zihin-tools-de-agente

Tools de agente — API e MCP externo

Workflow universal: leia o contrato (zihin://schemas/api_config) → monte → validate_schema_data (dry-run) → create_schema. Depois confira com list_agent_tools que a tool aparece como resolved.

api_config — chamar API externa

create_schema com schema_type: "api_config" e schema_data = { tool_definition, editor_schema }.

Regras críticas (violar = falha silenciosa em runtime):

1. editor_schema.api.endpoints[].name DEVE ser IGUAL a tool_definition.name — se diferirem, a tool quebra o roteamento interno sem erro claro.
2. Path parameters usam ${variavel} (com cifrão): path /items/${item_id} com item_id declarado no input_schema.
3. Auth canônico é { "prefix": "Bearer"|"Basic", "secret_ref": "<nome-do-secret>" } — o campo type é DEPRECATED. Para Basic, armazene o secret já em base64.
4. tool_definition.description mínimo 20 chars e deve dizer O QUE a tool faz e O QUE retorna (o LLM do agente decide por ela).
5. Recomendado: UMA tool por schema (uma operação por api_config) — múltiplos endpoints exigem action routing.
6. Timeout: api_config → editor_schema.api.timeout_ms (1000-120000, default 30000); MCP externo → config.call_timeout_ms por chamada de tool (≠ config.timeout, que é só conexão + listagem). Os dois alimentam o teto do executor. Retry de timeout é opt-in, não default: contra servidor pendurado, repetir só empilha espera.

Secrets: crie antes com create_secret (o valor em claro aparece SÓ na criação — guarde na hora). Liste com list_secrets (valores nunca expostos). Referencie via secret_ref.

Campos de transformação (opcionais por endpoint): default_body (valores fixos mergeados), locked_fields (campos que o LLM não pode sobrescrever — enforcement server-side), field_mapping (renomeia campos), array_fields, body_format: "array", defaults_from_context (auto-inject de valores do contexto do webhook quando o LLM não fornece — safety net autoritativo).