Identifica o tenant, role e plano da sessão MCP atual. Use para confirmar em qual organização e com qual nível de acesso você está conectado.

Lista agentes disponíveis para conversa. Retorna apenas agentes publicados do tenant.

Lista conversas recentes com um agente. Para usuários finais (role member), retorna apenas as próprias sessões; operadores (admin/editor/owner) veem as do tenant.

Retorna o histórico de mensagens de uma conversa. Filtra mensagens técnicas (tool calls) e retorna apenas interações user/assistant.

Envia uma mensagem a um agente e recebe a resposta completa (síncrono — sem streaming progressivo). O agente usa todas as tools configuradas (api_config, MCP externo).

Resposta inclui: response (texto), session_id (manter para contexto), tools_used (nomes), tool_calls (detalhes com name, duration_ms, success), execution_time_ms, model_used, execution_id (correlação com get_execution_diagnostics). outcome nomeia o desfecho real do turno (COMPLETED, LENGTH, CANCELLED, PAUSED, BUDGET_EXCEEDED, QUOTA_EXCEEDED, SESSION_BUSY, TIMEOUT ou ERROR); success só é true para COMPLETED e LENGTH (resposta cortada pelo teto de saída, mas entregue) — não confie só em success===true sem checar outcome se precisar distinguir bloqueio de sucesso pleno. outcome TIMEOUT com resposta = a chamada ao modelo passou do tempo; vem com timed_out: true e timeout_clock (first_signal = o provedor não começou a responder; idle = parou no meio; call = a chamada sem stream passou do teto). A resposta é a mensagem de falha do turno e o motivo fica na execução (get_execution_diagnostics). Turno que estoura o deadline do runtime retorna erro TURN_TIMEOUT com execution_id, session_id, timed_out: true e timeout_clock: turn — a execução fica registrada e a sessão pode ser retomada. Consumidor sob controle da plataforma (denylist do tenant, engajamento encerrado ou sessão suspensa) devolve { gated: true, gate, gate_action, response } SEM executar o agente — response é a mensagem fixa configurada, não saída do modelo.

IMPORTANTE: use o session_id retornado nas próximas mensagens para manter o contexto da conversa — ou, em integrações, session_from (a sessão é derivada de campos e você não precisa guardar id).

Integrações (só key admin/owner; em editor/member os campos voltam em ignored_fields): context = dados do sistema de origem que o agente LÊ (vão junto da mensagem, nunca no system prompt); bindings = argumentos AUTORITATIVOS das tools (defaults_from_context / ${context.x}; nunca vão ao modelo nem ficam gravados); session_from = nomes de campos de context/bindings que definem a conversa (mesmo hash do webhook session_strategy derive). A resposta traz accepted_fields e ignored_fields.

Retorna o perfil agregado de um consumidor (cross-session, cross-agent). Inclui display_name, canais usados, # de sessões, # de turns, lista de agentes que já interagiram, flags de produto e timestamps.

Lista paginada de consumidores do tenant atual, ordenada por mais recentes (last_seen_at desc). Útil pra dashboards "consumers ativos" ou ranking.

Lista as sessões de um consumidor específico (cross-agent, ordenadas por mais recentes). Complementa get_consumer_profile (que retorna só contadores agregados).

Envia uma mensagem manual ao consumer pelo MESMO canal outbound do agente (Twilio/Meta/webhook), sem invocar LLM e sem consumir quota. Útil quando atendimento humano assumiu uma sessão (use combinado com set_session_control mode=manual_handoff). Mensagem é gravada no conversation_history com metadata.author=human (F4) — assim o agente NÃO aprende a imitar esse padrão se reassumir. ENVIO ÚNICO: a mesma mensagem para a mesma sessão dentro de 60s é deduplicada (reenvio da tool call NÃO entrega 2x; a resposta vem com idempotent_replay=true). Para controlar a janela, passe idempotency_key — a mesma chave é aceita pelo REST POST /api/v1/sessions/:id/manual-message (header Idempotency-Key).

