Chamar a API em um servidor auto-hospedado

Um servidor auto-hospedado do Claude Managed Agents tem a mesma API que o serviço hospedado do Managed Agents da Anthropic. Seu código o chama com o SDK oficial, o cURL ou o ant CLI. Duas coisas mudam: a “base URL” (URL base) é o endereço do seu servidor, e a chave de API é a sua chave de API do servidor em vez de uma chave de API do Claude.

Para criar agentes e executar sessões em um navegador, consulte Usar o console no seu servidor.

Pré-requisitos

• Um servidor em execução: Inicie um com Comece a usar o Claude Managed Agents auto-hospedado ou Implantar no Kubernetes.
• Acesso ao servidor: Se outra pessoa executa o servidor, peça a ela o endereço dele e como se autenticar. Se ela usa single sign-on, consulte Permita que desenvolvedores façam login a partir de um terminal.
• O CLI ant: Instale a versão mais recente, como mostra o início rápido da CLI.

Apontar o seu cliente para o seu servidor

O SDK e a CLI ant leem o endereço do servidor de ANTHROPIC_BASE_URL e a chave de API de ANTHROPIC_API_KEY. Defina as duas variáveis em um terminal que você reservar para este servidor.

Para a stack do início rápido, execute estes comandos a partir do diretório que contém o seu arquivo .env:

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

No Kubernetes, defina as duas variáveis como mostra Executar uma sessão e mantenha o port-forward dele em execução.

Nesse terminal, todo comando ant, como ant beta:agents list, chega ao seu servidor. Não execute o Claude Code nem o docker compose nesse terminal, porque eles leem as mesmas variáveis.

Iniciar uma sessão

Uma sessão precisa do ID de um agente e do ID de um ambiente:

• Agente: Crie um como mostra Criar um agente, com o seu cliente apontado para o seu servidor. Se você envia requisições HTTP diretas, substitua https://api.anthropic.com na URL por $ANTHROPIC_BASE_URL.
• Ambiente: A stack do início rápido cria um chamado compose-sandbox, e os Helm charts criam um chamado default. ant beta:environments list imprime o nome e o ID de cada ambiente. Para os seus próprios workers, é o ID que a CLI de administração imprimiu em Executar os seus próprios workers.

Coloque os seus dois IDs no seu shell, no lugar destes IDs de exemplo:

export AGENT_ID=agent_011CYm1BLqPXpQRk5khsSXrs
export ENVIRONMENT_ID=env_01595EKxaaTTGwwY3kyXdtbs

O exemplo a seguir cria uma sessão e envia sua primeira mensagem na mesma requisição:

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)

A resposta contém o ID da sessão, que começa com sesn_. O agente começa a trabalhar imediatamente. Suas ferramentas integradas, como bash, são executadas em um worker que serve o ambiente.

Para acompanhar a sessão, abra o console do seu servidor em um navegador, selecione Sessions e, em seguida, selecione a sessão. Uma sessão que você iniciou com a chave de API do servidor, como nesta página, aparece apenas para administradores.

Para acompanhar a sessão no seu terminal em vez disso, passe o ID dela para ant beta:sessions connect:

ant beta:sessions connect sesn_011CZkZAtmR3yMPDzynEDxu7

Para saber o que mais uma sessão pode fazer, como fixar uma versão do agente, consulte Iniciar uma sessão.

Enviar uma mensagem e ler a resposta

Coloque o ID da sua sessão no seu shell, no lugar deste ID de exemplo:

export SESSION_ID=sesn_011CZkZAtmR3yMPDzynEDxu7

Aguarde até que a sessão esteja ociosa antes de executar o próximo exemplo. O exemplo para de ler quando um turno termina. Se um turno anterior ainda estiver em execução, o fim dele pode parar o exemplo antes que a resposta à sua mensagem chegue. O console e o ant beta:sessions connect mostram o status da sessão.

O exemplo a seguir envia uma mensagem e imprime a resposta do agente. Ele abre o stream de eventos da sessão primeiro, porque um stream entrega apenas os eventos que ocorrem depois que ele é aberto:

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

Além de imprimir o texto de agent.message, o loop trata três eventos:

• session.status_idle: O loop termina, a menos que o stop_reason.type do evento seja requires_action.
• session.status_terminated: O loop termina.
• session.error: O loop imprime a mensagem do erro e continua lendo, porque o servidor pode repetir uma chamada ao modelo que falhou e concluir o turno.

requires_action significa que a sessão pausou para uma chamada de ferramenta. O que encerra a pausa depende da chamada:

• Uma chamada de ferramenta personalizada ou uma requisição para confirmar uma chamada de ferramenta: Somente o seu código pode respondê-la. Se o seu agente usa alguma delas, consulte Responder a chamadas de ferramenta que pausam a sessão.
• Uma chamada a uma ferramenta que um worker executa, como bash: Essa chamada normalmente não pausa a sessão. Se nenhum worker assumir a chamada por cerca de 3 minutos, a sessão pausa até que um worker retorne o resultado. O seu código não tem nada a responder nesse caso. Mantenha o stream aberto, e o turno é retomado quando um worker executar a chamada.

