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 determinan cómo se comporta Claude durante una sesión.

Crea el agente una sola 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 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 el modelo Claude Opus más reciente 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 compatibles.

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

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 geo 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 geo de inferencia predeterminada del espacio de trabajo en el momento en que se atiende. Consulta Residencia de datos para conocer los controles de geo a nivel de espacio de trabajo 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 espacio de trabajo 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 espacio de trabajo se restringe 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 espacios de trabajo 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 agente y la fijación de cada agente incluido en la lista predefined_agents de subagents o workflows deben tener todas el mismo valor o no estar establecidas; consulta Orquestación multiagente. Para cambiar o eliminar la fijación más adelante, actualiza el objeto model del agente; proporcionar model sin inference_geo la elimina, 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 la concurrencia optimista (una discrepancia devuelve un 409), u omítelo para aplicar la actualización de forma incondicional (gana la última escritura). Las actualizaciones de 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 de forma incondicional, omite version de la solicitud:

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

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

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 de forma incondicional y la actualización más reciente reemplaza silenciosamente cualquier actualización concurrente, sin error para ninguno de los llamadores. Proporcionar version es el valor predeterminado recomendado para llamadores interactivos, y omitirlo es adecuado para bucles de aplicación declarativos, como un trabajo de CI que sincroniza definiciones de agentes registradas 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 None. 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 elimina la fijación de geo 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 None o un arreglo vacío.

• multiagent se fusiona con el bloque almacenado nivel por nivel cuando la actualización mantiene el tipo multiagent_20261001. Una configuración que omitas conserva su valor almacenado, y una lista predefined_agents que envíes reemplaza la lista almacenada. Cualquier otra actualización que envíe multiagent reemplaza el bloque almacenado en su totalidad, y las configuraciones que omita toman sus valores predeterminados. Pasa multiagent=None para borrar todo el bloque. Dentro del bloque, null restablece una configuración a su valor predeterminado, por lo que establecer workflows en null activa los flujos de trabajo dinámicos. Consulta Activar los flujos de trabajo dinámicos.

• Los metadatos se fusionan 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 respecto a la versión actual, no se crea una nueva versión y se devuelve la versión existente.

• Las listas predefined_agents de otros agentes no se actualizan. Los agentes que incluyen este agente en la lista predefined_agents de subagents o workflows conservan la versión que quedó fijada cuando se crearon o cuando una actualización envió esa lista por última vez, incluso si la referencia omite version. Para delegar a la nueva versión, actualiza el agente que lo incluye para que la lista haga referencia a la nueva versión.

La siguiente actualización borra la descripción, elimina la clave team de metadata y establece workflows en null, lo que activa los flujos de trabajo 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 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 de 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 siguen ejecutándose, pero las nuevas sesiones no pueden hacer referencia al agente. La respuesta establece archived_at en la marca de tiempo del archivado.

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

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

Próximos pasos