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 muitas sessões.

Campos de configuração do agente

Você também pode sobrescrever model, system, tools, mcp_servers e skills para uma única sessão sem alterar o agente. Um nível de effort definido dentro de uma sobrescrita de model por sessão não é aplicado e, como a sobrescrita substitui o objeto model do agente por completo, uma sessão criada com uma sobrescrita de model é executada no nível de esforço padrão do modelo; para executar em um nível de esforço específico, defina effort no agente e não sobrescreva model para essa sessão. Consulte Sobrescrever 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 5 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 de agente para a lista completa de ferramentas suportadas.

Os exemplos usam curl, a CLI ant ou um dos SDKs. Se você ainda não configurou um deles, o início rápido cobre a instalação e a configuração do cliente.

agent=$(ant beta:agents create --format json < coding-assistant.agent.yaml)

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

name: Coding Assistant
model:
  id: claude-opus-5
system: You are a helpful coding agent.
tools:
  - type: agent_toolset_20260401

A resposta ecoa sua configuração e adiciona os campos id, type, version, created_at, updated_at e archived_at, e preenche os campos de model que você omitir, como effort, com seus valores padrão. 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-5",
    "effort": { "type": "high" },
    "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": [],
  "multiagent": null,
  "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.

Fixar a geo de inferência

Assim como speed e effort, inference_geo é definido por meio da forma de objeto de model: passe model como um objeto e defina inference_geo junto com id. O campo aceita "us" ou "global". Quando não está definido, cada requisição ao modelo segue a geo de inferência padrão do workspace no momento em que é atendida. Consulte Residência de dados para os controles de geo no nível do workspace e preços.

O exemplo a seguir fixa um agente na inferência dos EUA e imprime o valor de inference_geo ecoado no objeto model da resposta:

agent=$(ant beta:agents create --format json < geo-pinned.agent.yaml)

echo "Inference geo: $(jq -r '.model.inference_geo' <<< "$agent")"

name: Geo-pinned assistant
model:
  id: claude-opus-5
  inference_geo: us
system: You are a helpful assistant.

Uma fixação de inference_geo é validada em relação ao allowed_inference_geos do workspace quando o agente é salvo, quando uma sessão é criada a partir dele e em cada turno que a sessão atende. Se a lista de permissões do workspace for restringida de modo que uma fixação não seja mais permitida, novas sessões não poderão ser criadas a partir do agente e as sessões em execução recusarão turnos adicionais; as fixações nunca são isentas, porque os workspaces dependem delas para conformidade e residência de dados.

Definir inference_geo em um modelo que não suporta fixação geográfica de inferência retorna um erro 400; consulte Disponibilidade de modelos para os modelos que suportam. Em uma configuração multiagent, a fixação do coordenador e a de cada membro da lista devem estar todas definidas com o mesmo valor ou todas não definidas; consulte Orquestração multiagente. Para alterar ou limpar a fixação posteriormente, atualize o objeto model do agente; fornecer model sem inference_geo a limpa, conforme descrito em Semântica de atualização.

Atualizar um agente

Atualizar um agente gera uma nova versão quando a configuração muda. O campo version é opcional: forneça-o para concorrência otimista (uma incompatibilidade retorna um 409) ou omita-o para aplicar a atualização incondicionalmente (a última escrita vence). Atualizações em agentes arquivados são rejeitadas.

ant beta:agents update --agent-id "$AGENT_ID" < coding-assistant.agent.yaml

name: Coding Assistant
model:
  id: claude-opus-5
system: You are a helpful coding agent. Always write tests.
tools:
  - type: agent_toolset_20260401

O exemplo anterior fornece version a partir da resposta de criação, portanto a atualização só é aplicada se nada mais tiver alterado o agente desde que você o leu. Para aplicar uma atualização incondicionalmente, omita version da requisição:

updated_agent=$(curl -fsSL "https://api.anthropic.com/v1/agents/$AGENT_ID" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "description": "Writes and reviews code."
  }')

echo "New version: $(jq -r '.version' <<< "$updated_agent")"

Semântica de atualização

• version é opcional e deve ser pelo menos 1 quando fornecido. Quando fornecido, a requisição retorna um 409 se não corresponder à versão atual do agente, mesmo quando os campos que você envia já correspondem aos valores armazenados; releia o agente e tente novamente. Quando omitido, a atualização é aplicada incondicionalmente e a atualização mais recente substitui silenciosamente qualquer atualização concorrente, sem erro para nenhum dos chamadores. Fornecer version é o padrão recomendado para chamadores interativos, e omiti-lo é adequado para loops de aplicação declarativa, como um job de CI que sincroniza definições de agente versionadas no repositório, onde o loop é o dono do agente.

• 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. Dentro de um objeto model que você fornece, effort é a única exceção: se o id do modelo não for alterado, omitir effort deixa o nível de esforço armazenado inalterado. Se você alterar o id do modelo, um effort omitido é redefinido para o padrão do novo modelo. Outros campos de model são substituídos junto com o objeto: fornecer model sem inference_geo limpa a fixação de geo de inferência do agente.

• Campos de array (tools, mcp_servers, skills) são totalmente substituídos pelo novo array. Para limpar completamente um campo de array, 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 alteração em relação à versão atual, nenhuma nova versão é criada e a versão existente é retornada.

• As listas de coordenadores não são atualizadas. Os 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

O arquivamento torna o agente somente leitura e não pode ser desfeito. As sessões existentes continuam em execução, mas novas sessões não podem referenciar o agente. A resposta define archived_at com o timestamp do arquivamento.

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

Próximos passos