Llamar a la API en un servidor autoalojado

Un servidor autoalojado de Claude Managed Agents tiene la misma API que el servicio alojado de Managed Agents de Anthropic. Tu código lo llama con el SDK oficial, cURL o la CLI ant. Cambian dos cosas: la URL base es la dirección de tu servidor, y la clave de API es tu clave de API del servidor en lugar de una clave de API de Claude.

Para crear agentes y ejecutar sesiones en un navegador, consulta Usar la consola en tu servidor.

Requisitos previos

• Un servidor en ejecución: Inicia uno con Comenzar con Claude Managed Agents autoalojado o Implementar en Kubernetes.
• Acceso al servidor: Si otra persona ejecuta el servidor, pídele su dirección y cómo autenticarte. Si usa el inicio de sesión único, consulta Permitir que los desarrolladores inicien sesión desde una terminal.
• La CLI ant: Instala la versión más reciente, como se muestra en el inicio rápido de la CLI.

Apuntar tu cliente a tu servidor

El SDK y la CLI ant leen la dirección del servidor desde ANTHROPIC_BASE_URL y la clave de API desde ANTHROPIC_API_KEY. Define ambas variables en una terminal que reserves para este servidor.

Para el stack del inicio rápido, ejecuta estos comandos desde el directorio que contiene tu archivo .env:

export ANTHROPIC_BASE_URL=http://127.0.0.1:8400
export ANTHROPIC_API_KEY=$(grep '^CMA_SERVER__API_KEY=' .env | cut -d= -f2)

En Kubernetes, define las dos variables como se muestra en Ejecutar una sesión y mantén en ejecución su port-forward.

En esa terminal, cada comando ant, como ant beta:agents list, llega a tu servidor. No ejecutes Claude Code ni docker compose en esa terminal, porque leen las mismas variables.

Iniciar una sesión

Una sesión necesita el ID de un agente y el ID de un entorno:

• Agente: Crea uno como se muestra en Crear un agente, con tu cliente apuntando a tu servidor. Si envías solicitudes HTTP directas, reemplaza https://api.anthropic.com en la URL por $ANTHROPIC_BASE_URL.
• Entorno: El stack del inicio rápido crea uno llamado compose-sandbox, y los charts de Helm crean uno llamado default. ant beta:environments list imprime el nombre y el ID de cada entorno. Para tus propios workers, es el ID que la CLI de administración imprimió en Ejecutar tus propios workers.

Coloca tus dos ID en tu shell, en lugar de estos ID de ejemplo:

export AGENT_ID=agent_011CYm1BLqPXpQRk5khsSXrs
export ENVIRONMENT_ID=env_01595EKxaaTTGwwY3kyXdtbs

El siguiente ejemplo crea una sesión y envía su primer mensaje en la misma solicitud:

import os

from anthropic import Anthropic

client = Anthropic()

session = client.beta.sessions.create(
    agent=os.environ["AGENT_ID"],
    environment_id=os.environ["ENVIRONMENT_ID"],
    initial_events=[
        {
            "type": "user.message",
            "content": [
                {"type": "text", "text": "List the files in the working directory."}
            ],
        },
    ],
)
print(session.id)

La respuesta contiene el ID de la sesión, que comienza con sesn_. El agente empieza a trabajar de inmediato. Sus herramientas integradas, como bash, se ejecutan en un worker que sirve el entorno.

Para observar la sesión, abre la consola de tu servidor en un navegador, selecciona Sessions y, a continuación, selecciona la sesión. Una sesión que iniciaste con la clave de API del servidor, como en esta página, solo es visible para los administradores.

Para seguir la sesión en tu terminal, pasa su ID a ant beta:sessions connect:

ant beta:sessions connect sesn_011CZkZAtmR3yMPDzynEDxu7

Para saber qué más puede hacer una sesión, como fijar una versión del agente, consulta Iniciar una sesión.

Enviar un mensaje y leer la respuesta

Coloca el ID de tu sesión en tu shell, en lugar de este ID de ejemplo:

export SESSION_ID=sesn_011CZkZAtmR3yMPDzynEDxu7

Espera hasta que la sesión esté inactiva antes de ejecutar el siguiente ejemplo. El ejemplo deja de leer cuando termina un turno. Si un turno anterior sigue en curso, su final puede detener el ejemplo antes de que llegue la respuesta a tu mensaje. Tanto la consola como ant beta:sessions connect muestran el estado de la sesión.