Cancela um turn de agente EM ANDAMENTO (mid-LLM, mid-tool, mid-stream). Útil quando agente entrou em loop caro, está respondendo errado, ou consumer pediu para parar. Diferente de set_session_control(suspended) que só bloqueia próximo turn — aqui interrompe o que já executa. Em multi-agent (Sprint 63), cancelar parent propaga em cascata via root_execution_id pra sub-agentes ativos.

Define o modo de controle de uma sessão específica (engaged | suspended | manual_handoff). Quando != engaged, o gate sessionControlGate curto-circuita o agent loop sem consumir quota. Use suspended pra pausar; manual_handoff pra sinalizar que atendimento humano assumiu. Com expires_at a pausa é temporária: no prazo a sessão volta sozinha para engaged.

Adiciona ou remove um consumidor do denylist universal do tenant (flag do_not_contact). Quando ativo, todas as mensagens desse consumer são bypassadas pelo Consumer Denylist Gate (sem invocação de LLM/Whisper, sem consumo de quota). Cross-agent — bloqueia em TODOS os agentes do tenant.

Lista todos os agentes do tenant. Retorna id, nome, status, tipo e metadados.

Retorna detalhes completos de um agente, incluindo schemas, triggers e configurações.

Cria um novo agente. Retorna o agente criado com seu UUID.

Atualiza campos de um agente existente. Envia apenas os campos que deseja alterar.

Arquiva um agente (soft delete). O agente pode ser restaurado depois.

Clona um agente existente com seus schemas. O clone é criado em status draft. Triggers podem ser clonados opcionalmente (desabilitados por padrão). Schemas inválidos geram warnings mas não bloqueiam a clonagem.

Publica ou despublica um agente para o tenant. Publicar torna o agente disponível para uso.

Lista todos os schemas (configurações) de um agente. Schemas definem persona, tools (API/DB/MCP), skills e workflow.

Retorna detalhes completos de um schema, incluindo schema_data.

Cria um novo schema para um agente. O schema_data varia conforme o tipo:

• persona_config: { editor_schema: { persona: { role, objective, tone, language, expertise, constraints, personality_traits, custom_guidelines } } }

• api_config: { tool_definition, editor_schema } — ATENÇÃO: endpoint.name DEVE ser igual a tool_definition.name. editor_schema.api.timeout_ms (1000-120000, default 30000) é a fonte única do quanto esperar: alimenta o AbortSignal do fetch e o teto do executor (doc loop-review/34 F1).

• workflow_config: { steps, transitions, conditions }

• skill_config: { skill: { name, instructions, priority? } } — instruções comportamentais transversais

• mcp_tool_config / mcp_resource_config: vínculo de tool/resource de MCP server (normalmente gerados pelo Builder) Triggers e CSPs NÃO são schemas: use create_trigger e create_csp.

WORKFLOW RECOMENDADO (evita erros de contrato): leia o resource zihin://schemas/{schema_type} (JSON Schema formal — o mesmo que o servidor valida), monte o schema_data, valide com validate_schema_data (dry-run), então crie.

Atualiza os dados (schema_data) de um schema existente — o nome que vale fica dentro de schema_data. Fluxo seguro com mais de um editor: get_schema → use a version como base_version → update_schema (com changelog). Para api_config: endpoint.name DEVE ser igual a tool_definition.name. Para persona_config: usar formato { editor_schema: { persona: { role, objective, ... } } }.

Desativa um schema (soft delete). O schema fica inativo mas pode ser reativado.

Lista todos os triggers do tenant. Triggers disparam execuções de agentes automaticamente.

Retorna detalhes completos de um trigger, incluindo configuração e estatísticas.

Cria um novo trigger para um agente. Contrato autoritativo: resource zihin://schemas/trigger_config (o mesmo JSON Schema que o servidor valida; envie apenas agent_id/name/trigger_type/trigger_config — tenant_id e ids são injetados pelo servidor). Use SOMENTE os enums abaixo — não invente valores como "public" para sender_access.mode. A configuração (trigger_config) depende do tipo:

• webhook: { query_extraction: { field: "chatInput" }, response_adapter: { format: "ebarn"|"slack"|"teams"|"twiml"|"raw" }, context_mapping: {}, session_strategy: { mode: "derive"|"ephemeral", fields?: [] }, sender_access?: { mode: "any"|"members"|"whitelist", identity_field?, match_column?, whitelist? }, execution?: { mode: "sync"|"async", ack_response?: { body, content_type }, callback?: { url, method, content_type, auth: { type, secret_ref }, body_template, response_transform }, message_buffer?: { enabled, window_ms, max_messages, concat_separator }, split_config?: { enabled, max_chunk_size, max_chunks, chunk_strategy: "paragraph"|"sentence"|"length", numbering, inter_chunk_delay_ms } } }

• email: { allowed_senders: [], subject_filter: "" }

• schedule: { cron: "0 9 * * *", timezone: "America/Sao_Paulo", query_template: "mensagem fixa", enabled_days?: ["monday","friday"], session_strategy?: { mode: "new" } (sessão nova a cada execução; é o único modo aceito para schedule), output?: { channel: "silent"|"webhook"|"callback"|"user" (user = SPEC D: entrega na sessão do chat nativo do usuário-alvo + push; exige target: { field: "user_id"|"consumer_key", value } e aceita push: { title, body }), webhook_url?: "https://..." (webhook), callback?: { url, method?, content_type?, auth?: { type, secret_ref }, body_template?, response_transform?: { strip_markdown, max_length } } (callback) } }

response_adapter.format determina defaults automáticos de transform: twiml → strip_markdown=true, max_length=4096. Override via execution.callback.response_transform. sender_access controla quem pode acionar o webhook: "any" (default), "members" (tenant_users), "whitelist" (lista explícita). message_buffer agrupa mensagens rápidas (popcorn) em uma janela de debounce via Redis antes de executar o agente. split_config divide respostas longas em múltiplos chunks para canais com limite de tamanho (WhatsApp, SMS).

Atualiza um trigger existente. Envia apenas os campos que deseja alterar.

Remove um trigger permanentemente. Esta ação não pode ser desfeita.

Habilita ou desabilita um trigger. Triggers desabilitados não disparam execuções.

Lista execuções de um trigger com paginação. Retorna histórico de execuções incluindo status, tempos e tokens.

Retorna detalhes enriquecidos de uma execução: session correlacionada, chamadas LLM, tool calls e métricas agregadas.

Navegação reversa: a partir de um session_id, retorna o trigger e a execução que originaram a sessão. Retorna has_trigger: false se a sessão não veio de trigger.

Lista os MCP servers vinculados a um agente. MCP servers conectam o agente a tools externas.

Retorna detalhes completos de um MCP server, incluindo configuração e capabilities.

Registra um novo MCP server para um agente. O agente poderá usar as tools expostas pelo server.

Transports: 'http' (Streamable HTTP; era do protocolo negociada automaticamente), 'stdio' (local, apenas dev). O 'sse' legado foi descontinuado (migração MCP 2026-07-28).

Combinações auth_method + config:

• none: config vazio {} (sem autenticação)

• bearer: { vault_secret_id: "NOME_DO_SECRET" } — o secret contém o token Bearer

• api_key: { vault_secret_id: "NOME_DO_SECRET", api_key_header: "X-Api-Key" } — header customizável

• tunnel: config vazio {} — token da plataforma resolvido via env var INTERNAL_TUNNEL_TOKEN (não vault). Usar para MCP servers via Zihin Tunnel

• oauth: { vault_secret_id: "OAUTH_CREDS", oauth_token_url: "https://..." } — OAuth2 client credentials

Campos opcionais em config: timeout (ms, 1000-120000 — só CONEXÃO + listagem de tools), call_timeout_ms (ms, 1000-120000 — timeout por CHAMADA de tool deste server; omitido = 30s global; alimenta também o teto do executor — doc loop-review/34 F1; retry de timeout é opt-in, não default), headers (object com headers extras), defaults_from_context (object com valores fixos injetados nas tools). Contrato: zihin://schemas/mcp_resource_config.

Atualiza configuração de um MCP server existente.

Remove um MCP server de um agente. As tools do server deixam de estar disponíveis.

Testa a conectividade de um MCP server externo com handshake REAL do protocolo (negociação de era) e listagem de tools. Retorna era/versão do protocolo, latência, tools disponíveis e classe de erro em falha. Use para diagnosticar problemas de conexão, auth, endpoint offline ou incompatibilidade de protocolo.

