Referência do config do agente (JSON)

O config do agente é o JSON que define o agente de um projeto no LangChain Agent: o modelo, o prompt, as tools e os ajustes. O editor do painel (menu Agente) e o bloco langchain.config do template mexem no mesmo JSON. Esta página lista todos os campos. Só dois campos são obrigatórios: model.provider e model.name. Todo o resto tem padrão, e campo omitido vale o padrão. Grave só o que você quer diferente do padrão.

A estrutura em uma olhada

{
  "name": "…",
  "model": { … },
  "instructions": { … },
  "tools": [ … ],
  "settings": { … },
  "agents": []
}

Bloco	O que faz	Onde aprender
`name`	Nome interno do agente. O lead não vê.	—
`model`	Provider, modelo, chave, temperatura, Max Tokens, raciocínio, tempo limite, tentativas e modelos de reserva (fallback).	Providers, Escolher o modelo, Resiliência
`instructions`	O prompt do agente e se os dados do lead vão junto a cada mensagem.	Prompt, Contexto injetado
`tools`	Tudo o que o agente pode usar: chamadas de API (incluindo as ações da Zatten), ações de apps de Integrações, servidores MCP, skills e a lista de tarefas.	Tools: visão geral
`settings`	Ajustes do comportamento: erro e transbordo, limite de chamadas, dados pessoais, resumo e limpeza de contexto, novas tentativas de tool, filtro de tools, transcrição de áudio e LangSmith.	Ver a tabela abaixo
`agents`	Reservado para vários agentes no futuro. Sem efeito hoje.	—

Os blocos de `settings`

Bloco	O que faz	Ligado por padrão?	Onde aprender
`error_handling`	Mensagem ao lead e transbordo quando todos os modelos falham.	Sim	Resiliência
`call_limit`	Teto de chamadas ao modelo por mensagem e por conversa.	Não	Limites e segurança
`pii_protection`	Esconde ou bloqueia dados pessoais.	Não	Limites e segurança
`human_approval`	Pausa para aprovação humana.	Não, e fica sempre desligado	Limites e segurança
`summarization`	Resume o histórico de conversas longas.	Não	Conversas longas
`context_editing`	Limpa resultados antigos de tools.	Não	Conversas longas
`tool_retry`	Tenta de novo uma tool que falhou.	Não	Tools: visão geral
`tool_selector`	Mostra ao modelo só as tools ligadas à mensagem.	Não	Limites e segurança
`transcription`	Transforma áudio do lead em texto.	Sim	Mídia
`tracing`	Envia o passo a passo do agente ao LangSmith.	Não	LangSmith

Regras que valem para o config inteiro

Omitido = padrão. Mandar settings: {} é igual a não mandar nada: valem os padrões, inclusive error_handling e transcription ligados.
Chave desconhecida não dá erro. O agente ignora a chave e a guarda intacta. É assim que o painel guarda _id e _zatten dentro de cada tool. A contrapartida: um erro de digitação também não dá erro. "inject_contex": true passa na validação e o recurso simplesmente não liga.
Valores fora da lista invalidam. Um type de tool, um provider ou um enum com valor que não existe faz o agente inteiro deixar de funcionar.
Tempo é sempre em segundos (timeout_seconds, initial_delay, max_delay).
Toda escrita cria uma versão não publicada. Quem publica é uma pessoa, no painel (Versões e publicação).
Pelo MCP, o config enviado substitui o config inteiro. Parta do que o get_template devolveu e mude só o necessário.

O que o template não grava

Ao aplicar o bloco langchain (pelo MCP ou pela API de template), a Zatten ajusta estes campos e devolve uma nota quando muda algo:

Campo	O que acontece
`model.api_key` e `settings.tracing.api_key`	Preservadas só quando o campo está ausente. Sem o campo, a chave já gravada no projeto continua. Com `""` (texto vazio), o vazio é gravado por cima e o agente para de responder. Omita o campo ou devolva intacto o valor que o `get_template` trouxe. Nunca mande `""` nem um texto de exemplo no lugar da chave.
`tools[].headers`	Preservados quando a tool chega sem cabeçalhos (campo ausente ou `{}`) e tem o mesmo `_id` de uma tool já gravada. Um cabeçalho com valor vazio é gravado vazio.
`settings.human_approval.enabled` e `tools[].require_approval`	Sempre gravados `false`. A aprovação pausa a conversa esperando alguém aprovar, e o painel não tem tela para isso: o lead ficaria sem resposta.
`settings.tracing.metadata.attendant_id`	Reescrito com o projeto de destino, para os traces no LangSmith ficarem no projeto certo.

Também não grave:

model.provider: "custom": desativado; o agente não valida.
tools[].type: "native": removido. As ações da Zatten são tools http (Ações da Zatten).
settings.tracing.provider: não existe. O tracing é sempre LangSmith.

Campos sem efeito hoje