El siguiente ejemplo envía un mensaje e imprime la respuesta del agente. Primero abre el flujo de eventos de la sesión, porque un flujo entrega solo los eventos que llegan después de abrirse:

import os

from anthropic import Anthropic

client = Anthropic()
session_id = os.environ["SESSION_ID"]

with client.beta.sessions.events.stream(session_id) as stream:
    client.beta.sessions.events.send(
        session_id,
        events=[
            {
                "type": "user.message",
                "content": [
                    {"type": "text", "text": "Summarize what you did in one sentence."}
                ],
            },
        ],
    )

    for event in stream:
        match event.type:
            case "agent.message":
                for block in event.content:
                    if block.type == "text":
                        print(block.text, end="")
            case "session.error":
                error_message = event.error.message if event.error else "unknown"
                print(f"\n[Error: {error_message}]")
            case "session.status_idle":
                if event.stop_reason.type != "requires_action":
                    break
            case "session.status_terminated":
                break

Además de imprimir el texto de agent.message, el bucle gestiona tres eventos:

• session.status_idle: El bucle termina, a menos que el stop_reason.type del evento sea requires_action.
• session.status_terminated: El bucle termina.
• session.error: El bucle imprime el mensaje del error y sigue leyendo, porque el servidor puede reintentar una llamada al modelo que falló y terminar el turno.

requires_action significa que la sesión se ha pausado para una llamada a herramienta. Lo que termina la pausa depende de la llamada:

• Una llamada a una herramienta personalizada o una solicitud para confirmar una llamada a herramienta: Solo tu código puede responderla. Si tu agente usa cualquiera de las dos, consulta Responder a llamadas a herramientas que pausan la sesión.
• Una llamada a una herramienta que ejecuta un worker, como bash: Esta llamada normalmente no pausa la sesión. Si ningún worker toma la llamada durante unos 3 minutos, la sesión se pausa hasta que un worker devuelve el resultado. En ese caso, tu código no tiene nada que responder. Mantén el flujo abierto, y el turno se reanuda cuando un worker ejecuta la llamada.

Para conocer los demás eventos que envía una sesión y cómo reconectarte sin perder ninguno, consulta Flujo de eventos de la sesión.

Mover datos hacia dentro y fuera de una sesión

Los datos llegan a una sesión y salen de ella a través del directorio de trabajo del worker.

En el stack del inicio rápido, el contenedor de cada sesión comienza con un directorio /workspace vacío, salvo por los clones de los repositorios de la sesión. De forma predeterminada, aproximadamente un minuto después de que termina un turno, el contenedor finaliza y Docker lo elimina junto con ese directorio. Todo lo que una sesión deba conservar tiene que salir mediante una llamada a herramienta, como una subida o un git push, antes de ese momento.

Un contenedor también finaliza aproximadamente una hora después de iniciarse, incluso a mitad de un turno. Ninguna configuración cambia eso. El turno continúa en un contenedor nuevo, normalmente después de uno o dos minutos, y tu cliente no recibe ningún evento por el cambio. El cambio tiene dos costos:

• Comandos: Todo lo que se ejecuta en el contenedor anterior se detiene. El contenedor nuevo vuelve a ejecutar desde el principio la llamada a herramienta interrumpida, pero nada reinicia un comando que el agente dejó en ejecución en segundo plano.
• Archivos: El /workspace del contenedor nuevo vuelve a estar vacío, salvo por clones nuevos de los repositorios de la sesión.

En un turno largo, haz que el agente suba o envíe su trabajo a medida que avanza, y evita los comandos que causen daño si se ejecutan dos veces.

En Kubernetes, una sesión conserva un pod durante aproximadamente una hora como máximo, y el turno continúa de la misma manera. Hay dos diferencias: el pod nuevo encuentra los archivos de la sesión en /workspace, y se inicia unos 6 minutos después de que se detiene el pod anterior.

Para los workers que inicias tú mismo, coloca los archivos de entrada en el directorio de trabajo antes de enviar el mensaje que los necesita. Lee los archivos de salida de ese directorio después.

Cuando inicias tú mismo un contenedor para cada sesión, monta un directorio que contenga los archivos de entrada de la sesión como directorio de trabajo del contenedor. Recoge los archivos de salida de él después de que el contenedor termine. Consulta Prepara archivos para una sesión.

Encontrar más ejemplos en las guías del servicio alojado

