Defina seu agente

Um agente é uma configuração reutilizável e versionada que define persona e capacidades. Ele agrupa o modelo, prompt de sistema, ferramentas, servidores MCP e 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 pelo 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

Criar um agente

O exemplo a seguir define um agente de codificação que usa o Claude Sonnet 4.6 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 suportadas.

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

{
  "id": "agent_01HqR2k7vXbZ9mNpL3wYcT8f",
  "type": "agent",
  "name": "Coding Assistant",
  "model": {
    "id": "claude-sonnet-4-6",
    "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
}

Atualizar um agente

Atualizar um agente gera uma nova versão. Passe o version atual para garantir que você está atualizando a partir de um estado conhecido.

Semântica de atualização

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

• Campos escalares (model, system, name, etc.) 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, callable_agents) são completamente substituídos pelo novo array. Para limpar um campo de array inteiramente, passe null ou um array vazio.

Ciclo de vida do agente

Listar versões

Busca o histórico completo de versões para rastrear como um agente mudou ao longo do tempo.

Arquivar um agente

Arquivar torna o agente somente leitura. As sessões existentes continuam a ser executadas, mas novas sessões não podem referenciar o agente. A resposta define archived_at para o timestamp do arquivamento.

Próximos passos

• Configure ferramentas para personalizar quais capacidades o agente pode usar.
• Anexe skills para expertise específica de domínio.
• Inicie uma sessão que referencia seu agente.

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 uma string vazia.