--- title: Riferimento url: https://platform.claude.com/docs/it/managed-agents/reference description: Tipi di evento, flag CLI del worker self-hosted, tipi di server MCP supportati, limiti di velocità e linee guida sul branding per Claude Managed Agents. featureMetadata: topic: title: Managed Agents url: https://platform.claude.com/docs/en/managed-agents/overview status: beta betaHeader: managed-agents-2026-04-01 --- Questa pagina raccoglie materiale di riferimento per Claude Managed Agents. Per le guide orientate alle attività, segui i link in ciascuna sezione. Per le operazioni sulla risorsa sessione, consulta [Operazioni sulle sessioni](https://platform.claude.com/docs/it/managed-agents/session-operations). ## Tipi di evento Le stringhe dei tipi di evento persistiti seguono una convenzione di denominazione `{domain}.{action}`; i delta di evento solo-stream (vedi la scheda Delta di evento) sono l'eccezione. Consulta [Stream di eventi della sessione](https://platform.claude.com/docs/it/managed-agents/events-and-streaming) per l'invio, lo streaming e l'elenco degli eventi. I tipi di evento webhook sono elencati separatamente in [Iscriversi ai webhook](https://platform.claude.com/docs/it/managed-agents/webhooks#supported-event-types), e alcuni dei loro nomi differiscono da quelli dello stream (ad esempio, `session.status_idled` anziché `session.status_idle`). | Tipo | Descrizione | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `user.message` | Un messaggio utente con contenuto di testo, immagine o documento. | | `user.interrupt` | Interrompe l'agente durante l'esecuzione. Non termina alcuna [esecuzione di workflow](https://platform.claude.com/docs/it/managed-agents/workflow-runs#interrupt-a-session-with-runs-open). | | `user.custom_tool_result` | Risposta a una chiamata di strumento personalizzato da parte dell'agente. | | `user.tool_confirmation` | Approva o nega una chiamata di strumento dell'agente o MCP quando una policy di autorizzazione richiede conferma. | | `user.define_outcome` | Definisce un [outcome](https://platform.claude.com/docs/it/managed-agents/define-outcomes) (risultato) verso cui l'agente deve lavorare. | | `user.tool_result` | Solo per le sessioni con [ambienti](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes) `self_hosted`, la tua integrazione è responsabile di fornire i risultati di `agent_toolset`. Gli helper SDK e la CLI lo fanno automaticamente. | | Tipo | Descrizione | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `agent.message` | Blocchi di contenuto della risposta dell'agente. | | `agent.thinking` | Segnala che l'agente sta facendo progressi tramite l'"extended thinking" (ragionamento esteso). È solo un segnale di avanzamento e non contiene il contenuto del ragionamento. | | `agent.tool_use` | L'agente invoca uno strumento predefinito dell'agente (bash, operazioni sui file e così via). Contiene `evaluated_permission` (java, php: `evaluatedPermission`; csharp, go: `EvaluatedPermission`) e, di solito, `evaluation` (csharp, go: `Evaluation`) (vedi [come è stata valutata ciascuna chiamata](https://platform.claude.com/docs/it/managed-agents/permission-policies#see-how-each-call-was-evaluated)). | | `agent.tool_result` | Risultato dell'esecuzione di uno strumento predefinito dell'agente. | | `agent.mcp_tool_use` | L'agente invoca uno strumento di un server MCP. Contiene `evaluated_permission` (java, php: `evaluatedPermission`; csharp, go: `EvaluatedPermission`) e, di solito, `evaluation` (csharp, go: `Evaluation`) (vedi [come è stata valutata ciascuna chiamata](https://platform.claude.com/docs/it/managed-agents/permission-policies#see-how-each-call-was-evaluated)). | | `agent.mcp_tool_result` | Risultato dell'esecuzione di uno strumento MCP. | | `agent.custom_tool_use` | L'agente invoca uno dei tuoi strumenti personalizzati. Rispondi con un evento `user.custom_tool_result`. | | `agent.thread_context_compacted` | La cronologia della conversazione è stata compattata per rientrare nella "context window" (finestra di contesto). | | `agent.thread_message_received` | In una sessione [multiagente](https://platform.claude.com/docs/it/managed-agents/multiagent-orchestration), un messaggio proveniente da un altro thread è arrivato sul thread il cui stream contiene questo evento; sul thread principale, un agente ha inviato un report o una domanda all'agente eseguito dalla sessione. | | `agent.thread_message_sent` | In una sessione [multiagente](https://platform.claude.com/docs/it/managed-agents/multiagent-orchestration), il thread il cui stream contiene questo evento ha inviato un messaggio a un altro thread; sul thread principale, l'agente eseguito dalla sessione ha inviato un'attività o un messaggio di follow-up a un altro agente. | Il contenuto dei messaggi in questi eventi può includere un blocco di contenuto `redacted`, `{"type": "redacted"}`: un segnaposto per contenuto trattenuto in base alla policy dei modelli di Anthropic. Il blocco non contiene altri campi. I blocchi redacted compaiono solo nel contenuto emesso dalla piattaforma; un evento utente che ne include uno viene rifiutato con un errore 400. | Tipo | Descrizione | | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `session.status_running` | L'agente sta elaborando attivamente. | | `session.status_idle` | L'agente ha terminato l'attività corrente ed è in attesa di input. Include uno `stop_reason` (java, php: `stopReason`; csharp, go: `StopReason`) che indica perché l'agente si è fermato. | | `session.status_rescheduled` | Si è verificato un errore transitorio e la sessione sta riprovando automaticamente. | | `session.status_terminated` | La sessione è terminata, a causa di un errore irreversibile oppure perché è stata archiviata. | | `session.deleted` | La sessione è stata eliminata. Termina qualsiasi stream di eventi attivo; non vengono emessi ulteriori eventi per questa sessione. | | `session.updated` | Una richiesta di aggiornamento della sessione ha modificato almeno un campo. Include solo i campi modificati. Gli aggiornamenti si applicano al turno successivo. | | `session.error` | Si è verificato un errore durante l'elaborazione. Include un oggetto tipizzato `error` (csharp, go: `Error`) con un `retry_status` (java, php: `retryStatus`; csharp, go: `RetryStatus`). | | `session.usage` | Istantanea dell'utilizzo cumulativo della sessione e del costo di listino tracciato. Contiene i totali di utilizzo della sessione e, se la sessione ne ha uno, il suo [budget](https://platform.claude.com/docs/it/managed-agents/budgets). | | `session.thread_created` | È stato creato un thread [multiagente](https://platform.claude.com/docs/it/managed-agents/multiagent-orchestration). Include `workflow_run_id` (java: `workflowRunId`; php: `workflowRunID`; csharp, go: `WorkflowRunID`): l'ID dell'esecuzione per il thread di un'[esecuzione di workflow](https://platform.claude.com/docs/it/managed-agents/workflow-runs#a-runs-threads), e `null` (python: `None`; ruby: `nil`; java: `Optional.empty()`; go: `""`) per qualsiasi altro thread. | | `session.thread_status_running` | Un thread della sessione ha iniziato l'esecuzione. Ogni sessione emette questo evento per il proprio thread principale; nelle sessioni [multiagente](https://platform.claude.com/docs/it/managed-agents/multiagent-orchestration), anche le transizioni dei thread figli vengono ripubblicate sullo stream principale. | | `session.thread_status_idle` | Un thread della sessione ha terminato il proprio turno ed è in attesa di input. Include `stop_reason` (java, php: `stopReason`; csharp, go: `StopReason`). | | `session.thread_status_rescheduled` | Un thread della sessione ha riscontrato un errore transitorio e sta riprovando automaticamente. | | `session.thread_status_terminated` | Un thread della sessione è terminato e non accetta ulteriori input, ad esempio perché è stato archiviato o ha riscontrato un errore irreversibile. Un thread advisor termina anche quando la sua consultazione si conclude. Il server archivia autonomamente i thread di un'esecuzione di workflow. | In una sessione il cui agente ha i [workflow dinamici](https://platform.claude.com/docs/it/managed-agents/multiagent-orchestration#dynamic-workflows) attivati, questi eventi `workflow_run.*` arrivano sullo stream della sessione: | Tipo | Descrizione | | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `workflow_run.created` | È stata creata un'esecuzione di workflow. Include `workflow_run_id` (java: `workflowRunId`; php: `workflowRunID`; csharp, go: `WorkflowRunID`), il `name` (csharp, go: `Name`) e la `description` (csharp, go: `Description`) dell'esecuzione, e `phases` (csharp, go: `Phases`), le fasi dichiarate per l'esecuzione. Segue un evento di stato, anche se dopo un'interruzione potrebbe non seguire. | | `workflow_run.status_running` | Un'esecuzione di workflow è in corso. Inviato quando l'esecuzione inizia, il che può avvenire un po' di tempo dopo `workflow_run.created`, e di nuovo quando riprende dopo una pausa dovuta al budget. Una ripresa dopo un'interruzione potrebbe non inviarlo. Un'esecuzione inattiva fin dall'inizio potrebbe ricevere prima `workflow_run.status_idle`. Include `workflow_run_id` (java: `workflowRunId`; php: `workflowRunID`; csharp, go: `WorkflowRunID`). | | `workflow_run.status_idle` | Un'esecuzione di workflow è diventata inattiva: è stata messa in pausa, ad esempio al raggiungimento del budget della sessione. Una pausa dopo un'interruzione potrebbe non inviarlo. Include `workflow_run_id` (java: `workflowRunId`; php: `workflowRunID`; csharp, go: `WorkflowRunID`). | | `workflow_run.status_ended` | Un'esecuzione di workflow è terminata. Include `workflow_run_id` (java: `workflowRunId`; php: `workflowRunID`; csharp, go: `WorkflowRunID`) e `result` (csharp, go: `Result`), il cui `type` (csharp, go: `Type`) indica come è terminata l'esecuzione. | | `workflow_run.error` | Un errore di un'esecuzione di workflow, o un avvio rifiutato dal server. Un'esecuzione che termina con un errore lo riceve, con lo stesso errore, prima del suo `workflow_run.status_ended`. Include `error` (csharp, go: `Error`) e `workflow_run_id` (java: `workflowRunId`; php: `workflowRunID`; csharp, go: `WorkflowRunID`), che è `null` (python: `None`; ruby: `nil`; java: `Optional.empty()`; go: `""`) quando non è stata creata alcuna esecuzione. | | `workflow_run.phase_started` | Un'esecuzione di workflow è entrata in una delle sue fasi. Include `workflow_run_id` (java: `workflowRunId`; php: `workflowRunID`; csharp, go: `WorkflowRunID`) e `workflow_run_phase_id` (java: `workflowRunPhaseId`; php: `workflowRunPhaseID`; csharp, go: `WorkflowRunPhaseID`). | | `workflow_run.phase_ended` | Un'esecuzione di workflow ha lasciato una fase. Include `workflow_run_id` (java: `workflowRunId`; php: `workflowRunID`; csharp, go: `WorkflowRunID`), `workflow_run_phase_id` (java: `workflowRunPhaseId`; php: `workflowRunPhaseID`; csharp, go: `WorkflowRunPhaseID`) e `phase_started_id` (java: `phaseStartedId`; php: `phaseStartedID`; csharp, go: `PhaseStartedID`). | Gli eventi span sono marcatori di osservabilità che racchiudono l'attività per il tracciamento dei tempi e dell'utilizzo. | Tipo | Descrizione | | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `span.model_request_start` | È iniziata una chiamata di inferenza del modello. | | `span.model_request_end` | Una chiamata di inferenza del modello è stata completata. Include `model_usage` (java, php: `modelUsage`; csharp, go: `ModelUsage`) con i conteggi dei token. | | `span.outcome_evaluation_start` | È iniziata la valutazione dell'[outcome](https://platform.claude.com/docs/it/managed-agents/define-outcomes). | | `span.outcome_evaluation_ongoing` | Heartbeat durante una valutazione dell'[outcome](https://platform.claude.com/docs/it/managed-agents/define-outcomes) in corso. | | `span.outcome_evaluation_end` | Un ciclo di valutazione dell'[outcome](https://platform.claude.com/docs/it/managed-agents/define-outcomes) è stato completato. Un risultato `needs_revision` significa che segue un altro ciclo; `satisfied`, `max_iterations_reached`, `failed` e `interrupted` sono terminali. | | Tipo | Descrizione | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `system.message` | Aggiunge un contesto privilegiato a livello di sistema che si applica al turno associato e a tutti i turni successivi. Per i modelli che lo accettano, consulta [Modelli supportati](https://platform.claude.com/docs/it/managed-agents/events-and-streaming#supported-models). Su un modello principale non supportato l'evento viene rifiutato con `model_does_not_support_mid_conversation_system`. | I delta degli eventi sono eventi di anteprima disponibili solo nello stream. Vengono emessi sulle connessioni di stream (a livello di sessione o per thread) che li attivano con il parametro `event_deltas` (curl: `event_deltas[]`; cli: `--event-delta`; java, php: `eventDeltas`; csharp, go: `EventDeltas`), e non vengono mai persistiti nella cronologia degli eventi della sessione. Consulta [Visualizzare in anteprima le risposte con i delta degli eventi](https://platform.claude.com/docs/it/managed-agents/event-deltas) per attivarli, accumularli e riconciliarli. | Tipo | Descrizione | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `event_start` | Un evento in anteprima ha iniziato a essere generato. Contiene il `type` (csharp, go: `Type`) e l'`id` (csharp, go: `ID`) dell'evento in arrivo. Solo-stream e mai persistito. | | `event_delta` | Contenuto incrementale per un evento in anteprima, identificato da `event_id` (java: `eventId`; php: `eventID`; csharp, go: `EventID`). Solo-stream e mai persistito. | ## Worker self-hosted Consulta [Riferimento per i worker self-hosted](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-reference) per i flag CLI di `ant beta:worker`, le variabili d'ambiente, i percorsi del filesystem e le opzioni degli helper dell'SDK dei worker predefiniti che gestiscono un ambiente `self_hosted`. ## Tipi di server MCP supportati Claude Managed Agents si connette a [server MCP remoti](https://platform.claude.com/docs/it/agents-and-tools/remote-mcp-servers) che espongono un endpoint HTTP, oppure a server MCP privati tramite [tunnel MCP](https://platform.claude.com/docs/it/agents-and-tools/mcp-tunnels/overview). Il server dovrebbe supportare il trasporto streamable HTTP del protocollo MCP; i server che supportano solo il trasporto SSE deprecato funzionano comunque tramite un fallback automatico. Consulta [Connettore MCP](https://platform.claude.com/docs/it/managed-agents/mcp-connector) per dichiarare i server su un agente. Per maggiori informazioni su MCP e sulla creazione di server MCP, consulta la [documentazione MCP](https://modelcontextprotocol.io). ## Limiti di velocità Gli endpoint di Managed Agents sono soggetti a "rate limit" (limiti di velocità) per organizzazione: | Operazione | Limite | | -------------------------------------------------------- | ------------------------- | | Endpoint di creazione (come agenti, sessioni e ambienti) | 300 richieste al minuto | | Endpoint di lettura (come recupero, elenco e stream) | 1.200 richieste al minuto | Si applicano anche i [limiti di spesa e i limiti di velocità per livello di utilizzo](https://platform.claude.com/docs/it/api/rate-limits) a livello di organizzazione. ## Linee guida sul branding Per i partner che integrano Claude Managed Agents, l'uso del branding Claude è facoltativo. Quando fai riferimento a Claude nel tuo prodotto: **Consentito:** * "Claude Agent" (preferito per i menu a tendina) * "Claude" (quando all'interno di un menu già etichettato "Agents") * "\{YourAgentName} Powered by Claude" (se hai già un nome per il tuo agente) **Non consentito:** * "Claude Code" o "Claude Code Agent" * "Claude Cowork" o "Claude Cowork Agent" * ASCII art con il marchio Claude Code o elementi visivi che imitano Claude Code Il tuo prodotto deve mantenere il proprio branding e non apparire come Claude Code, Claude Cowork o qualsiasi altro prodotto Anthropic. Per domande sulla conformità del branding, contatta il [team commerciale](https://www.anthropic.com/contact-sales) di Anthropic.