O bloco Agent roda um modelo dentro de um workflow. Você dá instruções, contexto e tools; o modelo raciocina sobre a entrada, chama tools conforme necessário e retorna texto puro ou JSON estruturado que blocos posteriores leem por referência. A maioria dos workflows é construída em torno de um ou mais blocos Agent.
Um agente e um bloco Agent são relacionados, mas distintos. Um agente é um workflow inteiro que raciocina e age por conta própria; um bloco Agent é um passo de raciocínio dentro dele. O agente mais simples é um único bloco Agent com tools, e os maiores encadeiam vários com outros blocos. Veja Agentes.
Configuração
Messages
As mensagens enviadas ao modelo. Cada mensagem tem um role: System define o trabalho e as regras do agente, User dá a entrada sobre a qual agir. Insira uma connection tag para passar uma saída anterior, como <start.input>.
You are a support assistant for an analytics product.
Answer in two sentences, cite the doc you used, and never guess a price.Model
O modelo que roda o passo. O padrão é claude-sonnet-4-6. Digite ou escolha qualquer modelo de OpenAI, Anthropic, Google, xAI, Groq, Cerebras, DeepSeek, Azure, AWS Bedrock, Google Vertex ou OpenRouter, ou um modelo local via Ollama ou VLLM.
Files
Arquivos para o modelo ler: imagens para um modelo com visão, ou documentos como texto. Envie-os no bloco, ou passe um arquivo de um bloco anterior, como um upload trigger ou uma resposta de API, com uma connection tag.
Tools
Capacidades que o agente pode chamar enquanto roda: buscar numa base de conhecimento, enviar uma mensagem no Slack, rodar um Function, chamar qualquer uma das integrações, ou usar uma custom tool ou servidor MCP que você adicionou. O modelo decide quais chamar e quando. (Para de onde as tools vêm e quando usar cada uma, veja Agentes.) Cada tool tem um controle de uso:
- Auto. O modelo a chama quando o contexto justifica.
- Force. O modelo deve chamá-la em toda execução.
- None. A tool fica oculta do modelo, o que a desabilita sem removê-la do bloco.
Skills
Skills de agentes que o agente pode carregar sob demanda: pacotes reutilizáveis de instruções como um padrão de código ou um playbook de suporte. Só os nomes das skills ficam no contexto de início, e o agente carrega as instruções completas quando decide que uma skill é relevante.
Memory
Memória de conversa embutida, mantida entre execuções por um conversation ID:
- None. Cada execução é independente.
- Conversation. O histórico completo daquele conversation ID.
- Sliding window (messages). As N mensagens mais recentes.
- Sliding window (tokens). Mensagens recentes até um orçamento de tokens.
A memória precisa de um conversation ID para persistir entre execuções. Para memória compartilhada entre workflows ou gerenciada como store próprio, use o bloco Memory.
Response Format
Dê ao agente um JSON Schema para forçar saída estruturada. A resposta fica restrita ao schema, e cada campo vira sua própria saída que você lê pelo nome, como <agent.sentiment>. Sem response format, o agente retorna texto puro em content.
{
"name": "user_analysis",
"schema": {
"type": "object",
"properties": {
"sentiment": { "type": "string", "enum": ["positive", "negative", "neutral"] },
"confidence": { "type": "number", "minimum": 0, "maximum": 1 }
},
"required": ["sentiment", "confidence"]
}
}Advanced
Algumas configurações ficam em advanced, ou aparecem só para modelos que as suportam:
- Temperature. Quão variada é a saída. Mantenha baixa (0–0.3) quando precisa de precisão e repetibilidade, média (em torno de 0.5) para o dia a dia, mais alta (0.7+) quando quer variedade criativa.
- Max output tokens. Limita o comprimento da resposta. O padrão é o limite completo do modelo.
- Reasoning effort / Thinking level. Para modelos com raciocínio estendido, quanto o modelo pensa antes de responder. Mais alto é mais completo, mas mais lento e custa mais tokens.
- API key. Sua chave para o provedor escolhido. Oculta no Zoen hospedado, que fornece uma.
Saídas
Depois que o agente roda, blocos posteriores leem o resultado pelo nome:
| Saída | O que é |
|---|---|
<agent.content> | A resposta: texto, ou o objeto estruturado quando um response format está definido |
<agent.tokens> | Uso de tokens, um objeto { input, output, total } |
<agent.toolCalls> | As tools que o agente chamou, com suas entradas e resultados |
<agent.model> | O modelo que rodou o passo |
<agent.cost> | Custo estimado da chamada |
Quando um response format está definido, seus campos são legíveis diretamente, como <agent.sentiment>.
Exemplo
Um workflow que lê uma mensagem de cliente e a classifica:
O Agent lê a mensagem do Start com <start.input> e retorna um resultado que blocos posteriores leem como <agent.content>.
Boas práticas
- Escreva uma system message clara. Defina o papel, o tom e os limites do agente. Instruções específicas produzem saída mais confiável que um prompt vago.
- Combine o modelo e a temperature com a tarefa. Use um modelo mais forte e temperature mais baixa (0–0.3) para precisão; suba a temperature para saída criativa ou variada.
- Dê ao agente só as tools de que precisa. Tools demais diluem as escolhas. Para trabalhos que não se sobrepõem, use um segundo bloco Agent em vez de sobrecarregar um.
- Use um response format quando um bloco downstream precisa de campos específicos. Ele garante a forma, e você lê cada campo como
<agent.field>.