Las guías del servicio alojado explican los conceptos principales de la API e incluyen ejemplos para cada función. Sus ejemplos del SDK y de la CLI llaman a tu servidor cuando los ejecutas en la terminal donde están definidas ANTHROPIC_BASE_URL y ANTHROPIC_API_KEY. Sus ejemplos de cURL indican https://api.anthropic.com, así que reemplaza esa dirección por $ANTHROPIC_BASE_URL antes de ejecutar uno.

Para algunas funciones, tu servidor necesita primero una configuración, o un ejemplo necesita un cambio:

Diferencias con el servicio alojado contiene la lista completa. Consúltala antes de migrar una aplicación existente.

Ejecutar tus propios workers

El stack del inicio rápido crea un entorno y ejecuta sus workers. Lo mismo hacen los charts de Helm de Implementar en Kubernetes. Si esos workers son todo lo que necesitas, omite esta sección.

Ejecutas los workers como lo haces con los sandboxes autoalojados: los mismos comandos ant beta:worker y workers del SDK, de las formas que muestra Implementar workers autoalojados. La excepción son los workers activados por webhooks, porque tu servidor no envía ninguno.

Crear un entorno y su clave

Crea un entorno y una clave de entorno con la CLI de administración, no en la Claude Console. La CLI, cma-server-admin, está en el nivel superior del archivo de la versión, así que ejecuta el comando desde allí. Para -base-url, pasa la dirección en la que tus workers llegan al servidor:

• Workers en la máquina que ejecuta el stack del inicio rápido: http://127.0.0.1:8400
• Workers en otra máquina: la dirección https del proxy TLS que colocas delante del servidor

La CLI de administración llama al servidor en la misma dirección, así que ejecútala en una máquina que pueda alcanzar esa dirección.

echo "$ANTHROPIC_API_KEY" | ./cma-server-admin bootstrap \
  -base-url http://127.0.0.1:8400 -name my-env -key-file -

El comando imprime la configuración del worker, el comando que inicia un worker, y el ID y la fecha de caducidad de la clave:

export ANTHROPIC_BASE_URL='http://127.0.0.1:8400'
export ANTHROPIC_ENVIRONMENT_ID='env_...'
export ANTHROPIC_ENVIRONMENT_KEY='sk-ant-oat01-...'
# then: histchars= HISTFILE=/dev/null ant beta:worker poll --workdir /workspace
# key id: 'etok_...'  expires: '...'

El comando muestra la clave solo una vez, así que guarda la clave, su ID y su fecha de caducidad en tu gestor de secretos. La clave deja de funcionar después de 365 días. Antes de eso, sigue Reemplazar una clave de entorno para tus propios workers.

Mantén la clave de API del servidor fuera de las máquinas que ejecutan workers. Ejecuta los workers en un contenedor o máquina virtual que no contenga nada que necesites proteger. Para tus demás responsabilidades de seguridad, consulta Tus responsabilidades de seguridad.

Ejecutar un experimento local

Ejecuta las tres líneas export en el shell donde inicias el worker. Luego inicia el worker con estos comandos, no con el que se imprimió. El primer comando crea el directorio de trabajo del worker, porque el worker no lo crea:

mkdir -p "$HOME/cma-workspace" "$HOME/.config/cma"
cat > "$HOME/.config/cma/worker.inputrc" <<'EOF'
$include /etc/inputrc
set disable-completion on
EOF
histchars= HISTFILE=/dev/null INPUTRC="$HOME/.config/cma/worker.inputrc" \
  ant beta:worker poll --workdir "$HOME/cma-workspace"

histchars, INPUTRC y HISTFILE configuran el shell detrás de la herramienta bash del worker, para que ejecute cada comando tal como lo escribió el agente:

• histchars=: El shell no interpreta ! como una referencia a su historial de comandos.
• INPUTRC: El archivo desactiva el “completion” (autocompletado), que de otro modo consumiría cada carácter de tabulación de un comando. Mantén el archivo fuera del directorio de trabajo, donde las herramientas de archivos del agente podrían reescribirlo.
• HISTFILE=/dev/null: El shell no lee ni escribe ningún archivo de historial.

No uses este worker para nada más. Contiene la clave de entorno y ejecuta las herramientas de todas las sesiones en un solo proceso. Tampoco clona los repositorios de una sesión. La sesión se ejecuta sin ellos, y tu cliente no recibe ningún error.

Ejecutar workers en producción

Para cualquier caso que no sea un experimento local, inicia un contenedor para cada sesión y ejecuta ant beta:worker run en él, como se muestra en Ejecutar un sandbox por sesión. Dale a su imagen lo que enumera Crear tu propia imagen de sandbox y cambia tres cosas en esa configuración:

