Agent

O bloco Agent executa um modelo dentro de um workflow. Você fornece instruções, contexto e tools; o modelo raciocina sobre a entrada, chama as tools que precisar e devolve texto simples ou JSON estruturado que os blocks seguintes leem por referência. A maioria dos workflows é construída em torno de um ou mais blocks Agent.

Um agente e um bloco Agent são coisas relacionadas, mas distintas. Um agente é um workflow inteiro que raciocina e age por conta própria; um bloco Agent é um único passo de raciocínio dentro dele. O agente mais simples é um único bloco Agent com tools, e os maiores combinam vários deles com outros blocks. Veja Agentes.

Configuração

Messages

As mensagens enviadas ao modelo. Cada mensagem tem um papel: System define a função e as regras do agente, User entrega a entrada sobre a qual ele deve 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 executa o passo. O padrão é claude-sonnet-4-6. Digite ou escolha qualquer modelo da 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 para texto. Faça o upload no próprio block, ou passe um arquivo de um block anterior — como um trigger de upload ou uma resposta de API — com uma connection tag.

Tools

Capacidades que o agente pode chamar durante a execução: buscar em uma base de conhecimento, enviar uma mensagem no Slack, executar uma Function, chamar qualquer uma das integrações ou usar uma tool personalizada ou servidor MCP que você adicionou. O modelo decide qual chamar e quando. (Para saber de onde vêm as tools e quando usar cada uma, veja Agentes.) Cada tool tem um controle de uso:

• Auto. O modelo chama quando o contexto justifica.
• Force. O modelo precisa chamar em toda execução.
• None. A tool fica oculta para o modelo, o que a desativa sem removê-la do block.

Skills

Skills de agente que o agente pode carregar sob demanda: pacotes de instruções reutilizáveis, como um padrão de código ou um manual de atendimento. Apenas 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 nativa, mantida entre execuções por um ID de conversa:

• None. Cada execução é independente.
• Conversation. O histórico completo daquele ID de conversa.
• Sliding window (messages). As N mensagens mais recentes.
• Sliding window (tokens). Mensagens recentes até um limite de tokens.

A memória precisa de um ID de conversa para persistir entre execuções. Para uma memória compartilhada entre workflows ou gerenciada como um repositório próprio, use o block Memory.

Response Format

Dê ao agente um JSON Schema para forçar saída estruturada. A resposta fica restrita ao schema, e cada campo se torna uma saída própria que você lê pelo nome, como <agent.sentiment>. Sem um response format, o agente devolve texto simples 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 apenas para modelos que as suportam:

• Temperature. O quanto a saída varia. Mantenha baixa (0–0,3) quando você precisa de precisão e repetibilidade, no meio (perto de 0,5) para o trabalho do dia a dia, e mais alta (0,7+) quando quer variedade criativa.
• Max output tokens. Limita o tamanho da resposta. O padrão é o limite total do modelo.
• Reasoning effort / Thinking level. Para modelos com raciocínio estendido, quanto o modelo pensa antes de responder. Níveis mais altos são mais completos, mas mais lentos e custam mais tokens.
• Prompt caching. Para modelos Claude da Anthropic, reaproveita o system prompt e as definições de tools entre execuções em vez de reprocessá-los toda vez. A entrada em cache custa um décimo da taxa normal, mas escrever o cache custa 1,25x — então deixe desligado para execuções isoladas e ligue quando o mesmo agente roda repetidamente. O cache cobre um prefixo só se ele alcançar 1.024 tokens (2.048 no Haiku) — abaixo disso a Anthropic ignora e nada muda. As entradas expiram após cinco minutos sem uso.
• API key. Sua chave para o provedor escolhido. Fica oculta no Studio hospedado, que fornece uma.

OpenAI e Gemini fazem cache automaticamente sem custo extra e não exigem configuração; o desconto já está refletido no que é cobrado de você.

Saídas

Depois que o agente executa, os blocks seguintes leem o resultado pelo nome:

Quando há um response format definido, seus campos podem ser lidos diretamente, como <agent.sentiment>.

Raciocínio e chamadas de tools em tempo real

Enquanto um agente executa, o Studio pode transmitir ao vivo o raciocínio e o ciclo de vida das tools — o terminal do workflow builder sempre os mostra, e um chat deployado os mostra quando a configuração Include thinking e o opt-in de protocolo do cliente concordam. O que realmente é transmitido depende do modelo: modelos marcados com deltas completos ou resumos transmitem o raciocínio quando um Thinking level ou Reasoning effort está definido (modelos reasoner da DeepSeek sempre raciocinam); um modelo marcado como "Não transmitido" pensa internamente, mas o provedor não libera o texto.

Os chips de chamada de tool em tempo real são transmitidos para modelos OpenAI, Anthropic, Azure Anthropic, Google, Vertex AI, DeepSeek, Groq, AWS Bedrock. Outros provedores executam as tools sem chips ao vivo e projetam a resposta final consolidada quando a execução termina; eles não pedem ao modelo para gerar essa resposta de novo só para criar um stream.

Exemplo

Um workflow que lê uma mensagem recebida de um cliente e a classifica:

O Agent lê a mensagem do Start com <start.input> e devolve um resultado que os blocks seguintes 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ídas mais confiáveis do que um prompt vago.
• Ajuste modelo e temperature à tarefa. Use um modelo mais forte e temperature baixa (0–0,3) para precisão; aumente a temperature para saídas criativas ou variadas.
• Dê ao agente apenas as tools de que ele precisa. Tools em excesso diluem as escolhas dele. Para trabalhos que não se sobrepõem, use um segundo bloco Agent em vez de sobrecarregar um só.
• Use um response format quando um block seguinte precisar de campos específicos. Ele garante o formato, e você lê cada campo como <agent.field>.