Define tu agente

Un agente es una configuración reutilizable y versionada que define la personalidad y las capacidades. Agrupa el modelo, el mensaje del sistema, las herramientas, los servidores MCP y las habilidades que moldean 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 en muchas sesiones.

Campos de configuración del agente

Crear un agente

El siguiente ejemplo define un agente de codificación que utiliza Claude Opus 4.7 con acceso al conjunto de herramientas de agente preintegrado. El conjunto de herramientas permite que el agente escriba código, lea archivos, busque en la web y más. Consulta la referencia de herramientas de agente para obtener la lista completa de herramientas admitidas.

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

Actualizar un agente

Actualizar un agente genera una nueva versión. Pasa la version actual para asegurar que estés actualizando desde un estado conocido.

Semántica de actualización

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

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

• Campos de matriz (tools, mcp_servers, skills, callable_agents) se reemplazan completamente por la nueva matriz. Para borrar un campo de matriz completamente, pasa null o una matriz vacía.

Ciclo de vida del agente

Listar versiones

Obtén el historial de versiones completo 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 hacer referencia al agente. La respuesta establece archived_at en la marca de tiempo del archivo.

Próximos pasos

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

Metadatos se fusionan a nivel de clave. Las claves que proporcionas se añaden o actualizan. Las claves que omites se preservan. Para eliminar una clave específica, establece su valor en una cadena vacía.