Invalida o cache de tools MCP. Use quando:

• Atualizou tools no MCP server externo e quer que o agente carregue as novas tools imediatamente

• Um MCP server está com problemas e quer forçar reconexão

• Quer limpar cache após alterar configuração de auth Funciona mesmo sem MCP Client ativo (reseta metadados no DB para forçar reconexão). Sem parâmetros: invalida todo o cache do tenant. Com mcp_server_id: invalida apenas o server especificado.

Lista todas as API Keys do tenant. Retorna id, nome, status, prefix, suffix, rate limit e estatísticas.

Cria uma nova API Key para o tenant. Retorna a chave completa (visível apenas neste momento).

Prefixes: zhn_live_ (produção), zhn_test_ (teste), zhn_dev_ (desenvolvimento). Diferença é semântica — mesmo comportamento. A chave gerada é exibida apenas uma vez — salve-a imediatamente.

Roles: admin (todas as tools + endpoints REST), editor (leitura + consumer), member (consumer only). "owner" é exclusivo de contas de usuário (tenant_users), não disponível para API Keys. Anti-escalação: não é possível criar key com role superior ao seu.

Se rate_limit_per_minute for omitido, usa o máximo do plano do tenant.

Retorna detalhes completos de uma API Key específica: nome, status, role, rate limits, estatísticas de uso e tenant associado.

Atualiza o rate_limit_per_minute de uma API Key existente. O novo valor é validado contra o plano do tenant. Evita a necessidade de revogar e recriar a chave apenas para ajustar o RPM.

Revoga uma API Key permanentemente. Triggers e webhooks que usam esta chave deixarão de funcionar.

Lista todas as políticas de segurança (CSPs) do tenant. Filtrável por escopo, tipo e status.

Retorna detalhes completos de uma política de segurança, incluindo regras e exceções.

Cria uma nova política de segurança contextual (CSP).

Escopos: tenant (global), team, agent, user — herança automática de cima para baixo. Tipos: schedule (horários), behavior (comportamento), data (dados), origin (origens), custom.

⚠️ Campo fora do contrato é ACEITO em silêncio (o schema permite propriedades extras) e fica INERTE. Não invente nome de campo: leia zihin://schemas/csp_config e use exatamente os de $defs.{tipo}Rules.

Exemplos de rules por tipo (todos os campos abaixo existem no contrato E são aplicados):

• schedule: { allowed_hours: { start: "08:00", end: "18:00" }, allowed_days: ["mon","tue","wed","thu","fri"], blocked_dates: ["2026-12-25"], timezone: "America/Sao_Paulo" }

• behavior: { max_tokens_per_request: 4096, max_iterations: 10, max_tool_calls: 20, must_not_tools: ["web_search","fetch_url"] }

• data: { sensitive_fields: ["cpf","email"], never_expose: ["password_hash"], restricted_entities: ["folha_pagamento"], restriction_message: "Não posso consultar esse dado." }

• custom: qualquer shape — é passado ao prompt como bloco de política sem interpretação do runtime.

Controle de superfície de tools (behavior):

• must_not_tools: nomes de tools que o agente NUNCA executa, mesmo carregadas. Filtrado antes do turno no runtime (inclusive no resume de HITL). É o único jeito de tirar uma tool nativa do agente sem desligar o recurso no tenant.

⚠️ policy_type "origin" NÃO é aplicado em runtime: nenhum entrypoint propaga o IP/origem do cliente até o loop, e countries/vpn/tor exigem provedor de geo que a plataforma não integra. A CSP é aceita e armazenada, mas não bloqueia nada — não use como controle de segurança.

Contrato formal: resource zihin://schemas/csp_config (envie só name/policy_type/scope/rules/... — tenant_id é injetado pelo servidor).

Aprovação por escopo (OE-2a, só chat nativo) — campos de behavior:

• require_approval_for: array de string (nome de tool) ou objetos { tool_name } | { mcp_server_id } | { source: "mcp"|"api"|"db" } — tools casadas exigem aprovação HITL antes de executar