• Clave de entorno: No pases ANTHROPIC_ENVIRONMENT_KEY al contenedor de una sesión. El servidor acepta esa clave para todas las sesiones del entorno, y el contenedor solo necesita acceso a una sesión.
• Secreto del elemento de trabajo: Pasa este secreto en lugar de la clave, porque el servidor lo acepta solo para esa sesión. Reenvía el secreto del elemento de trabajo muestra dónde lo recibe tu código. Donde esa sección establece ANTHROPIC_WORK_SECRET, coloca el secreto en un archivo que solo el usuario del contenedor pueda leer. Por ejemplo, canaliza el secreto a la entrada estándar del contenedor y haz que el contenedor escriba el archivo antes de iniciar el worker. Luego establece ANTHROPIC_WORK_SECRET_FILE en la ruta del archivo.
• Dirección del servidor: Establece ANTHROPIC_BASE_URL en una dirección que el contenedor pueda alcanzar. http://127.0.0.1:8400 no lo es.

Para un worker del SDK, se aplican dos puntos más:

• Versión: Compila el worker con la versión más reciente del SDK, como se describe en SDKs, CLI y bibliotecas. El worker de esa versión espera la aprobación antes de ejecutar una llamada a herramienta que la necesite, y nunca ejecuta una llamada que una política deniega. Un worker compilado con una versión anterior ejecuta cada llamada a herramienta en cuanto llega.
• Ejemplos: Los ejemplos de Ejecutar el worker del SDK dentro del sandbox leen la clave de entorno, así que no funcionan aquí tal como están.

Crear tu propia imagen de sandbox

Una imagen propia necesita estos paquetes y ajustes:

• Paquetes: Git 2.38 o posterior, curl, jq y ripgrep, con el que busca la herramienta grep del worker.

• Ajustes del shell: histchars, HISTFILE e INPUTRC, como en el experimento local, y TERMINFO. Coloca estas líneas en el Dockerfile, antes de cualquier línea USER:

  ENV histchars=
  RUN printf '\nset disable-completion on\n' >> /etc/inputrc
  ENV INPUTRC=/etc/inputrc TERMINFO=/etc/terminfo HISTFILE=/dev/null
  RUN test -r /etc/terminfo/d/dumb

  

  TERMINFO debe indicar el directorio que contiene d/dumb, la descripción de terminal que lee el bash del worker. En Alpine con bash instalado, es /etc/terminfo, como se muestra. En otra base, como Debian o Ubuntu, es /lib/terminfo o /usr/share/terminfo, el que contenga d/dumb. Escribe ese directorio en el ajuste TERMINFO y en la línea RUN test, que detiene la compilación si falta el archivo.

La imagen también necesita dos scripts del archivo, que se ejecutan antes de que se inicie el worker:

1. Copia image-build/with-repositories.sh a /usr/local/bin/cma-with-repositories. Clona los repositorios de una sesión.
2. Copia image-build/with-egress.sh a /usr/local/bin/cma-with-egress. Dirige las herramientas de la sesión al gateway de salida, si tu servidor ejecuta uno.
3. Haz ejecutables ambos archivos.
4. Coloca ambos delante del comando del worker, como en cma-with-egress cma-with-repositories ant beta:worker run .... Omite este paso si tu imagen ejecuta el kubernetes/sandbox/worker.sh del archivo, porque ese script inicia el worker de esta manera.

Un worker que se inicia sin cma-with-repositories ejecuta la sesión sin ningún repositorio. Tu cliente no recibe ningún error.

Trasladar workers desde el servicio alojado

Si ya ejecutas workers para el servicio alojado de Anthropic, esos mismos workers pueden servir a tu servidor en su lugar. Haz tres cosas:

• Pasa al proceso que sondea en busca de trabajo los tres valores export que imprimió la CLI de administración.
• Inicia ese proceso con histchars, HISTFILE e INPUTRC definidas, como en el experimento local.
• Aplica los cambios que describe Ejecutar workers en producción y compara la imagen de cada sesión con Crear tu propia imagen de sandbox.

Próximos pasos

• Permitir que los desarrolladores inicien sesión desde una terminal: Configura el inicio de sesión único, para que los desarrolladores usen la CLI ant con su propia identidad, en una terminal sin ANTHROPIC_API_KEY.
• Identidad y credenciales del agente: Permite que los sistemas externos confíen en tus agentes y mantén las credenciales de vault en tu gestor de secretos.
• Proveedor de inferencia: Envía las llamadas al modelo a un proveedor de nube o a tu propio gateway de modelos.