Differenze rispetto al servizio ospitato
Scopri quali funzionalità ha solo Claude Managed Agents self-hosted, quali funzionalità del servizio ospitato non ha, quali si comportano in modo diverso e quali richiedono prima un’impostazione del server.
Un server Claude Managed Agents self-hosted ha la stessa API del servizio Managed Agents ospitato di Anthropic, a parte le differenze descritte in questa pagina. Le tabelle indicano cosa fare per ciascuna. Consultale prima di spostare un’applicazione sul tuo server. Nulla viene copiato dal servizio ospitato, cronologia delle sessioni inclusa. Crea di nuovo sul tuo server i tuoi agenti, skill, credenziali del vault e memory store.
Funzionalità che ha solo il tuo server
| Funzionalità | Cosa fa | Come configurarla |
|---|---|---|
| Una scelta del provider di inferenza | Il server può inviare le chiamate al modello a un provider cloud o al tuo gateway di modelli anziché alla Claude API. | Provider di inferenza |
| Single sign-on | Le persone chiamano il server con un token del tuo provider di identità OpenID Connect. Il server assegna a ogni chiamante un ruolo in base ai gruppi presenti nel token. La chiave API del server continua a funzionare. | Single sign-on |
| Il tuo gestore di segreti | Il server può archiviare il segreto di ogni nuova credenziale del vault nel tuo secret manager anziché nel proprio database. | Gestore di segreti |
| Identità dell’agente | Il server può firmare un token di breve durata e inviarlo con le chiamate di un agente a un server MCP. Il server MCP o il gateway verifica il token rispetto alle chiavi pubbliche che pubblichi. | Identità dell’agente |
Funzionalità non disponibili
| Funzionalità | Cosa succede | Cosa fare invece |
|---|---|---|
| Ambienti cloud | Esistono solo ambienti self_hosted. Una richiesta per un ambiente cloud restituisce un errore 400. | Distribuisci worker self-hosted per ogni ambiente. |
| Il resto della Claude API, come la Messages API e la Models API | Il server non la fornisce. Le chiamate dell’SDK a /v1/messages e /v1/models restituiscono un errore 404. | Invia queste richieste alla Claude API o al tuo provider, da un client che non punta al tuo server. |
| Risorse di sessione File e la Files API | Il server rifiuta le risorse file, e /v1/files non esiste. Le risorse memory_store funzionano. | Metti i file nella directory di lavoro del worker. Consulta Spostare dati dentro e fuori da una sessione. Per mostrare al modello un’immagine o un PDF, invialo come base64 in un messaggio. |
Credenziali del vault mcp_oauth | Il server le rifiuta quando le crei, perché non ha un flusso OAuth per rinnovare un token. | Archivia il token come credenziale static_bearer. Aggiorna la credenziale con un nuovo token prima che quello vecchio scada. |
Skill predefinite docx, pdf, pptx e xlsx | Il server rifiuta un agente che le dichiara. Esistono solo le skill che carichi tu. | Scarica i loro sorgenti dal repository delle skill e caricale come skill personalizzate. |
| Deployment pianificati e dreams | Il server non ha route per queste funzionalità. | Avvia le sessioni dal tuo scheduler, ad esempio un cron job. I dreams non hanno un sostituto. |
| Webhook | Il server non invia webhook, quindi un worker che si avvia su un webhook non si avvia mai. | Segui una sessione tramite il suo flusso di eventi, oppure elenca i suoi eventi. Mantieni i tuoi worker in esecuzione in modo che possano eseguire il polling. |
Funzionalità che si comportano diversamente
| Funzionalità | Cosa cambia | Cosa fare |
|---|---|---|
| Claude Console | La Claude Console su platform.claude.com non mostra ciò che si trova sul tuo server. | Usa la console sul tuo server. |
| Chiamate agli strumenti | I turni del modello di una sessione vengono eseguiti anche quando nessun worker sta interrogando il suo ambiente. La prima chiamata a uno strumento quindi attende, senza errori, finché un worker non la esegue. | Se una sessione si ferma su una chiamata a uno strumento, verifica che un worker stia interrogando il suo ambiente. |
| Archivi di memoria | L’API è completa. È il worker, non il server, a copiare ogni store collegato nella sandbox e a riscrivere le modifiche. Consulta Memory store nelle sandbox self-hosted. | Esegui i tuoi worker sulla versione più recente di ant, con una directory /mnt/memory scrivibile. |
| Caricamenti di skill personalizzate | Il server non decomprime un archivio zip. Il caricamento di un archivio restituisce un errore 400 che dice SKILL.md not found in uploaded files. | ant apply e l’helper files_from_dir dell’SDK Python funzionano così come sono. Con qualsiasi altro strumento, carica i file della skill come parti separate, e fai iniziare il nome del file di ciascuna parte con la cartella della skill, come in my-skill/SKILL.md. |
| Orchestrazione multiagente | Un agente può delegare solo ai subagenti che elenchi. I flussi di lavoro dinamici, l’advisor e i subagenti che l’agente definisce da sé non sono disponibili. Il server accetta un blocco multiagent solo se il suo type è coordinator. Gli esempi in Orchestrazione multiagente impostano type su multiagent_20261001, che restituisce un errore 400. Anche un blocco con un’impostazione advisor restituisce un errore 400. | Imposta multiagent su {"type": "coordinator", "agents": [...]}. Elenca da 1 a 20 agenti in agents. Ogni voce assume una delle forme di un agente predefinito. |
| Risorse di sessione repository GitHub | Il server rifiuta le risorse github_repository finché non elenchi i loro host Git nelle sue impostazioni. Il server non rileva le skill nella directory .claude/skills di un repository, quindi collega le skill all’agente. | Consulta I repository Git richiedono una voce nell’allowlist. |
| Server MCP | Il server si connette solo agli host MCP che elenchi nelle sue impostazioni. | Consulta I server MCP richiedono una voce nell’allowlist. |
| Strumenti web | Gli strumenti web_search e web_fetch sono disattivati finché non li attivi nelle impostazioni del server. | Consulta Gli strumenti web richiedono un’impostazione del server. |
Credenziali del vault environment_variable | Il server le rifiuta finché non attivi l’egress gateway, un proxy tra le tue sandbox e internet. | Consulta Credenziali di variabili d’ambiente. Senza il gateway, fornisci alla tua sandbox le credenziali CLI e API di cui ha bisogno tramite i tuoi strumenti. |
| Risultati degli strumenti personalizzati | Il server invia al modello l’intero testo del risultato di uno strumento personalizzato. Se un risultato è troppo grande per la “context window” (finestra di contesto) del modello, il server risponde comunque con 200, e la sessione termina poi con un session.error. | Accorcia i risultati lunghi nel tuo client prima di inviarli. |
| Risultati degli strumenti MCP | Il server tronca un risultato più grande della sua impostazione mcp.max_result_bytes, che è 100 KiB per impostazione predefinita. Comunica al modello che il risultato è stato troncato, e il resto va perso. Anche il servizio ospitato tronca i risultati lunghi, ma può salvare il risultato completo in un file per una sessione in una sandbox cloud. | Per modificare il limite, imposta mcp.max_result_bytes nel file delle impostazioni. |
| Immagini e documenti inviati tramite URL | Il server accetta un blocco image o document con un’origine url, ma il modello non lo vede mai, e non viene restituito alcun errore. Lo stesso accade a un blocco image con un’origine file. | Invia i dati come base64, oppure come text per un documento. |
Lo stato di sessione rescheduling | Il server ritenta una chiamata al modello che fallisce per un motivo temporaneo e riporta ogni tentativo nel flusso di eventi, come fa il servizio ospitato. Lo stato della sessione rimane running tra un tentativo e l’altro, quindi un filtro statuses[]=rescheduling non corrisponde ad alcuna sessione. | Leggi i nuovi tentativi dal flusso di eventi. |
| Metadati di sessione, con un gateway di modelli | Se l’impostazione inference.credentials.assertion.forward_metadata del server elenca delle chiavi dei metadati di sessione, un aggiornamento che aggiunge, rimuove o modifica una di esse restituisce un errore 400. | Imposta quelle chiavi quando crei la sessione. Per l’impostazione, consulta Token del gateway a breve durata. |
Funzionalità che richiedono un’impostazione del server
Ognuna di queste funzionalità è disattivata, o rifiuta ogni host, finché non modifichi il file delle impostazioni del server.
I server MCP richiedono una voce nell’allowlist
Il server si connette solo ai server MCP i cui host sono elencati in mcp.allowed_hostnames nel suo file delle impostazioni:
mcp:
allowed_hostnames:
- mcp.example.comGli host devono corrispondere esattamente, senza caratteri jolly e senza sottodomini, e l’elenco è vuoto per impostazione predefinita. Finché l’host di un server MCP non è nell’elenco, il tuo server rifiuta di salvare un agente che lo indica.
Un server MCP all’interno della tua rete privata non ha bisogno di un tunnel MCP. Inserisci il suo URL nella definizione dell’agente, come descritto in Connettore MCP, e aggiungi il suo host all’allowlist. All’URL si applicano due regole:
- Deve usare
https, a meno che il server MCP non si trovi sull’indirizzo di loopback. - Se il suo host è un nome che si risolve solo in indirizzi privati o riservati, il tuo server rifiuta per impostazione predefinita di connettersi. Scegli la soluzione adatta al tuo caso:
| Il tuo caso | Soluzione |
|---|---|
L’indirizzo è in 10.0.0.0/8, 172.16.0.0/12 o 192.168.0.0/16, e controlli i record DNS del nome | Mantieni il nome, ed elencalo anche in mcp.private_hostnames nel file delle impostazioni. |
| Qualsiasi altro caso | Usa l’indirizzo IP al posto del nome, nell’URL e nell’allowlist. Il certificato del server MCP deve indicare quell’indirizzo. |
I repository Git richiedono una voce nell’allowlist
Nel servizio ospitato, le sessioni che usano sandbox self-hosted non possono avere risorse github_repository. Sul tuo server, le sessioni possono averle. Il server rifiuta queste risorse finché non elenchi i loro host Git nel suo file delle impostazioni. Gli agenti possono eseguire il push solo sui branch che elenchi:
git:
allowed_hostnames:
- github.com
allowed_push_refs:
- refs/heads/agent/Tieni presenti questi punti:
- URL: l’host non deve necessariamente essere
github.com, ma l’URL deve usare HTTPS. - Token: il token che il tuo client invia non raggiunge mai la sandbox, perché il traffico Git passa attraverso il tuo server, che aggiunge il token.
- Branch: agli agenti non viene comunicato l’elenco dei branch, quindi indica un branch nel tuo prompt.
- Force push: il server non rifiuta i force push, quindi un agente può sovrascrivere qualsiasi branch che elenchi. Per rifiutare i force push, proteggi il branch sul tuo host Git.
Accedere a GitHub mostra la richiesta e come ruotare un token. Se un clone fallisce, la sessione riceve un evento session.error che ne indica la causa. Per verificare un push, cerca il branch sul tuo host Git. Il log del server riporta ok anche per un push che il tuo host ha rifiutato.
Gli strumenti web richiedono un’impostazione del server
Gli strumenti web_search e web_fetch sono disattivati per impostazione predefinita. Per attivarli, aggiungi questo al file delle impostazioni del server:
web_tools:
enabled: trueCon questa sola impostazione, si applicano gli elenchi di domini e il limite di contenuto di ciascun agente, come nel servizio ospitato.
Per limitare gli strumenti per ogni agente, imposta web_tools.allowed_domains, web_tools.blocked_domains o web_tools.max_content_tokens. Ognuna di queste impostazioni attiva anche gli strumenti. Il server rifiuta di salvare un agente che richiede più di quanto consentono queste impostazioni. Ad esempio, rifiuta un agente che consente un dominio al di fuori di web_tools.allowed_domains, o che imposta un limite di contenuto più grande. Se un agente del genere esiste già, non può avviare una sessione finché non lo aggiorni.
Mentre gli strumenti sono disattivati, ciò che accade a un agente dipende dalle voci web_search e web_fetch nel suo toolset:
| Il toolset ha | Cosa succede |
|---|---|
| Nessuna voce per nessuno dei due strumenti | L’agente viene eseguito senza gli strumenti, e nessun errore lo segnala. |
Una voce che si limita a disattivare il proprio strumento, come {"name": "web_fetch", "enabled": false} | Lo stesso. |
| Una voce che lascia attivo il proprio strumento, o che ne imposta gli elenchi di domini, il limite di contenuto o la posizione | Il server rifiuta di salvare l’agente, o di avviare una sessione per esso. |
Quali strumenti web esistono dipende anche dal tuo provider di inferenza.
Differenze che dipendono dal tuo provider di inferenza
Alcune funzionalità funzionano solo con alcuni valori dell’impostazione inference.provider del server. La tabella mostra cosa succede con gli altri valori. Alcuni di questi casi non restituiscono alcun errore.
Le righe web_search e web_fetch si applicano dopo che hai attivato gli strumenti web. Fino ad allora, nessuno dei due strumenti funziona con alcun provider.
| Funzionalità | Funziona quando inference.provider è | Con gli altri valori | Cosa fare |
|---|---|---|---|
Strumento web_search | anthropic, vertex, foundry | Il server non offre mai lo strumento al modello. Gli agenti vengono comunque salvati ed eseguiti, ed elencano ancora lo strumento, ma il modello non può chiamarlo. | Fornisci all’agente uno strumento personalizzato o un server MCP che esegua ricerche. |
Strumento web_fetch | anthropic, foundry | Come per web_search. | Fornisci all’agente uno strumento personalizzato o un server MCP che recuperi le pagine. |
inference_geo | anthropic | Il server rifiuta di salvare un agente che lo imposta. | Rimuovi inference_geo dall’agente. |
Modalità veloce (speed: "fast") | Dipende dal provider e dal modello dell’agente | Un agente che la imposta deve superare due controlli. Quando salvi l’agente: il catalogo dei modelli del server deve elencare il modello dell’agente come uno che accetta la modalità veloce. Altrimenti, il server rifiuta di salvare l’agente. A ogni turno: se il provider non offre la modalità veloce per quel modello o deployment, il turno termina con un errore. | Rimuovi speed dall’agente. Consulta Modelli che accettano la modalità veloce. |
Con anthropic, il server richiede per impostazione predefinita il fallback lato server della Claude API. Quando un classificatore di sicurezza rifiuta una richiesta, un altro modello Claude, eventualmente meno capace, può quindi rispondere. Anthropic sceglie il modello, e nessun evento segnala il cambiamento, ma una lettura della sessione mostra l’ID di quel modello. Per disattivare il fallback, imposta inference.model_fallback: false. Con gli altri provider, una richiesta del genere termina il turno con un rifiuto.
La documentazione del tuo provider indica quali modelli e regioni supportano ciascuna funzionalità. Gli strumenti personalizzati, gli strumenti MCP e gli strumenti eseguiti dal tuo worker sono gli stessi con ogni provider.
Modelli che accettano la modalità veloce
Per impostazione predefinita, il catalogo dei modelli del server elenca quattro modelli come modelli che accettano la modalità veloce: Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8 e Claude Opus 4.6. Su Claude Opus 4.6, la Claude API accetta la richiesta ma la esegue a velocità standard. Questi valori di inference.provider sono eccezioni:
foundry: il catalogo elenca solo Claude Opus 5.5.gatewayconformat: vertex-raw-predict: il catalogo non elenca alcun modello.vertex: il catalogo non elenca alcun modello, e nessuna impostazione lo cambia.
Per modificare ciò che il catalogo elenca, consulta Voci dei modelli.
Se esegui già sandbox self-hosted
Il software del worker è lo stesso, quindi i tuoi worker possono connettersi al tuo server. Eseguire i tuoi worker elenca i tre valori per il processo che esegue il polling e cosa cambiare per primo. Un worker che si avvia su un webhook qui non funziona.
Questa pagina ti è stata utile?