• approval_policy_id: UUID de política criada via create_approval_policy — define QUEM aprova (sem ela, aprova o próprio solicitante) Ex: behavior: { require_approval_for: ["create_deal", { source: "db" }], approval_policy_id: "" }

Atualiza uma política de segurança existente. Envia apenas os campos que deseja alterar.

⚠️ rules é SUBSTITUÍDO, não mesclado: reenvie os campos que quer manter. Campo fora do contrato é aceito em silêncio e fica inerte — confira em zihin://schemas/csp_config.

Campos de behavior mais usados:

• must_not_tools: blocklist de tools que o agente nunca executa (único controle de superfície de tools).

• max_iterations / max_tool_calls / max_tokens_per_request: tetos de execução por turno.

• require_approval_for + approval_policy_id: aprovação por escopo (OE-2a, só chat nativo — ver create_approval_policy).

Remove uma política de segurança permanentemente.

Ativa ou desativa uma política de segurança. CSPs inativas não são aplicadas.

Retorna as políticas efetivas para um contexto específico, considerando herança de escopos. A resolução segue: tenant → team → agent → user (mais específico sobrescreve).

Retorna visão completa do agente: dados, schemas ativos, triggers, CSPs vinculadas e configuração de publicação.

Lista todas as ferramentas resolvidas de um agente (api_config + MCP tools + core tools). Mostra o que o agente efetivamente terá disponível em runtime, com nome, descrição e parâmetros.

Valida todos os schemas de um agente. Verifica api_config (endpoints, auth). Retorna schemas válidos, inválidos e warnings — útil antes de publicar o agente. Também cruza persona, skills e workflow com a SUPERFÍCIE EFETIVA de tools (tools carregadas menos must_not_tools da CSP): toda tool citada no texto que o agente não pode chamar vira warning em surface.cited_outside (reason blocked_by_csp ou not_in_surface). É o que evita o agente "ensinar" uma tool que a CSP bloqueou e responder "ferramenta indisponível" ao usuário.

Retorna métricas agregadas de um agente: chamadas LLM (calls, errors, success_rate, tokens, custo, latência p50/p95 — agregação em SQL, sem cap de linhas), uso de tools (amostra das últimas 2000 chamadas, com flag sample_truncated) e sessões. Útil para monitorar performance e custos de um agente em produção. Para saúde de infra do tenant (erros sem agente), use get_tenant_health.

Valida schema_data sem salvar (dry-run) — MESMA validação Ajv do create_schema/update_schema. Use SEMPRE antes de criar/atualizar schemas para evitar tentativa e erro. O contrato formal de cada tipo está no resource zihin://schemas/{schema_type}. Retorna erros, warnings e infos de validação.

Ativa ou desativa um schema sem deletá-lo. Schemas inativos não são carregados no runtime do agente.

Testa um trigger enviando um payload de exemplo. Executa o agente vinculado e retorna o resultado. Útil para verificar se webhook, schedule ou email trigger estão configurados corretamente. ATENÇÃO: executa o agente de verdade (não é dry-run), mas usa uma sessão temporária.