Para os outros eventos que uma sessão envia e para saber como se reconectar sem perder nenhum, consulte Stream de eventos da sessão.

Mover dados para dentro e para fora de uma sessão

Os dados chegam a uma sessão e saem dela pelo diretório de trabalho do worker.

Na stack do início rápido, o contêiner de cada sessão começa com um diretório /workspace vazio, exceto pelos clones dos repositórios da sessão. Por padrão, cerca de um minuto depois que um turno termina, o contêiner encerra, e o Docker o exclui junto com esse diretório. Qualquer coisa que uma sessão precise manter tem que sair por meio de uma chamada de ferramenta, como um upload ou um git push, antes disso.

Um contêiner também encerra cerca de uma hora depois de iniciar, mesmo no meio de um turno. Nenhuma configuração muda isso. O turno continua em um novo contêiner, geralmente depois de um ou dois minutos, e o seu cliente não recebe nenhum evento pela troca. A troca tem dois custos:

• Comandos: Tudo o que é executado no contêiner antigo para. O novo contêiner executa a chamada de ferramenta interrompida novamente desde o início, mas nada reinicia um comando que o agente deixou em execução em segundo plano.
• Arquivos: O /workspace do novo contêiner fica vazio de novo, exceto por clones novos dos repositórios da sessão.

Em um turno longo, faça o agente enviar ou fazer push do trabalho dele à medida que avança, e evite comandos que causem danos se forem executados duas vezes.

No Kubernetes, uma sessão mantém um pod por cerca de uma hora no máximo, e o turno continua da mesma forma. Duas coisas são diferentes: o novo pod encontra os arquivos da sessão em /workspace, e ele inicia cerca de 6 minutos depois que o pod antigo para.

Para workers que você mesmo inicia, coloque os arquivos de entrada no diretório de trabalho antes de enviar a mensagem que precisa deles. Leia os arquivos de saída dele depois.

Quando você mesmo inicia um contêiner para cada sessão, monte um diretório que contenha os arquivos de entrada da sessão como o diretório de trabalho do contêiner. Colete os arquivos de saída dele depois que o contêiner terminar. Consulte Preparar arquivos para uma sessão.

Encontrar mais exemplos nos guias do serviço hospedado

Os guias do serviço hospedado explicam os conceitos principais da API e têm exemplos para cada recurso. Os exemplos de SDK e CLI desses guias chamam o seu servidor quando você os executa no terminal em que ANTHROPIC_BASE_URL e ANTHROPIC_API_KEY estão definidas. Os exemplos de cURL desses guias usam o endereço https://api.anthropic.com, então substitua esse endereço por $ANTHROPIC_BASE_URL antes de executar um deles.

Para alguns recursos, o seu servidor precisa primeiro de uma configuração, ou um exemplo precisa de uma alteração:

Diferenças em relação ao serviço hospedado tem a lista completa. Consulte-a antes de migrar uma aplicação existente.

Executar os seus próprios workers

A stack do início rápido cria um ambiente e executa os workers dele. Os Helm charts de Implantar no Kubernetes também fazem isso. Se esses workers forem tudo de que você precisa, pule esta seção.

Você executa workers da mesma forma que faz com os sandboxes auto-hospedados: os mesmos comandos ant beta:worker e workers do SDK, das formas que Implantar workers auto-hospedados mostra. A exceção são os workers acionados por webhooks, porque o seu servidor não envia nenhum.

Criar um ambiente e a chave dele

Crie um ambiente e uma chave de ambiente com o CLI de administração, não no Claude Console. O CLI, cma-server-admin, fica no topo do arquivo compactado da versão, então execute o comando a partir dali. Em -base-url, passe o endereço pelo qual os seus workers alcançam o servidor:

• Workers na máquina que executa a stack do início rápido: http://127.0.0.1:8400
• Workers em outra máquina: o endereço https do proxy TLS que você coloca na frente do servidor

O CLI de administração chama o servidor no mesmo endereço, então execute-o em uma máquina que consiga alcançar esse endereço.

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

O comando imprime as configurações do worker, o comando que inicia um worker, e o ID e a expiração da chave:

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: '...'

O comando exibe a chave apenas uma vez, então armazene a chave, o ID dela e a expiração no seu gerenciador de segredos. A chave para de funcionar após 365 dias. Antes disso, siga Substituir uma chave de ambiente para os seus próprios workers.

Mantenha a chave de API do servidor fora das máquinas que executam workers. Execute workers em um contêiner ou VM que não contenha nada que você precise proteger. Para as suas outras obrigações de segurança, consulte Suas responsabilidades de segurança.

Executar um experimento local

Execute as três linhas export no shell em que você inicia o worker. Em seguida, inicie o worker com estes comandos, não com o que foi impresso. O primeiro comando cria o diretório de trabalho do worker, porque o worker não o cria:

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 e HISTFILE configuram o shell por trás da ferramenta bash do worker, para que ele execute cada comando exatamente como o agente o escreveu:

• histchars=: O shell não trata ! como uma referência ao seu histórico de comandos.
• INPUTRC: O arquivo desativa o completamento, que de outra forma consumiria cada caractere de tabulação em um comando. Mantenha o arquivo fora do diretório de trabalho, onde as ferramentas de arquivo do agente poderiam reescrevê-lo.
• HISTFILE=/dev/null: O shell não lê nem grava um arquivo de histórico.

Não use este worker para mais nada. Ele guarda a chave de ambiente e executa as ferramentas de todas as sessões em um único processo. Ele também não clona os repositórios de uma sessão. A sessão é executada sem eles, e o seu cliente não recebe nenhum erro.

Executar workers em produção

Para qualquer uso além de um experimento local, inicie um contêiner para cada sessão e execute ant beta:worker run nele, como mostra Executar um sandbox por sessão. Forneça à imagem dele o que Criar a sua própria imagem de sandbox lista e altere três coisas nessa configuração:

• Chave de ambiente: Não passe ANTHROPIC_ENVIRONMENT_KEY para o contêiner de uma sessão. O servidor aceita essa chave para todas as sessões do ambiente, e o contêiner precisa de acesso a apenas uma sessão.
• Segredo do item de trabalho: Passe este segredo no lugar da chave, porque o servidor o aceita apenas para essa única sessão. Encaminhar o segredo do item de trabalho mostra onde o seu código o recebe. Onde essa seção define ANTHROPIC_WORK_SECRET, coloque o segredo em um arquivo que apenas o usuário do contêiner pode ler. Por exemplo, envie o segredo por pipe para a entrada padrão do contêiner e faça o contêiner gravar o arquivo antes de iniciar o worker. Em seguida, defina ANTHROPIC_WORK_SECRET_FILE como o caminho do arquivo.
• Endereço do servidor: Defina ANTHROPIC_BASE_URL como um endereço que o contêiner consiga alcançar. http://127.0.0.1:8400 não é um deles.

Para um worker do SDK, valem mais dois pontos:

• Versão: Crie o worker com a versão mais recente do SDK, conforme descrito em SDKs, CLI e bibliotecas. O worker dessa versão aguarda aprovação antes de executar uma chamada de ferramenta que precisa dela e nunca executa uma chamada que uma política nega. Um worker criado com uma versão anterior executa toda chamada de ferramenta assim que ela chega.
• Exemplos: Os exemplos em Executar o worker do SDK dentro do sandbox leem a chave de ambiente, então não funcionam aqui como estão.

Criar a sua própria imagem de sandbox

Uma imagem própria precisa destes pacotes e configurações:

• Pacotes: Git 2.38 ou posterior, curl, jq e ripgrep, que a ferramenta grep do worker usa para fazer buscas.

• Configurações do shell: histchars, HISTFILE e INPUTRC, como no experimento local, e TERMINFO. Coloque estas linhas no Dockerfile, antes de qualquer linha 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 precisa indicar o diretório que contém d/dumb, a descrição de terminal que o bash do worker lê. No Alpine com bash instalado, esse diretório é /etc/terminfo, como mostrado. Em outra base, como Debian ou Ubuntu, é /lib/terminfo ou /usr/share/terminfo, o que contiver d/dumb. Escreva esse diretório na configuração TERMINFO e na linha RUN test, que interrompe o build se o arquivo estiver faltando.

A imagem também precisa de dois scripts do arquivo compactado, que são executados antes de o worker iniciar:

1. Copie image-build/with-repositories.sh para /usr/local/bin/cma-with-repositories. Ele clona os repositórios de uma sessão.
2. Copie image-build/with-egress.sh para /usr/local/bin/cma-with-egress. Ele aponta as ferramentas da sessão para o “egress gateway” (gateway de saída), se o seu servidor executar um.
3. Torne os dois arquivos executáveis.
4. Coloque os dois na frente do comando do worker, como em cma-with-egress cma-with-repositories ant beta:worker run .... Pule esta etapa se a sua imagem executa o kubernetes/sandbox/worker.sh do arquivo compactado, porque esse script inicia o worker dessa forma.

Um worker que é iniciado sem cma-with-repositories executa a sessão sem nenhum repositório. O seu cliente não recebe nenhum erro.

Migrar workers do serviço hospedado

Se você já executa workers para o serviço hospedado da Anthropic, os mesmos workers podem servir o seu servidor em vez disso. Faça três coisas:

• Passe para o processo que faz o polling de trabalho os três valores export que o CLI de administração imprimiu.
• Inicie esse processo com histchars, HISTFILE e INPUTRC definidos, como no experimento local.
• Faça as alterações que Executar workers em produção descreve e verifique a imagem de cada sessão em relação a Criar a sua própria imagem de sandbox.

Próximos passos

• Permita que desenvolvedores façam login a partir de um terminal: Configure o single sign-on, para que os desenvolvedores usem o CLI ant com a própria identidade, em um terminal sem ANTHROPIC_API_KEY.
• Identidade e credenciais do agente: Permita que sistemas externos confiem nos seus agentes e mantenha as credenciais de vault no seu gerenciador de segredos.
• Provedor de inferência: Envie chamadas ao modelo para um provedor de nuvem ou para o seu próprio gateway de modelos.