São aceitos na validação, mas nada no agente os usa. Não prometa o recurso a partir deles.

Campo	Por quê
`description` (raiz)	Só metadado. O agente não lê.
`agents`	Reservado para vários agentes. Sem contrato definido.
`tools[].allowed_tools` e `tools[].blocked_tools` (MCP)	O filtro não existe. Toda tool do servidor MCP chega ao modelo, diga a lista o que disser (Servidores MCP).
`settings.human_approval.mode: "all_responses"` (o padrão) e `"custom"`	Não implementados. E a aprovação fica sempre desligada de qualquer forma.
`tools[].name` de `builtin` diferente de `todo_list`	Aceito e ignorado.
`settings.tracing.enabled: true` sem `api_key`	Valida e não liga.

Combinações que o agente recusa

Passam campo a campo, mas o config inteiro falha:

Quando	Exige
`model.fallback.enabled: true`	Pelo menos um item em `model.fallback.models`
`settings.call_limit.enabled: true`	`per_message` ou `per_conversation`
`settings.summarization.enabled: true`	`trigger_tokens` ou `trigger_messages`
`settings.pii_protection.enabled: true`	Pelo menos uma regra em `rules`
`settings.transcription.provider: "custom"`	`base_url`

E estas não falham, mas não funcionam, sem aviso:

settings.error_handling.handoff_tool com o nome de uma tool que não existe ou que não é http: o lead recebe a mensagem de erro, mas não é transferido.
Uma propriedade "type": "array" sem items em parameters de uma tool http: modelos do Google (Gemini) recusam toda chamada do agente (Tool HTTP).

Referência campo a campo

As tabelas completas ficam abaixo. Status: ativo (o agente usa), sem efeito hoje (aceito e ignorado), sempre false (o template força desligado).

Exemplo de config mínimo válido

Um agente no OpenRouter, com prompt, dados do lead no contexto e o transbordo automático quando o modelo falha. A chave não vai no exemplo: num projeto que já roda, a chave gravada é mantida; num projeto novo, preencha no painel (Providers).

{
  "name": "atendimento_clinica",
  "model": {
    "provider": "openrouter",
    "name": "fabricante/modelo"
  },
  "instructions": {
    "system_prompt": "Você é a recepcionista da Clínica Exemplo. Responda em português, com frases curtas.",
    "inject_context": true
  },
  "tools": [],
  "settings": {
    "transcription": { "language": "pt" }
  }
}

O menor config que o agente aceita é só {"model": {"provider": "…", "name": "…"}}. Troque fabricante/modelo por um modelo real (Escolher o modelo). Para uma tool de verdade nesse config, veja os exemplos em Tool HTTP e Ações da Zatten.

Armadilhas

Erro de digitação não dá erro. Uma chave escrita errado é ignorada em silêncio e o recurso fica desligado. Confira os nomes nesta página.
Gravar settings inteiro “por garantia” congela os padrões no JSON. Grave só o que mudou.
Mandar a chave vazia. "api_key": "" apaga a chave gravada e o agente para de responder. Para manter a chave atual, omita model.api_key (e settings.tracing.api_key) ou devolva o valor que o get_template trouxe.
allowed_tools e blocked_tools no MCP parecem um controle de segurança, mas não filtram nada.
openai/whisper-1 com provider OpenAI direto faz toda transcrição falhar. Use whisper-1 (Mídia).
Skills somem em conversa longa com context_editing ou tool_selector ligados, se load_skill não estiver em exclude_tools e always_include (Skills).
handoff_tool com nome errado não transfere o lead, sem aviso.
Valor fora da lista (provider custom, tool native, enum inventado) derruba o agente inteiro: nenhuma mensagem é respondida.

Para saber mais

Como o agente funciona
Referência do template (o bloco langchain)
Versões e publicação
Testar o agente
LangChain: middlewares prontos
Termos para buscar: “LangChain create_agent middleware”, “JSON Schema object properties items”, “OpenRouter provider routing”, “LangSmith tracing project”.

Fundamentos

Modelo

Prompt e conversa

Tools

Capacidades

Operar

Referência do config do agente (JSON)

A estrutura em uma olhada

Os blocos de `settings`

Regras que valem para o config inteiro

O que o template não grava

Campos sem efeito hoje

Combinações que o agente recusa

Referência campo a campo

Exemplo de config mínimo válido

Armadilhas

Para saber mais

​A estrutura em uma olhada

​Os blocos de settings

​Regras que valem para o config inteiro

​O que o template não grava

​Campos sem efeito hoje

​Combinações que o agente recusa

​Referência campo a campo

​Exemplo de config mínimo válido

​Armadilhas

​Para saber mais

A estrutura em uma olhada

Os blocos de `settings`

Regras que valem para o config inteiro

O que o template não grava

Campos sem efeito hoje

Combinações que o agente recusa

Referência campo a campo

Exemplo de config mínimo válido

Armadilhas

Para saber mais