Retorna trace de diagnóstico completo de uma execução: timeline cronológica de LLM calls e tool calls, com tokens, latência, modelo usado e finish_reason. Cada llm_call traz cached (tokens LIDOS do cache, com desconto) e cache_creation (tokens ESCRITOS no cache, cobrados a ~1,25× a entrada); summary.cache_creation_tokens soma a escrita do turno — sem esse campo o cost_usd parece não fechar com a tabela de preços (era a #344). execution.metadata traz a correlação que o caller do /stream mandou (trace_id, correlation_id…), ou null. Use o execution_id (campo id do agent_executions) ou root_execution_id retornado pelo chat_with_agent.

Lista todos os secrets do tenant (sem expor valores). Retorna nome, categoria, descrição, uso e timestamps. Use o campo "name" como secret_ref em api_config.

Cria um novo secret criptografado para o tenant. O valor é criptografado com AES-256-GCM e armazenado no vault. IMPORTANTE: O valor plaintext não será retornado após criação — salve-o antes.

Após criar, use o "name" como:

• secret_ref em api_config auth (ex: "ZIGMA_API_KEY")

• vault_secret_id em connection_config (ex: "DB_PASSWORD_PROD")

Atualiza o valor de um secret existente. O novo valor é criptografado e substitui o anterior.

Remove um secret permanentemente. ATENÇÃO: api_config que referenciam este secret deixarão de funcionar.

Lista o histórico de versões de um recurso (agent, schema, trigger ou mcp_server). Cada versão registra uma alteração com before/after.

Retorna detalhes de uma versão específica de um recurso, incluindo dados before/after e campos alterados.

Compara duas versões de um recurso, mostrando diff campo a campo entre elas.

Restaura um recurso individual para uma versão anterior. O trigger grava automaticamente a nova versão resultante do rollback.

Timeline completa de todas as alterações de um agente (schemas, triggers, MCP servers). Filtrável por tipo de recurso.

Lista snapshots de publicação de um agente. Cada snapshot captura o estado completo no momento da publicação.

Retorna detalhes completos de um snapshot de publicação, incluindo estado do agente, schemas, triggers e MCP servers.

Restaura um agente completo para um snapshot de publicação anterior. Restaura agent, schemas, triggers e MCP servers.

Lista memórias persistentes de um agente. Retorna fatos, preferências, instruções e contexto armazenados.

Remove (soft delete) uma memória específica de um agente. Requer agent_id, memory_key e user_key. Chaves com prefixo "_" são controle da plataforma e não podem ser removidas por aqui.

Retorna o status atual do serviço de agendamento (SchedulerService). Mostra jobs ativos, próximas execuções e estatísticas.

Define (action=canned) ou reabre (action=engage) o engajamento de um agente com um consumidor. Com canned, a plataforma responde message a esse consumidor sem acionar o agente, até expirar. user_key = identidade do consumidor (telefone só-dígitos em WhatsApp; idUsuario em webhook; user_id no chat).

Retorna o orçamento (teto de gasto em USD) e o saldo do ciclo atual de um agente. O budget conta TODAS as chamadas LLM do agente, incluindo BYOK. unlimited=true significa sem teto configurado.

Lista saldo/teto de gasto (USD) de TODOS os agentes do tenant em batch. Útil para visão de burn-rate consolidada sem N+1.

Define ou remove o teto de gasto (USD) de um agente. limit_usd=null remove o teto (ilimitado). É também o laço de recuperação: elevar o teto faz um agente parado por budget voltar a rodar no próximo turno. Retorna o saldo recalculado.

Lista pendências de aprovação HITL do tenant (ações de tools aguardando aprovação de usuário). admin/owner veem todas; editor vê apenas as próprias solicitações e o que pode aprovar. A decisão (aprovar/rejeitar) acontece no chat do aprovador, não por esta API.

Lista políticas de aprovação do tenant (quem aprova o quê). Políticas são referenciadas por CSPs via behavior.approval_policy_id.

Retorna uma política de aprovação por ID (nome, stages com aprovadores, is_active).

Cria uma política de aprovação (quem aprova ações de tools sob HITL). stages[].approvers aceita {type:"user", id:""} ou {type:"role", role:"admin"}. Para ativar em um agente: vincule na CSP via behavior.approval_policy_id + behavior.require_approval_for. Contrato formal: resource zihin://schemas/approval_policy (envie só name/description/stages — tenant_id e created_by são injetados pelo servidor).

Atualiza uma política de aprovação (nome, descrição, stages, is_active). is_active=false desativa a política. Envie apenas os campos a alterar.

Retorna pares orquestrador→subagente que INVOCARAM de fato (via invoke_agent), com contagem de invocações e último uso. Complementa allowed_invoke_agents (que é "pode invocar").

Saúde de infra no nível do tenant: erros NÃO atribuíveis a um agente específico (rate limit, auth de provider, infra), agrupados por código canônico. Complementa get_agent_metrics (que é por agente).

Trace hierárquico de uma execução multi-agente a partir do root_execution_id: árvore supervisor→subagentes com fases, tool calls e custo por nó. Use get_session_agent_tree quando tiver o session_id em vez do execution_id.

Árvore de agentes de uma SESSÃO (linhagem por parent_session_id, #227): supervisor + subagentes de todos os turnos. Funciona em sessões multi-turno onde o trace por execução não fecha a árvore.