Diferencias con el servicio alojado
Consulta qué funciones solo tiene Claude Managed Agents autoalojado, qué funciones del servicio alojado no tiene, cuáles se comportan de forma diferente y cuáles necesitan primero una configuración del servidor.
Un servidor de Claude Managed Agents autoalojado tiene la misma API que el servicio alojado Managed Agents de Anthropic, aparte de las diferencias de esta página. Las tablas indican qué hacer en cada caso. Consúltalas antes de mover una aplicación a tu servidor. No se copia nada del servicio alojado, incluido el historial de sesiones. Vuelve a crear tus agentes, skills, credenciales de vault y almacenes de memoria en tu servidor.
Funciones que solo tiene tu servidor
| Función | Qué hace | Cómo configurarla |
|---|---|---|
| Una elección de proveedor de inferencia | El servidor puede enviar las llamadas al modelo a un proveedor de nube o a tu propio gateway de modelos en lugar de la Claude API. | Proveedor de inferencia |
| Inicio de sesión único | Las personas llaman al servidor con un token de tu proveedor de identidad OpenID Connect. El servidor asigna a cada llamante un rol a partir de los grupos del token. La clave de API del servidor sigue funcionando. | Inicio de sesión único |
| Tu propio gestor de secretos | El servidor puede almacenar el secreto de cada nueva credencial de vault en tu gestor de secretos en lugar de en su propia base de datos. | Gestor de secretos |
| Identidad del agente | El servidor puede firmar un token de corta duración y enviarlo con las llamadas de un agente a un servidor MCP. El servidor MCP o el gateway verifica el token con las claves públicas que publiques. | Identidad del agente |
Funciones que no están disponibles
| Función | Qué sucede | Qué hacer en su lugar |
|---|---|---|
| Entornos en la nube | Solo existen entornos self_hosted. Una solicitud de un entorno en la nube devuelve un error 400. | Implementa workers autoalojados para cada entorno. |
| El resto de la Claude API, como la Messages API y la Models API | El servidor no la sirve. Las llamadas del SDK a /v1/messages y /v1/models devuelven un error 404. | Envía esas solicitudes a la Claude API o a tu proveedor, desde un cliente que no apunte a tu servidor. |
| Recursos de sesión de archivo y la Files API | El servidor rechaza los recursos file, y /v1/files no existe. Los recursos memory_store funcionan. | Coloca los archivos en el directorio de trabajo del worker. Consulta Mover datos hacia dentro y fuera de una sesión. Para mostrarle al modelo una imagen o un PDF, envíalo como base64 en un mensaje. |
Credenciales de vault mcp_oauth | El servidor las rechaza cuando las creas, porque no tiene un flujo de OAuth para renovar un token. | Almacena el token como una credencial static_bearer. Actualiza la credencial con un token nuevo antes de que caduque el anterior. |
Skills predefinidas docx, pdf, pptx y xlsx | El servidor rechaza un agente que las declare. Solo existen las skills que subes. | Descarga su código fuente desde el repositorio de skills y súbelas como skills personalizadas. |
| Implementaciones programadas y sueños | El servidor no tiene rutas para ellos. | Inicia sesiones desde tu propio programador, como un trabajo de cron. Los sueños no tienen reemplazo. |
| Webhooks | El servidor no envía webhooks, por lo que un worker que se inicia con un webhook nunca se inicia. | Sigue una sesión a través de su flujo de eventos, o lista sus eventos. Mantén tus workers en ejecución para que puedan sondear. |
Funciones que se comportan de forma diferente
| Función | Qué es diferente | Qué hacer |
|---|---|---|
| Claude Console | La Claude Console en platform.claude.com no muestra lo que hay en tu servidor. | Usa la consola de tu servidor. |
| Llamadas a herramientas | Los turnos del modelo de una sesión se ejecutan incluso cuando ningún worker está sondeando su entorno. La primera llamada a herramienta espera entonces, sin error, hasta que un worker la ejecute. | Si una sesión se detiene en una llamada a herramienta, comprueba que haya un worker sondeando su entorno. |
| Almacenes de memoria | La API está completa. Es el worker, no el servidor, quien copia cada almacén adjunto en el sandbox y escribe los cambios de vuelta. Consulta Almacenes de memoria en sandboxes autoalojados. | Ejecuta tus workers con la versión más reciente de ant, con un directorio /mnt/memory con permisos de escritura. |
| Subidas de skills personalizadas | El servidor no descomprime un archivo zip. Subir uno devuelve un error 400 que dice SKILL.md not found in uploaded files. | ant apply y el helper files_from_dir del SDK de Python funcionan tal cual. Con cualquier otra cosa, sube los archivos de la skill como partes separadas y haz que el nombre de archivo de cada parte empiece por la carpeta de la skill, como en my-skill/SKILL.md. |
| Orquestación multiagente | Un agente solo puede delegar en los subagentes que incluyas. Los flujos de trabajo dinámicos, el asesor y los subagentes que el propio agente define no están disponibles. El servidor acepta un bloque multiagent solo si su type es coordinator. Los ejemplos de Orquestación multiagente establecen type en multiagent_20261001, que devuelve un error 400. Un bloque con una configuración advisor también devuelve un error 400. | Establece multiagent en {"type": "coordinator", "agents": [...]}. Incluye de 1 a 20 agentes en agents. Cada entrada adopta una de las formas de un agente predefinido. |
| Recursos de sesión de repositorio de GitHub | El servidor rechaza los recursos github_repository hasta que incluyas sus hosts de Git en su configuración. El servidor no descubre skills en el directorio .claude/skills de un repositorio, así que adjunta las skills al agente. | Consulta Los repositorios de Git necesitan una entrada en la lista de permitidos. |
| Servidores MCP | El servidor se conecta solo a los hosts MCP que incluyas en su configuración. | Consulta Los servidores MCP necesitan una entrada en la lista de permitidos. |
| Herramientas web | Las herramientas web_search y web_fetch están desactivadas hasta que las actives en la configuración del servidor. | Consulta Las herramientas web necesitan una configuración del servidor. |
Credenciales de vault environment_variable | El servidor las rechaza hasta que actives el “egress gateway” (gateway de salida), un proxy entre tus sandboxes e internet. | Consulta Credenciales de variables de entorno. Sin el gateway, proporciona a tu sandbox las credenciales de CLI y de API que necesita mediante tus propias herramientas. |
| Resultados de herramientas personalizadas | El servidor envía al modelo el texto completo de un resultado de herramienta personalizada. Si un resultado es demasiado grande para la “context window” (ventana de contexto) del modelo, el servidor igualmente responde con 200, y la sesión termina entonces con un session.error. | Acorta los resultados largos en tu cliente antes de enviarlos. |
| Resultados de herramientas MCP | El servidor recorta un resultado que supera su configuración mcp.max_result_bytes, que es de 100 KiB de forma predeterminada. Le indica al modelo que el resultado se recortó, y el resto se pierde. El servicio alojado también recorta los resultados largos, pero puede guardar el resultado completo en un archivo para una sesión en un sandbox en la nube. | Para cambiar el límite, establece mcp.max_result_bytes en el archivo de configuración. |
| Imágenes y documentos enviados por URL | El servidor acepta un bloque image o document con una fuente url, pero el modelo nunca lo ve y no se produce ningún error. Lo mismo ocurre con un bloque image con una fuente file. | Envía los datos como base64, o como text en el caso de un documento. |
El estado de sesión rescheduling | El servidor reintenta una llamada al modelo que falla por un motivo transitorio e informa de cada intento en el flujo de eventos, como hace el servicio alojado. El estado de la sesión permanece en running entre intentos, por lo que un filtro statuses[]=rescheduling no coincide con ninguna sesión. | Consulta los reintentos en el flujo de eventos. |
| Metadatos de sesión, con un gateway de modelos | Si la configuración inference.credentials.assertion.forward_metadata del servidor incluye claves de metadatos de sesión, una actualización que añada, elimine o cambie una de ellas devuelve un error 400. | Establece esas claves cuando crees la sesión. Para la configuración, consulta Tokens de gateway de corta duración. |
Funciones que necesitan una configuración del servidor
Cada una de estas funciones está desactivada, o rechaza todos los hosts, hasta que cambies el archivo de configuración del servidor.
Los servidores MCP necesitan una entrada en la lista de permitidos
El servidor solo se conecta a servidores MCP cuyos hosts incluyas en mcp.allowed_hostnames en su archivo de configuración:
mcp:
allowed_hostnames:
- mcp.example.comLos hosts deben coincidir exactamente, sin comodines ni subdominios, y la lista está vacía de forma predeterminada. Hasta que el host de un servidor MCP esté en la lista, tu servidor se niega a guardar un agente que lo mencione.
Un servidor MCP dentro de tu red privada no necesita un túnel MCP. Coloca su URL en la definición del agente, como describe Conector MCP, y añade su host a la “allowlist” (lista de permitidos). Se aplican dos reglas a la URL:
- Debe usar
https, a menos que el servidor MCP esté en la dirección de loopback. - Si su host es un nombre que solo se resuelve en direcciones privadas o reservadas, tu servidor se niega a conectarse de forma predeterminada. Elige la solución que se ajuste a tu caso:
| Tu caso | Solución |
|---|---|
La dirección está en 10.0.0.0/8, 172.16.0.0/12 o 192.168.0.0/16, y controlas los registros DNS del nombre | Conserva el nombre y añádelo también a mcp.private_hostnames en el archivo de configuración. |
| Cualquier otro caso | Usa la dirección IP en lugar del nombre, tanto en la URL como en la lista de permitidos. El certificado del servidor MCP debe nombrar esa dirección. |
Los repositorios de Git necesitan una entrada en la lista de permitidos
En el servicio alojado, las sesiones que usan sandboxes autoalojados no pueden tener recursos github_repository. En tu servidor, sí pueden. El servidor rechaza estos recursos hasta que incluyas sus hosts de Git en su archivo de configuración. Los agentes solo pueden hacer push a las ramas que incluyas:
git:
allowed_hostnames:
- github.com
allowed_push_refs:
- refs/heads/agent/Ten en cuenta estos puntos:
- URL: El host no tiene que ser
github.com, pero la URL debe usar HTTPS. - Token: El token que tu cliente envía nunca llega al sandbox, porque el tráfico de Git pasa por tu servidor, que añade el token.
- Ramas: A los agentes no se les indica la lista de ramas, así que nombra una rama en tu prompt.
- Force pushes: El servidor no rechaza los force pushes, por lo que un agente puede sobrescribir cualquier rama que incluyas. Para rechazar los force pushes, protege la rama en tu host de Git.
Acceder a GitHub muestra la solicitud y cómo rotar un token. Si una clonación falla, la sesión recibe un evento session.error que indica la causa. Para comprobar un push, busca la rama en tu host de Git. El registro del servidor dice ok incluso para un push que tu host rechazó.
Las herramientas web necesitan una configuración del servidor
Las herramientas web_search y web_fetch están desactivadas de forma predeterminada. Para activarlas, añade esto al archivo de configuración del servidor:
web_tools:
enabled: trueSolo con esta configuración, se aplican las listas de dominios y el límite de contenido propios de cada agente, como en el servicio alojado.
Para limitar las herramientas para todos los agentes, establece web_tools.allowed_domains, web_tools.blocked_domains o web_tools.max_content_tokens. Cada una de estas configuraciones también activa las herramientas. El servidor se niega a guardar un agente que pida más de lo que permiten estas configuraciones. Por ejemplo, rechaza un agente que permita un dominio fuera de web_tools.allowed_domains, o que establezca un límite de contenido mayor. Si ese agente ya existe, no puede iniciar una sesión hasta que lo actualices.
Mientras las herramientas están desactivadas, lo que le ocurre a un agente depende de las entradas web_search y web_fetch de su conjunto de herramientas:
| El conjunto de herramientas tiene | Qué ocurre |
|---|---|
| Ninguna entrada para ninguna de las dos herramientas | El agente se ejecuta sin las herramientas, y ningún error lo indica. |
Una entrada que solo desactiva su herramienta, como {"name": "web_fetch", "enabled": false} | Lo mismo. |
| Una entrada que deja su herramienta activada, o que establece sus listas de dominios, su límite de contenido o su ubicación | El servidor se niega a guardar el agente, o a iniciar una sesión para él. |
Qué herramientas web existen también depende de tu proveedor de inferencia.
Diferencias que dependen de tu proveedor de inferencia
Algunas funciones solo funcionan con algunos valores de la configuración inference.provider del servidor. La tabla muestra lo que ocurre con los demás valores. Algunos de estos casos no devuelven ningún error.
Las filas de web_search y web_fetch se aplican después de que actives las herramientas web. Hasta entonces, ninguna de las dos herramientas funciona con ningún proveedor.
| Función | Funciona cuando inference.provider es | Con los demás valores | Qué hacer |
|---|---|---|---|
Herramienta web_search | anthropic, vertex, foundry | El servidor nunca ofrece la herramienta al modelo. Los agentes se siguen guardando y ejecutando, y siguen incluyendo la herramienta, pero el modelo no puede llamarla. | Proporciona al agente una herramienta personalizada o un servidor MCP que haga búsquedas. |
Herramienta web_fetch | anthropic, foundry | Lo mismo que con web_search. | Proporciona al agente una herramienta personalizada o un servidor MCP que obtenga páginas. |
inference_geo | anthropic | El servidor se niega a guardar un agente que lo establezca. | Elimina inference_geo del agente. |
Modo rápido (speed: "fast") | Depende del proveedor y del modelo del agente | Un agente que lo establezca tiene que superar dos comprobaciones. Cuando guardas el agente: El catálogo de modelos del servidor debe incluir el modelo del agente como uno que acepta el modo rápido. De lo contrario, el servidor se niega a guardar el agente. En cada turno: Si el proveedor no ofrece el modo rápido para ese modelo o implementación, el turno termina con un error. | Elimina speed del agente. Consulta Modelos que aceptan el modo rápido. |
Con anthropic, el servidor solicita de forma predeterminada el fallback del lado del servidor de la Claude API. Cuando un clasificador de seguridad rechaza una solicitud, otro modelo de Claude, posiblemente uno menos capaz, puede entonces responderla. Anthropic elige el modelo, y ningún evento informa del cambio, pero una lectura de la sesión muestra el ID de ese modelo. Para desactivar el fallback, establece inference.model_fallback: false. Con los demás proveedores, una solicitud así termina el turno con un rechazo.
La documentación de tu proveedor indica qué modelos y regiones admiten cada función. Las herramientas personalizadas, las herramientas MCP y las herramientas que ejecuta tu worker son las mismas con cualquier proveedor.
Modelos que aceptan el modo rápido
De forma predeterminada, el catálogo de modelos del servidor incluye cuatro modelos como modelos que aceptan el modo rápido: Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8 y Claude Opus 4.6. Con Claude Opus 4.6, la Claude API acepta la solicitud, pero la ejecuta a velocidad estándar. Estos valores de inference.provider son excepciones:
foundry: El catálogo incluye solo Claude Opus 5.5.gatewayconformat: vertex-raw-predict: El catálogo no incluye ningún modelo.vertex: El catálogo no incluye ningún modelo, y ninguna configuración lo cambia.
Para cambiar lo que incluye el catálogo, consulta Entradas de modelo.
Si ya ejecutas sandboxes autoalojados
El software del worker es el mismo, por lo que tus workers pueden conectarse a tu servidor. Ejecutar tus propios workers enumera los tres valores para el proceso que hace polling y qué cambiar primero. Un worker que se inicia con un webhook no funciona aquí.
¿Te resultó útil esta página?