Defina seu agente

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

Crie o agente uma vez como um recurso reutilizável e referencie-o por ID sempre 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 substituir model, system, tools, mcp_servers e skills para uma única sessão sem alterar o agente. Uma substituição de model substitui por completo o objeto model do agente, portanto o effort do próprio agente não é mantido. Para executar a sessão em um nível de esforço específico, defina effort dentro do objeto model da substituição. Consulte Substituir a configuração do agente para uma sessão.

Criar um agente

O exemplo a seguir define um agente de programação que usa o modelo Claude Opus mais recente 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 nenhum deles, o início rápido aborda a instalação e a configuração do cliente.

ant apply coding-assistant.md

---
name: Coding Assistant
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
---

You are a helpful coding agent.

A resposta repete sua configuração e adiciona os campos id, type, version, created_at, updated_at e archived_at, além de preencher com seus valores padrão os campos de model que você omitir, como effort. 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-5",
    "effort": { "type": "medium" },
    "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ões 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 ver os controles de geo no nível do workspace e os preços.

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

ant apply geo-pinned-assistant.md

---
name: Geo-pinned assistant
model:
  id: claude-opus-5-5
  inference_geo: us
---

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 ver os modelos que suportam. Em uma configuração multiagent, a fixação do agente e a fixação de cada agente listado na lista predefined_agents de subagents ou workflows devem estar todas definidas com o mesmo valor ou todas sem definição; consulte Orquestração multiagente. Para alterar ou remover a fixação posteriormente, atualize o objeto model do agente; fornecer model sem inference_geo a remove, 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 "optimistic concurrency" (concorrência otimista) (uma incompatibilidade retorna um 409), ou omita-o para aplicar a atualização incondicionalmente (a última gravação prevalece). Atualizações em agentes arquivados são rejeitadas.

Com a CLI, edite o arquivo do agente e execute ant apply novamente; o apply fornece version para você.

ant apply coding-assistant.md

---
name: Coding Assistant
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
---

You are a helpful coding agent. Always write tests.

O exemplo anterior fornece version a partir da resposta de criação, de modo que 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:

unconditional_agent = client.beta.agents.update(
    agent.id,
    description="Writes and reviews code.",
)

print(f"New version: {unconditional_agent.version}")

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; leia o agente novamente e tente de novo. 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 apply declarativos, como um job de CI que sincroniza definições de agentes versionadas no repositório, em que 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 None. 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 mudar, omitir effort mantém inalterado o nível de esforço armazenado. 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 remove 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 None ou um array vazio.

• multiagent é mesclado ao bloco armazenado nível por nível quando a atualização mantém o tipo multiagent_20261001. Uma configuração que você omite mantém seu valor armazenado, e uma lista predefined_agents que você envia substitui a lista armazenada. Qualquer outra atualização que envie multiagent substitui o bloco armazenado como um todo, e as configurações que ela omite assumem seus valores padrão. Passe multiagent=None para limpar o bloco inteiro. Dentro do bloco, null redefine uma configuração para seu padrão, portanto definir workflows como null ativa os fluxos de trabalho dinâmicos. Consulte Ativar fluxos de trabalho dinâmicos.

• Metadata é mesclado no nível da 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 predefined_agents de outros agentes não são atualizadas. Agentes que listam este agente na lista predefined_agents de subagents ou workflows mantêm a versão que foi fixada quando foram criados ou quando uma atualização enviou essa lista pela última vez, mesmo que a referência omita version. Para delegar à nova versão, atualize o agente que o lista para que a lista referencie a nova versão.

A atualização a seguir limpa a descrição, exclui a chave team de metadata e define workflows como null, o que ativa os fluxos de trabalho dinâmicos:

ant apply code-reviewer.md

---
name: Code Reviewer
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
metadata:
  owner: docs
multiagent:
  type: multiagent_20261001
  workflows: null
---

You are a helpful coding agent.

Ciclo de vida do agente

Listar versões

Obtenha 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.

for version in client.beta.agents.versions.list(agent.id):
    print(f"Version {version.version}: {version.updated_at.isoformat()}")

Arquivar um agente

Arquivar 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.

archived = client.beta.agents.archive(agent.id)

print(f"Archived at: {archived.archived_at.isoformat()}")

Próximos passos