Define tu agente

Un agente es una configuración reutilizable y versionada que define la personalidad y las capacidades. Agrupa el modelo, la "system prompt" (indicación del sistema), las herramientas, los servidores MCP y las skills que dan forma a cómo se comporta Claude durante una sesión.

Crea el agente una vez como un recurso reutilizable y haz referencia a él por ID cada vez que inicies una sesión. Los agentes están versionados y son más fáciles de administrar a lo largo de muchas 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. Una sobrescritura de model reemplaza por completo el objeto model del agente, por lo que el effort propio del agente no se conserva. Para ejecutar la sesión con un nivel de esfuerzo específico, establece effort dentro del objeto model de la sobrescritura. 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 5 con acceso al conjunto de herramientas de agente predefinido. El 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 admitidas.

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

La respuesta refleja tu configuración y agrega los campos id, type, version, created_at, updated_at y archived_at, y completa los campos de model que omitas, como effort, con sus valores predeterminados. 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-5-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
}

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

Fijar la geografía de inferencia

Al igual que speed y effort, inference_geo se establece mediante la forma de objeto de model: pasa model como un objeto y establece inference_geo junto con id. El campo acepta "us" o "global". Cuando no está establecido, cada solicitud al modelo sigue la geografía de inferencia predeterminada del workspace en el momento en que se atiende. Consulta Residencia de datos para conocer los controles de geografía a nivel de workspace y los precios.

El siguiente ejemplo fija un agente a la inferencia en EE. UU. e imprime el valor de inference_geo del objeto model del 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.

Una fijación de inference_geo se valida contra los allowed_inference_geos del workspace cuando se guarda el agente, cuando se crea una sesión a partir de él y en cada turno que atiende la sesión. Si la lista de permitidos del workspace se reduce de modo que una fijación ya no está permitida, no se pueden crear nuevas sesiones a partir del agente y las sesiones en ejecución rechazan turnos adicionales; las fijaciones nunca quedan exentas, porque los workspaces dependen de ellas para el cumplimiento normativo y la residencia de datos.

Establecer inference_geo en un modelo que no admite la fijación geográfica de inferencia devuelve un error 400; consulta Disponibilidad de modelos para ver los modelos que sí la admiten. En una configuración multiagent, la fijación del coordinador y la de cada miembro de la lista deben estar todas establecidas en el mismo valor o todas sin establecer; consulta Orquestación multiagente. Para cambiar o borrar la fijación más adelante, actualiza el objeto model del agente; proporcionar model sin inference_geo la borra, como se describe en Semántica de actualización.

Actualizar un agente

Actualizar un agente genera una nueva versión cuando la configuración cambia. El campo version es opcional: proporciónalo para concurrencia optimista (una discrepancia devuelve un 409), u omítelo para aplicar la actualización incondicionalmente (la última escritura gana). Las actualizaciones a agentes archivados se rechazan.

Con la CLI, edita el archivo del agente y vuelve a ejecutar ant apply; apply proporciona version por ti.

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.

El ejemplo anterior proporciona version a partir de la respuesta de creación, por lo que la actualización solo se aplica si nada más ha cambiado el agente desde que lo leíste. Para aplicar una actualización incondicionalmente, omite version de la solicitud:

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 actualización

• version es opcional y debe ser al menos 1 cuando se proporciona. Cuando se proporciona, la solicitud devuelve un 409 si no coincide con la versión actual del agente, incluso cuando los campos que envías ya coinciden con los valores almacenados; vuelve a leer el agente y reintenta. Cuando se omite, la actualización se aplica incondicionalmente y la actualización más reciente reemplaza silenciosamente a cualquier otra concurrente, sin error para ninguno de los dos llamadores. Proporcionar version es la opción predeterminada recomendada para llamadores interactivos, y omitirlo se ajusta a bucles de aplicación declarativos, como un trabajo de CI que sincroniza definiciones de agentes versionadas en el repositorio, donde el bucle es el propietario del agente.

• Los campos omitidos se conservan. Solo necesitas incluir los campos que quieres 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. Dentro de un objeto model que proporciones, effort es la única excepción: si el id del modelo no cambia, omitir effort deja sin cambios el nivel de esfuerzo almacenado. Si cambias el id del modelo, un effort omitido se restablece al valor predeterminado del nuevo modelo. Los demás campos de model se reemplazan junto con el objeto: proporcionar model sin inference_geo borra la fijación de geografía de inferencia del agente.

• Los campos de arreglo (tools, mcp_servers, skills) se reemplazan por completo con 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 agents. Pasa null para borrarlo.

• Los metadatos se combinan a nivel de clave. Las claves que proporcionas se agregan o actualizan. Las claves que omites 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 los coordinadores no se actualizan. Los coordinadores que hacen referencia a este agente en su lista multiagent.agents conservan 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 para 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.

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

Archivar un agente

Archivar hace que el agente sea de 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.

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

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

Próximos pasos