---
title: Diferenças em relação ao serviço hospedado
url: https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/differences
description: Veja quais recursos só o Claude Managed Agents auto-hospedado tem, quais recursos hospedados ele não tem, quais se comportam de forma diferente e quais precisam primeiro de uma configuração do servidor.
---
Para solicitar acesso ao Claude Managed Agents auto-hospedado, entre em contato com a equipe da sua conta na Anthropic.
Um servidor auto-hospedado do Claude Managed Agents tem a mesma API do serviço hospedado [Managed Agents](https://platform.claude.com/docs/pt-BR/managed-agents/overview) da Anthropic, exceto pelas diferenças desta página. As tabelas dizem o que fazer em cada caso. Consulte-as antes de mover uma aplicação para o seu servidor. Nada é copiado do serviço hospedado, incluindo o histórico de sessões. Crie novamente seus agentes, skills, credenciais de vault e memory stores no seu servidor.
## Recursos que só o seu servidor tem
| Recurso | O que faz | Como configurar |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Escolha do provedor de inferência | O servidor pode enviar chamadas de modelo para um provedor de nuvem ou seu próprio gateway de modelos em vez da Claude API. | [Provedor de inferência](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/inference-provider) |
| Single sign-on | As pessoas chamam o servidor com um token do seu provedor de identidade OpenID Connect. O servidor atribui a cada chamador uma função a partir dos grupos no token. A chave de API do servidor continua funcionando. | [Single sign-on](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/configure#single-sign-on) |
| Seu próprio gerenciador de segredos | O servidor pode armazenar o segredo de cada nova credencial de vault no seu gerenciador de segredos em vez de em seu próprio banco de dados. | [Gerenciador de segredos](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/agent-identity#secret-manager) |
| Identidade do agente | O servidor pode assinar um token de curta duração e enviar esse token com as chamadas de um agente para um servidor MCP. O servidor MCP ou o gateway verifica o token com base em chaves públicas que você publica. | [Identidade do agente](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/agent-identity#agent-identity) |
## Recursos que não estão disponíveis
| Recurso | O que acontece | O que fazer em vez disso |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Ambientes de nuvem](https://platform.claude.com/docs/pt-BR/managed-agents/environments) | Só existem ambientes `self_hosted`. Uma requisição de um ambiente de nuvem retorna um erro `400`. | [Implante workers auto-hospedados](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-workers) para todos os ambientes. |
| O restante da Claude API, como a [Messages API](https://platform.claude.com/docs/pt-BR/build-with-claude/working-with-messages) e a Models API | O servidor não o atende. As chamadas do SDK para `/v1/messages` e `/v1/models` retornam um erro `404`. | Envie essas requisições para a Claude API ou para o seu provedor, a partir de um cliente que não aponte para o seu servidor. |
| [Recursos de sessão de arquivo](https://platform.claude.com/docs/pt-BR/managed-agents/files) e a Files API | O servidor rejeita recursos `file`, e `/v1/files` não existe. Recursos `memory_store` funcionam. | Coloque os arquivos no diretório de trabalho do worker. Consulte [Mover dados para dentro e para fora de uma sessão](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/call-the-api#move-data-in-and-out-of-a-session). Para mostrar uma imagem ou um PDF ao modelo, envie-o como `base64` em uma mensagem. |
| [Credenciais de vault `mcp_oauth`](https://platform.claude.com/docs/pt-BR/managed-agents/vaults) | O servidor as rejeita quando você as cria, porque não tem um fluxo OAuth para renovar um token. | Armazene o token como uma credencial `static_bearer`. Atualize a credencial com um novo token antes que o antigo expire. |
| [Skills predefinidas `docx`, `pdf`, `pptx` e `xlsx`](https://platform.claude.com/docs/pt-BR/managed-agents/skills) | O servidor rejeita um agente que as declara. Só existem as skills que você envia. | Baixe o código-fonte delas no [repositório de skills](https://github.com/anthropics/skills) e envie-as como skills personalizadas. |
| [Implantações agendadas](https://platform.claude.com/docs/pt-BR/managed-agents/scheduled-deployments) e [dreams](https://platform.claude.com/docs/pt-BR/managed-agents/dreams) | O servidor não tem rotas para eles. | Inicie sessões a partir do seu próprio agendador, como um cron job. Dreams não têm substituto. |
| [Webhooks](https://platform.claude.com/docs/pt-BR/managed-agents/webhooks) | O servidor não envia webhooks, então um worker que é iniciado por um webhook nunca é iniciado. | Acompanhe uma sessão pelo seu [stream de eventos](https://platform.claude.com/docs/pt-BR/managed-agents/events-and-streaming) ou liste os eventos dela. Mantenha seus workers em execução para que eles possam fazer polling. |
## Recursos que se comportam de forma diferente
| Recurso | O que é diferente | O que fazer |
| --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Claude Console | O Claude Console em platform.claude.com não mostra o que está no seu servidor. | Use o [console no seu servidor](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/console). |
| Chamadas de ferramenta | Os turnos de modelo de uma sessão são executados mesmo quando nenhum worker está fazendo polling no ambiente dela. A primeira chamada de ferramenta então aguarda, sem erro, até que um worker a execute. | Se uma sessão parar em uma chamada de ferramenta, verifique se um worker está fazendo polling no ambiente dela. |
| [Memory stores](https://platform.claude.com/docs/pt-BR/managed-agents/memory) | A API está completa. O worker, e não o servidor, copia cada store anexado para o sandbox e grava as alterações de volta. Consulte [Memory stores em sandboxes auto-hospedados](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-memory). | Execute seus workers na [versão mais recente do `ant`](https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/cli/quickstart#installation), com um diretório `/mnt/memory` gravável. |
| Envios de [skills personalizadas](https://platform.claude.com/docs/pt-BR/managed-agents/skills#create-a-custom-skill) | O servidor não descompacta um arquivo zip. O envio de um arquivo zip retorna um erro `400` que diz `SKILL.md not found in uploaded files`. | `ant apply` e o auxiliar `files_from_dir` do SDK de Python funcionam como estão. Com qualquer outra coisa, envie os arquivos da skill como partes separadas e comece o nome de arquivo de cada parte com a pasta da skill, como em `my-skill/SKILL.md`. |
| [Orquestração multiagente](https://platform.claude.com/docs/pt-BR/managed-agents/multiagent-orchestration) | Um agente só pode delegar para subagentes que você lista. Fluxos de trabalho dinâmicos, o advisor e subagentes que o próprio agente define não estão disponíveis. O servidor aceita um bloco `multiagent` (csharp, go: `Multiagent`) apenas se o `type` dele for `coordinator`. Os exemplos em Orquestração multiagente definem `type` como `multiagent_20261001`, que retorna um erro `400`. Um bloco que tenha uma configuração `advisor` (csharp, go: `Advisor`) também retorna um erro `400`. | Defina `multiagent` (csharp, go: `Multiagent`) como `{"type": "coordinator", "agents": [...]}`. Liste de 1 a 20 agentes em `agents` (csharp, go: `Agents`). Cada entrada assume uma das [formas de um agente predefinido](https://platform.claude.com/docs/pt-BR/managed-agents/multiagent-orchestration#predefined-and-inline-agents). |
| Recursos de sessão de [repositório do GitHub](https://platform.claude.com/docs/pt-BR/managed-agents/github) | O servidor rejeita recursos `github_repository` até que você liste os hosts Git deles nas configurações do servidor. O servidor não descobre skills no diretório `.claude/skills` de um repositório, então anexe as skills ao agente. | Consulte [Repositórios Git precisam de uma entrada na allowlist](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/differences#git-repositories-need-an-allowlist-entry). |
| [Servidores MCP](https://platform.claude.com/docs/pt-BR/managed-agents/mcp-connector) | O servidor se conecta apenas aos hosts MCP que você lista nas configurações dele. | Consulte [Servidores MCP precisam de uma entrada na allowlist](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/differences#mcp-servers-need-an-allowlist-entry). |
| [Ferramentas web](https://platform.claude.com/docs/pt-BR/managed-agents/tools-web-restrictions) | As ferramentas `web_search` e `web_fetch` ficam desativadas até que você as ative nas configurações do servidor. | Consulte [Ferramentas web precisam de uma configuração do servidor](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/differences#web-tools-need-a-server-setting). |
| [Credenciais de vault `environment_variable`](https://platform.claude.com/docs/pt-BR/managed-agents/vaults) | O servidor as rejeita até que você ative o gateway de saída, um proxy entre os seus sandboxes e a internet. | Consulte [Credenciais de variável de ambiente](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/agent-identity#environment-variable-credentials). Sem o gateway, forneça ao seu sandbox as credenciais de CLI e de API de que ele precisa por meio das suas próprias ferramentas. |
| Resultados de ferramentas personalizadas | O servidor envia ao modelo o texto inteiro de um resultado de ferramenta personalizada. Se um resultado for grande demais para a “context window” (janela de contexto) do modelo, o servidor ainda responde com `200`, e a sessão então termina com um `session.error`. | Encurte resultados longos no seu cliente antes de enviá-los. |
| Resultados de ferramentas MCP | O servidor corta um resultado que seja maior que a configuração `mcp.max_result_bytes` dele, que é de 100 KiB por padrão. Ele informa ao modelo que o resultado foi cortado, e o restante é perdido. O serviço hospedado também corta resultados longos, mas pode [salvar o resultado completo em um arquivo](https://platform.claude.com/docs/pt-BR/managed-agents/mcp-connector#mcp-tool-output-handling) para uma sessão em um sandbox de nuvem. | Para alterar o limite, defina `mcp.max_result_bytes` no [arquivo de configurações](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/configuration-reference#where-settings-go). |
| Imagens e documentos enviados por URL | O servidor aceita um bloco `image` ou `document` com uma origem `url`, mas o modelo nunca o vê, e não há erro. O mesmo acontece com um bloco `image` com uma origem `file`. | Envie os dados como `base64`, ou como `text` no caso de um documento. |
| O status de sessão `rescheduling` | O servidor tenta novamente uma chamada de modelo que falha por um motivo passageiro e informa cada tentativa no stream de eventos, como o serviço hospedado faz. O status da sessão permanece `running` entre as tentativas, então um filtro `statuses[]=rescheduling` não corresponde a nenhuma sessão. | Leia as novas tentativas no stream de eventos. |
| Metadados de sessão, com um gateway de modelos | Se a configuração `inference.credentials.assertion.forward_metadata` do servidor listar chaves de metadados de sessão, uma atualização que adicione, remova ou altere uma delas retorna um erro `400`. | Defina essas chaves ao criar a sessão. Para a configuração, consulte [Tokens de gateway de curta duração](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/configuration-reference#short-lived-gateway-tokens). |
## Recursos que precisam de uma configuração do servidor
Cada um desses recursos fica desativado, ou recusa todos os hosts, até que você altere o [arquivo de configurações](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/configuration-reference#where-settings-go) do servidor.
### Servidores MCP precisam de uma entrada na allowlist
O servidor se conecta apenas a servidores MCP cujos hosts você lista em `mcp.allowed_hostnames` no [arquivo de configurações](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/configuration-reference#where-settings-go) dele:
```yaml
mcp:
allowed_hostnames:
- mcp.example.com
```
Os hosts correspondem exatamente, sem curingas e sem subdomínios, e a lista fica vazia por padrão. Até que o host de um servidor MCP esteja na lista, seu servidor se recusa a salvar um agente que o mencione.
Um servidor MCP dentro da sua rede privada não precisa de um [túnel MCP](https://platform.claude.com/docs/pt-BR/agents-and-tools/mcp-tunnels/overview). Coloque a URL dele na definição do agente, como descreve o [Conector MCP](https://platform.claude.com/docs/pt-BR/managed-agents/mcp-connector), e adicione o host dele à allowlist. Duas regras se aplicam à URL:
* Ela deve usar `https`, a menos que o servidor MCP esteja no endereço de loopback.
* Se o host dela for um nome que resolve apenas para endereços privados ou reservados, seu servidor se recusa a se conectar por padrão. Escolha a correção adequada ao seu caso:
| Seu caso | Correção |
| -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| O endereço está em `10.0.0.0/8`, `172.16.0.0/12` ou `192.168.0.0/16`, e você controla os registros DNS do nome | Mantenha o nome e liste-o também em `mcp.private_hostnames` no arquivo de configurações. |
| Qualquer outro caso | Use o endereço IP no lugar do nome, na URL e na allowlist. O certificado do servidor MCP precisa nomear esse endereço. |
### Repositórios Git precisam de uma entrada na allowlist
No serviço hospedado, sessões que usam [sandboxes auto-hospedados](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes#session-resources) não podem ter recursos `github_repository`. No seu servidor, elas podem. O servidor rejeita esses recursos até que você liste os hosts Git deles no [arquivo de configurações](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/configuration-reference#where-settings-go) dele. Os agentes podem fazer push apenas para os branches que você lista:
```yaml
git:
allowed_hostnames:
- github.com
allowed_push_refs:
- refs/heads/agent/
```
Observe estes pontos:
* **URL:** O host não precisa ser `github.com`, mas a URL deve usar HTTPS.
* **Token:** O token que seu cliente envia nunca chega ao sandbox, porque o tráfego Git passa pelo seu servidor, que adiciona o token.
* **Branches:** Os agentes não são informados da lista de branches, então nomeie um branch no seu prompt.
* **Force pushes:** O servidor não recusa force pushes, então um agente pode sobrescrever qualquer branch que você lista. Para recusar force pushes, proteja o branch no seu host Git.
[Acessar o GitHub](https://platform.claude.com/docs/pt-BR/managed-agents/github) mostra a requisição e como fazer a rotação de um token. Se um clone falhar, a sessão recebe um evento `session.error` que informa a causa. Para verificar um push, procure o branch no seu host Git. O log do servidor diz `ok` mesmo para um push que o seu host recusou.
### Ferramentas web precisam de uma configuração do servidor
As ferramentas `web_search` e `web_fetch` ficam desativadas por padrão. Para ativá-las, adicione isto ao [arquivo de configurações](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/configuration-reference#where-settings-go) do servidor:
```yaml
web_tools:
enabled: true
```
Apenas com essa configuração, as próprias listas de domínios e o próprio limite de conteúdo de cada agente se aplicam, como no serviço hospedado.
Para limitar as ferramentas para todos os agentes, defina `web_tools.allowed_domains`, `web_tools.blocked_domains` ou `web_tools.max_content_tokens`. Cada uma dessas configurações também ativa as ferramentas. O servidor se recusa a salvar um agente que peça mais do que essas configurações permitem. Por exemplo, ele recusa um agente que permita um domínio fora de `web_tools.allowed_domains` ou que defina um limite de conteúdo maior. Se esse agente já existir, ele não poderá iniciar uma sessão até que você o atualize.
Enquanto as ferramentas estiverem desativadas, o que acontece com um agente depende das entradas `web_search` e `web_fetch` no conjunto de ferramentas dele:
| O conjunto de ferramentas tem | O que acontece |
| ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| Nenhuma entrada para nenhuma das duas ferramentas | O agente é executado sem as ferramentas, e nenhum erro informa isso. |
| Uma entrada que apenas desativa a sua ferramenta, como `{"name": "web_fetch", "enabled": false}` | O mesmo. |
| Uma entrada que deixa a sua ferramenta ativada, ou que define as listas de domínios, o limite de conteúdo ou a localização dela | O servidor se recusa a salvar o agente, ou a iniciar uma sessão para ele. |
Quais ferramentas web existem também [depende do seu provedor de inferência](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/differences#differences-that-depend-on-your-inference-provider).
## Diferenças que dependem do seu provedor de inferência
Alguns recursos funcionam apenas com alguns valores da configuração `inference.provider` do servidor. A tabela mostra o que acontece com os outros valores. Alguns desses casos não retornam nenhum erro.
As linhas de `web_search` e `web_fetch` se aplicam depois que você [ativa as ferramentas web](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/differences#web-tools-need-a-server-setting). Até lá, nenhuma das duas ferramentas funciona com nenhum provedor.
| Recurso | Funciona quando `inference.provider` é | Com os outros valores | O que fazer |
| ----------------------------------------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Ferramenta `web_search` | `anthropic`, `vertex`, `foundry` | O servidor nunca oferece a ferramenta ao modelo. Os agentes ainda são salvos e executados, e ainda listam a ferramenta, mas o modelo não consegue chamá-la. | Dê ao agente uma ferramenta personalizada ou um servidor MCP que faça buscas. |
| Ferramenta `web_fetch` | `anthropic`, `foundry` | O mesmo que para `web_search`. | Dê ao agente uma ferramenta personalizada ou um servidor MCP que busque páginas. |
| `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) | `anthropic` | O servidor se recusa a salvar um agente que o defina. | Remova `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) do agente. |
| Modo rápido (`speed: "fast"`) | Depende do provedor e do modelo do agente | Um agente que o defina precisa passar por duas verificações.
**Quando você salva o agente:** O catálogo de modelos do servidor precisa listar o modelo do agente como um que aceita o modo rápido. Caso contrário, o servidor se recusa a salvar o agente.
**Em cada turno:** Se o provedor não oferecer o modo rápido para esse modelo ou implantação, o turno termina com um erro. | Remova `speed` (csharp, go: `Speed`) do agente. Consulte [Modelos que aceitam o modo rápido](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/differences#models-that-accept-fast-mode). |
Com `anthropic`, o servidor solicita por padrão o [fallback do lado do servidor](https://platform.claude.com/docs/pt-BR/build-with-claude/refusals-and-fallback#server-side-fallback) da Claude API. Quando um classificador de segurança recusa uma requisição, outro modelo Claude, possivelmente menos capaz, pode então respondê-la. A Anthropic escolhe o modelo, e nenhum evento informa a troca, mas uma leitura da sessão mostra o ID desse modelo. Para desativar o fallback, defina `inference.model_fallback: false`. Com os outros provedores, uma requisição desse tipo encerra o turno com uma recusa.
A documentação do seu provedor informa quais modelos e regiões oferecem suporte a cada recurso. Ferramentas personalizadas, ferramentas MCP e as ferramentas que o seu worker executa são as mesmas em todos os provedores.
### Modelos que aceitam o modo rápido
Por padrão, o catálogo de modelos do servidor lista quatro modelos como modelos que aceitam o modo rápido: Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8 e Claude Opus 4.6. No Claude Opus 4.6, a Claude API aceita a requisição, mas [a executa na velocidade padrão](https://platform.claude.com/docs/pt-BR/build-with-claude/fast-mode#checking-which-speed-was-used). Estes valores de `inference.provider` são exceções:
* **`foundry`:** O catálogo lista apenas o Claude Opus 5.5.
* **`gateway` com `format: vertex-raw-predict`:** O catálogo não lista nenhum modelo.
* **`vertex`:** O catálogo não lista nenhum modelo, e nenhuma configuração altera isso.
Para alterar o que o catálogo lista, consulte [Entradas de modelo](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/configuration-reference#model-entries).
## Se você já executa sandboxes auto-hospedados
O software do worker é o mesmo, então seus workers podem se conectar ao seu servidor. [Executar os seus próprios workers](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/call-the-api#point-a-worker-at-your-server) lista os três valores para o processo que faz polling e o que alterar primeiro. Um worker que é iniciado por um webhook não funciona aqui.