Defina seu agente

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

Crie o agente uma vez como um recurso reutilizável e faça referência a ele por ID cada vez que você inicia 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 Claude Opus 4.7 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.

ant beta:agents create \
  --name "Coding Assistant" \
  --model '{id: claude-opus-4-7}' \
  --system "You are a helpful coding agent." \
  --tool '{type: agent_toolset_20260401}'

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

{
  "id": "agent_01HqR2k7vXbZ9mNpL3wYcT8f",
  "type": "agent",
  "name": "Coding Assistant",
  "model": {
    "id": "claude-opus-4-7",
    "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 a version atual para garantir que você está atualizando a partir de um estado conhecido.

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, 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 matriz (tools, mcp_servers, skills, callable_agents) são totalmente substituídos pela nova matriz. Para limpar um campo de matriz completamente, passe null ou uma matriz vazia.

• Metadados são mesclados 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 uma string vazia.

• 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 será criada e a versão existente será retornada.

Ciclo de vida do agente

Listar versões

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

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

Arquivar um agente

Arquivar torna o agente somente leitura. As sessões existentes continuam a ser executadas, mas novas sessões não podem fazer referência ao agente. A resposta define archived_at para o timestamp do arquivo.

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

Próximas etapas

• Configure ferramentas para personalizar quais capacidades o agente pode usar.
• Anexe habilidades para expertise específica do domínio.
• Inicie uma sessão que faça referência ao seu agente.