Define tu agente

Un agente es una configuración reutilizable y versionada que define la personalidad y las capacidades. Agrupa el modelo, la indicación del sistema, las herramientas, los servidores MCP y las habilidades que determinan cómo se comporta Claude durante una sesión.

Crea el agente una vez como un recurso reutilizable y haz referencia a él por su ID cada vez que inicies una sesión. Los agentes están versionados y son más fáciles de gestionar en múltiples sesiones.



Campos de configuración del agente

También puedes sobrescribir model, system, tools, mcp_servers y skills para una sola sesión sin cambiar el agente. Consulta Sobrescribir la configuración del agente para una sesión.



Crear un agente

El siguiente ejemplo define un agente de programación que usa Claude Opus 4.8 con acceso al conjunto de herramientas de agente predefinidas. Este conjunto de herramientas permite al agente escribir código, leer archivos, buscar en la web y más. Consulta la referencia de herramientas de agente para ver la lista completa de herramientas compatibles.

Los ejemplos usan curl, la CLI ant o uno de los SDK. Si aún no has configurado ninguno, la guía de inicio rápido cubre la instalación y la configuración del 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")

La respuesta refleja tu configuración y añade los campos id, type, version, created_at, updated_at y archived_at. El campo version comienza en 1 y se incrementa cada vez que una actualización cambia el 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
}

El default_config del conjunto de herramientas muestra su política de permisos predeterminada, always_allow, que se aplica a menos que configures una.



Actualizar un agente

Actualizar un agente genera una nueva versión cuando la configuración cambia. El campo version es obligatorio y debe coincidir con la versión actual del agente, de modo que siempre actualices desde un estado conocido. Una discrepancia de versión devuelve un error 409, y las actualizaciones a agentes archivados se rechazan.

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



Semántica de actualización

• Los campos omitidos se conservan. Solo necesitas incluir los campos que deseas cambiar.

• Los campos escalares (model, system, name, description) se reemplazan con el nuevo valor. system y description se pueden borrar pasando null. model y name son obligatorios y no se pueden borrar.

• Los campos de arreglo (tools, mcp_servers, skills) se reemplazan completamente por el nuevo arreglo. Para borrar un campo de arreglo por completo, pasa null o un arreglo vacío.

• multiagent se reemplaza en su totalidad, incluida su lista de agents. Pasa null para borrarlo.

• Los metadatos se fusionan a nivel de clave. Las claves que proporciones se añaden o actualizan. Las claves que omitas se conservan. Para eliminar una clave específica, establece su valor en null.

• Detección de operaciones sin efecto. Si la actualización no produce ningún cambio con respecto a la versión actual, no se crea una nueva versión y se devuelve la versión existente.

• Las listas de coordinadores no se actualizan. Los coordinadores que hacen referencia a este agente en su lista multiagent.agents mantienen la versión que se fijó cuando el coordinador se creó o se actualizó por última vez, incluso si la referencia omite version. Para delegar a la nueva versión, actualiza el coordinador de modo que su lista haga referencia a ella.



Ciclo de vida del agente



Listar versiones

Obtén el historial completo de versiones para hacer seguimiento de cómo ha cambiado un agente a lo largo del tiempo. Los resultados están paginados, y los ejemplos del SDK obtienen todas las páginas automáticamente.

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



Archivar un agente

Archivar convierte el agente en solo lectura y no se puede deshacer. Las sesiones existentes continúan ejecutándose, pero las nuevas sesiones no pueden hacer referencia al agente. La respuesta establece archived_at con la marca de tiempo del archivado.

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



Próximos pasos