Riferimento
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.
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.
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 per l'invio, lo streaming e l'elenco degli eventi. I tipi di evento webhook sono elencati separatamente in Iscriversi ai webhook, 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. |
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 (risultato) verso cui l'agente deve lavorare. |
user.tool_result | Solo per le sessioni con ambienti 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 e, di solito, evaluation (vedi come è stata valutata ciascuna chiamata). |
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 e, di solito, evaluation (vedi come è stata valutata ciascuna chiamata). |
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, 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, 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 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 con un retry_status. |
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. |
session.thread_created | È stato creato un thread multiagente. Include workflow_run_id: l'ID dell'esecuzione per il thread di un'esecuzione di workflow, e None 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, 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. |
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 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, il name e la description dell'esecuzione, e 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. |
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. |
workflow_run.status_ended | Un'esecuzione di workflow è terminata. Include workflow_run_id e result, il cui 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 e workflow_run_id, che è None quando non è stata creata alcuna esecuzione. |
workflow_run.phase_started | Un'esecuzione di workflow è entrata in una delle sue fasi. Include workflow_run_id e workflow_run_phase_id. |
workflow_run.phase_ended | Un'esecuzione di workflow ha lasciato una fase. Include workflow_run_id, workflow_run_phase_id e phase_started_id. |
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 con i conteggi dei token. |
span.outcome_evaluation_start | È iniziata la valutazione dell'outcome. |
span.outcome_evaluation_ongoing | Heartbeat durante una valutazione dell'outcome in corso. |
span.outcome_evaluation_end | Un ciclo di valutazione dell'outcome è 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. 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, e non vengono mai persistiti nella cronologia degli eventi della sessione. Consulta Visualizzare in anteprima le risposte con i delta degli eventi per attivarli, accumularli e riconciliarli.
| Tipo | Descrizione |
|---|---|
event_start | Un evento in anteprima ha iniziato a essere generato. Contiene il type e l'id dell'evento in arrivo. Solo-stream e mai persistito. |
event_delta | Contenuto incrementale per un evento in anteprima, identificato da event_id. Solo-stream e mai persistito. |
Worker self-hosted
Consulta Riferimento per i worker self-hosted 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 che espongono un endpoint HTTP, oppure a server MCP privati tramite tunnel MCP. 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 per dichiarare i server su un agente.
Per maggiori informazioni su MCP e sulla creazione di server MCP, consulta la documentazione MCP.
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 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 di Anthropic.
Was this page helpful?