Defina seu agente

Um agente é uma configuração reutilizável e versionada que define persona e capacidades. Ele agrupa o modelo, o prompt do sistema, as ferramentas, os servidores MCP e as skills que moldam como o Claude se comporta durante uma sessão.

Crie o agente uma vez como um recurso reutilizável e referencie-o por ID cada vez que você iniciar uma sessão. Os agentes são versionados e mais fáceis de gerenciar em várias sessões.



Campos de configuração do agente

Você também pode substituir model, system, tools, mcp_servers e skills para uma única sessão sem alterar o agente. Consulte Substituir a configuração do agente para uma sessão.



Criar um agente

O exemplo a seguir define um agente de codificação que usa o Claude Opus 4.8 com acesso ao conjunto de ferramentas de agente pré-construído. O conjunto de ferramentas permite que o agente escreva código, leia arquivos, pesquise na web e muito mais. Consulte a referência de ferramentas do agente para a lista completa de ferramentas compatíveis.

Os exemplos usam curl, a CLI ant ou um dos SDKs. Se você ainda não configurou um deles, o quickstart aborda a instalação e a configuração do cliente.

agent=$(ant beta:agents create \
  --name "Coding Assistant" \
  --model '{id: claude-opus-4-8}' \
  --system "You are a helpful coding agent." \
  --tool '{type: agent_toolset_20260401}' \
  --format json)

AGENT_ID=$(jq -r '.id' <<< "$agent")
AGENT_VERSION=$(jq -r '.version' <<< "$agent")

A resposta ecoa sua configuração e adiciona os campos id, type, version, created_at, updated_at e archived_at. O version começa em 1 e é incrementado cada vez que uma atualização altera o agente.

{
  "id": "agent_01HqR2k7vXbZ9mNpL3wYcT8f",
  "type": "agent",
  "name": "Coding Assistant",
  "model": {
    "id": "claude-opus-4-8",
    "speed": "standard"
  },
  "system": "You are a helpful coding agent.",
  "description": null,
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "default_config": {
        "permission_policy": { "type": "always_allow" }
      }
    }
  ],
  "skills": [],
  "mcp_servers": [],
  "metadata": {},
  "version": 1,
  "created_at": "2026-04-03T18:24:10.412Z",
  "updated_at": "2026-04-03T18:24:10.412Z",
  "archived_at": null
}

O default_config no conjunto de ferramentas mostra sua política de permissão padrão, always_allow, que se aplica a menos que você configure uma.



Atualizar um agente

Atualizar um agente gera uma nova versão quando a configuração muda. O campo version é obrigatório e deve corresponder à versão atual do agente, para que você sempre atualize a partir de um estado conhecido. Uma incompatibilidade de versão retorna um 409, e atualizações em agentes arquivados são rejeitadas.

ant beta:agents update \
  --agent-id "$AGENT_ID" \
  --version "$AGENT_VERSION" \
  --system "You are a helpful coding agent. Always write tests."



Semântica de atualização

• Campos omitidos são preservados. Você só precisa incluir os campos que deseja alterar.

• Campos escalares (model, system, name, description) são substituídos pelo novo valor. system e description podem ser limpos passando null. model e name são obrigatórios e não podem ser limpos.

• Campos de array (tools, mcp_servers, skills) são totalmente substituídos pelo novo array. Para limpar um campo de array completamente, passe null ou um array vazio.

• multiagent é substituído como um todo, incluindo sua lista agents. Passe null para limpá-lo.

• Metadata é mesclado no nível de chave. As chaves que você fornece são adicionadas ou atualizadas. As chaves que você omite são preservadas. Para excluir uma chave específica, defina seu valor como null.

• Detecção de no-op. Se a atualização não produzir nenhuma mudança em relação à versão atual, nenhuma nova versão é criada e a versão existente é retornada.

• Listas de coordenadores não são atualizadas. Coordenadores que referenciam este agente em sua lista multiagent.agents mantêm a versão que foi fixada quando o coordenador foi criado ou atualizado pela última vez, mesmo que a referência omita version. Para delegar à nova versão, atualize o coordenador para que sua lista a referencie.



Ciclo de vida do agente



Listar versões

Busque o histórico completo de versões para acompanhar como um agente mudou ao longo do tempo. Os resultados são paginados, e os exemplos de SDK buscam todas as páginas automaticamente.

ant beta:agents:versions list --agent-id "$AGENT_ID"



Arquivar um agente

Arquivar torna o agente somente leitura e não pode ser desfeito. Sessões existentes continuam a ser executadas, mas novas sessões não podem referenciar o agente. A resposta define archived_at com o timestamp de arquivamento.

ant beta:agents archive --agent-id "$AGENT_ID"



Próximos passos