Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Claude Managed Agents sostituisce il tuo ciclo agente scritto a mano con un'infrastruttura gestita. Questa pagina descrive cosa cambia quando migri da un ciclo personalizzato costruito sulla Messages API o dal Claude Agent SDK.
Se hai costruito un agente chiamando messages.create in un ciclo while, eseguendo tu stesso le chiamate agli strumenti e aggiungendo i risultati alla cronologia della conversazione, la maggior parte di quel codice viene eliminata.
| Prima | Dopo |
|---|---|
| Mantieni l'array della cronologia della conversazione e lo ripassi a ogni turno. | La sessione memorizza la cronologia lato server. Invia eventi, ricevi eventi. |
Iteri sui blocchi di contenuto tool_use, esegui ogni strumento e torni al ciclo con messaggi tool_result. | Gli strumenti predefiniti vengono eseguiti automaticamente all'interno della sandbox. Gestisci solo gli strumenti personalizzati tramite eventi agent.custom_tool_use. |
| Predisponi la tua sandbox per eseguire il codice generato dall'agente. | La sandbox della sessione gestisce l'esecuzione del codice, le operazioni sui file e bash. |
| Decidi tu quando il ciclo è terminato. | La sessione emette session.status_idle quando l'agente non ha più nulla da fare. |
Prima (ciclo Messages API, semplificato):
messages = [{"role": "user", "content": task}]
while True:
response = client.messages.create(
model="claude-opus-5",
max_tokens=1024,
messages=messages,
tools=tools,
)
messages.append({"role": "assistant", "content": response.content})
if response.stop_reason == "end_turn":
break
for block in response.content:
if block.type == "tool_use":
result = execute_tool(block.name, block.input)
messages.append(
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": block.id,
"content": result,
}
],
}
)Dopo (Claude Managed Agents):
agent = client.beta.agents.create(
name="Task Runner",
model="claude-opus-5",
tools=[{"type": "agent_toolset_20260401"}],
)
session = client.beta.sessions.create(
agent={"type": "agent", "id": agent.id, "version": agent.version},
environment_id=environment.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": task}]}],
)
for event in stream:
if event.type == "session.status_idle":
breakagent.custom_tool_use. Consulta Flusso di eventi della sessione.allowed_domains, blocked_domains, max_content_tokens e user_location, ora impostati una sola volta nelle voci web_search e web_fetch dell'array configs del toolset dell'agente invece che su ogni richiesta. I campi max_uses, citations e cache_control non sono disponibili. Consulta Limitare i domini di ricerca web e recupero web.Se hai sviluppato con il Claude Agent SDK, stai già lavorando con agenti, strumenti e sessioni come concetti. La differenza è dove vengono eseguiti: l'SDK viene eseguito in un processo che gestisci tu, mentre Managed Agents viene eseguito nell'infrastruttura di Anthropic. La maggior parte della migrazione consiste nel mappare gli oggetti di configurazione dell'SDK ai loro equivalenti lato API.
| Agent SDK | Managed Agents |
|---|---|
ClaudeAgentOptions(...) costruito a ogni esecuzione | client.beta.agents.create(...) una sola volta; l'Agent viene persistito e versionato lato server. Consulta Configurazione dell'agente. |
async with ClaudeSDKClient(...) o query(...) | client.beta.sessions.create(...) e poi invia e ricevi eventi. |
Funzioni decorate con @tool inviate automaticamente dall'SDK | Dichiarale come {"type": "custom", ...} sull'Agent; il tuo client gestisce gli eventi agent.custom_tool_use e risponde con user.custom_tool_result. Consulta Strumenti. |
| Gli strumenti integrati vengono eseguiti nel tuo processo sul tuo filesystem | {"type": "agent_toolset_20260401"} esegue gli stessi strumenti all'interno della sandbox della sessione su /workspace. |
cwd, add_dirs puntano a percorsi locali | Carica o monta file come risorse della sessione. |
system_prompt e la gerarchia CLAUDE.md | Una singola stringa system sull'Agent. Ogni aggiornamento che modifica l'agente produce una nuova versione lato server; fissa le sessioni a una versione specifica per promuovere o eseguire il rollback senza un deploy. Consulta Configurazione dell'agente. |
mcp_servers configurati e autenticati in un unico posto | Dichiara i server sull'Agent; fornisci le credenziali tramite un Vault sulla Session. |
permission_mode, can_use_tool | permission_policy per singolo strumento; invia eventi user.tool_confirmation per gli strumenti always_ask. |
Prima (Agent SDK):
from claude_agent_sdk import (
ClaudeAgentOptions,
ClaudeSDKClient,
create_sdk_mcp_server,
tool,
)
@tool("get_weather", "Get the current weather for a city.", {"city": str})
async def get_weather(args: dict) -> dict:
return {"content": [{"type": "text", "text": f"{args['city']}: 18°C, clear"}]}
options = ClaudeAgentOptions(
model="claude-opus-5",
system_prompt="You are a concise weather assistant.",
mcp_servers={
"weather": create_sdk_mcp_server("weather", "1.0", tools=[get_weather])
},
)
async with ClaudeSDKClient(options=options) as agent:
await agent.query("What's the weather in Tokyo?")
async for msg in agent.receive_response():
print(msg)Dopo (Managed Agents):
from anthropic import Anthropic
client = Anthropic()
agent = client.beta.agents.create(
name="weather-agent",
model="claude-opus-5",
system="You are a concise weather assistant.",
tools=[
{
"type": "custom",
"name": "get_weather",
"description": "Get the current weather for a city.",
"input_schema": {
"type": "object",
"properties": {"city": {"type": "string"}},
"required": ["city"],
},
}
],
)
environment = client.beta.environments.create(
name="weather-env",
config={"type": "cloud", "networking": {"type": "unrestricted"}},
)
session = client.beta.sessions.create(
agent={"type": "agent", "id": agent.id, "version": agent.version},
environment_id=environment.id,
)
def get_weather(city: str) -> str:
return f"{city}: 18°C, clear"
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": "What's the weather in Tokyo?"}],
}
],
)
for event in stream:
if event.type == "agent.message":
print(
"".join(block.text for block in event.content if block.type == "text")
)
elif event.type == "agent.custom_tool_use":
result = get_weather(**event.input)
client.beta.sessions.events.send(
session.id,
events=[
{
"type": "user.custom_tool_result",
"custom_tool_use_id": event.id,
"content": [{"type": "text", "text": result}],
}
],
)
elif (
event.type == "session.status_idle"
and event.stop_reason
and event.stop_reason.type == "end_turn"
):
breakL'Agent e l'Environment vengono creati una sola volta e riutilizzati tra le sessioni. La funzione dello strumento viene ancora eseguita nel tuo processo; la differenza è che leggi l'evento agent.custom_tool_use e invii il risultato esplicitamente invece di lasciare che l'SDK lo invii per te.
Il compromesso per far eseguire ad Anthropic il ciclo agente è che alcune cose che l'SDK gestiva automaticamente diventano responsabilità del tuo client.
| Funzionalità SDK | Approccio Managed Agents |
|---|---|
| Plan mode | Esegui prima una sessione di sola pianificazione, poi una seconda sessione per eseguire il piano. |
| Stili di output, slash command | Applicali nel tuo client prima di inviare user.message o dopo aver ricevuto agent.message. |
Hook PreToolUse / PostToolUse | Il tuo client vede già ogni evento agent.custom_tool_use prima di rispondere; inserisci lì la logica. Per gli strumenti integrati, usa permission_policy: always_ask. |
max_turns | Conta i turni lato client. |
sessions.create e sessions.events.stream.resources.agent.custom_tool_use.Quando viene rilasciato un nuovo modello Claude, migrare un'integrazione Claude Managed Agents è tipicamente una modifica di un solo campo: aggiorna model nella tua definizione dell'agente e la modifica avrà effetto sulla prossima sessione che crei.
ant beta:agents update --agent-id "$AGENT_ID" < agent.yamlname: Task Runner
model: claude-opus-5
system: You are a task automation agent. Complete the task you are given end to end.
tools:
- type: agent_toolset_20260401La maggior parte delle modifiche di comportamento a livello di modello documentate nella guida alla migrazione della Messages API non richiede azioni da parte tua:
max_tokens, configurazione di thinking) sono gestite dal runtime di Claude Managed Agents. Questi campi non sono esposti nella definizione dell'agente.agent.custom_tool_use. Vedi dati strutturati, non stringhe grezze.Le descrizioni del comportamento nella guida della Messages API (cosa fa diversamente il modello) si applicano ancora. I passaggi di migrazione (come modificare il codice della richiesta) no.
Was this page helpful?