Define tu agente

Un agente es una configuración reutilizable y versionada que define la persona y las capacidades. Agrupa el modelo, el prompt 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 referéncialo por ID cada vez que inicies una sesión. Los agentes están versionados y son más fáciles de gestionar en muchas sesiones.

Campos de configuración del agente

Crear un agente

El siguiente ejemplo define un agente de codificación que usa Claude Sonnet 4.6 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.

La respuesta repite tu configuración y agrega los campos id, version, created_at, updated_at y archived_at. El campo version comienza en 1 y se incrementa cada vez que actualizas el 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
}

Actualizar un agente

Actualizar un agente genera una nueva versión. Pasa el version actual para asegurarte de que estás actualizando desde un estado conocido.

Semántica de actualización

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

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

• Los campos de array (tools, mcp_servers, skills, callable_agents) son completamente reemplazados por el nuevo array. Para borrar un campo de array por completo, pasa null o un array vacío.

Ciclo de vida del agente

Listar versiones

Obtiene el historial completo de versiones para rastrear cómo ha cambiado un agente a lo largo del tiempo.

Archivar un agente

Archivar hace que el agente sea de solo lectura. Las sesiones existentes continúan ejecutándose, pero las nuevas sesiones no pueden referenciar al agente. La respuesta establece archived_at con la marca de tiempo del archivo.

Próximos pasos

• Configura herramientas para personalizar qué capacidades puede usar el agente.
• Adjunta habilidades para experiencia específica del dominio.
• Inicia una sesión que referencie tu agente.

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 una cadena vacía.