Inizia con Claude Managed Agents

Questa guida ti accompagna nella creazione di un agente, nella configurazione di un ambiente, nell'avvio di una sessione e nello streaming delle risposte dell'agente.

Concetti fondamentali

Concept	Description
Agent	The model, system prompt, tools, MCP servers, and skills
Environment	A configured container template (packages, network access)
Session	A running agent instance within an environment, performing a specific task and generating outputs
Events	Messages exchanged between your application and the agent (user turns, tool results, status updates)

Prerequisiti

Un account Console Anthropic
Una chiave API

Installa la CLI

Verifica l'installazione:

ant --version

Installa l'SDK

Imposta la tua chiave API come variabile d'ambiente:

export ANTHROPIC_API_KEY="your-api-key-here"

Crea la tua prima sessione

Tutte le richieste API di Managed Agents richiedono l'header beta managed-agents-2026-04-01. L'SDK imposta l'header beta automaticamente.

Cosa sta succedendo

Quando invii un evento utente, Claude Managed Agents:

Provisiona un container: La configurazione del tuo ambiente determina come viene costruito.
Esegue il ciclo dell'agente: Claude decide quali strumenti utilizzare in base al tuo messaggio
Esegue gli strumenti: Scritture di file, comandi bash e altre chiamate agli strumenti vengono eseguiti all'interno del container
Trasmette eventi in streaming: Ricevi aggiornamenti in tempo reale mentre l'agente lavora
Va in stato idle: L'agente emette un evento session.status_idle quando non ha più nulla da fare

Prossimi passi

Definisci il tuo agente

Crea configurazioni di agente riutilizzabili e con versioning

Crea un agente

Crea un agente che definisce il modello, il prompt di sistema e gli strumenti disponibili.

set -euo pipefail

agent=$(
  curl -sS --fail-with-body https://api.anthropic.com/v1/agents \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d @- <<'EOF'
{
  "name": "Coding Assistant",
  "model": "claude-sonnet-4-6",
  "system": "You are a helpful coding assistant. Write clean, well-documented code.",
  "tools": [
    {"type": "agent_toolset_20260401"}
  ]
}
EOF
)

AGENT_ID=$(jq -er '.id' <<<"$agent")
AGENT_VERSION=$(jq -er '.version' <<<"$agent")

echo "Agent ID: $AGENT_ID, version: $AGENT_VERSION"

Il tipo di strumento agent_toolset_20260401 abilita l'intero set di strumenti agente predefiniti (bash, operazioni sui file, ricerca web e altro). Consulta Strumenti per l'elenco completo e le opzioni di configurazione per singolo strumento.

Salva l'agent.id restituito. Lo utilizzerai come riferimento in ogni sessione che crei.

Crea un ambiente

Un ambiente definisce il container in cui viene eseguito il tuo agente.

environment=$(
  curl -sS --fail-with-body https://api.anthropic.com/v1/environments \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d @- <<'EOF'
{
  "name": "quickstart-env",
  "config": {
    "type": "cloud",
    "networking": {"type": "unrestricted"}
  }
}
EOF
)

ENVIRONMENT_ID=$(jq -er '.id' <<<"$environment")

echo "Environment ID: $ENVIRONMENT_ID"

Salva l'environment.id restituito. Lo utilizzerai come riferimento in ogni sessione che crei.

Avvia una sessione

Crea una sessione che fa riferimento al tuo agente e al tuo ambiente.

session=$(
  curl -sS --fail-with-body https://api.anthropic.com/v1/sessions \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d @- <<EOF
{
  "agent": "$AGENT_ID",
  "environment_id": "$ENVIRONMENT_ID",
  "title": "Quickstart session"
}
EOF
)

SESSION_ID=$(jq -er '.id' <<<"$session")

echo "Session ID: $SESSION_ID"

Invia un messaggio e ricevi la risposta in streaming

Apri uno stream, invia un evento utente, quindi elabora gli eventi man mano che arrivano:

# Send the user message first; the API buffers events until the stream attaches
curl -sS --fail-with-body \
  "https://api.anthropic.com/v1/sessions/$SESSION_ID/events" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d @- >/dev/null <<'EOF'
{
  "events": [
    {
      "type": "user.message",
      "content": [
        {
          "type": "text",
          "text": "Create a Python script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt"
        }
      ]
    }
  ]
}
EOF

# Open the SSE stream and process events as they arrive
while IFS= read -r line; do
  [[ $line == data:* ]] || continue
  json=${line#data: }
  case $(jq -r '.type' <<<"$json") in
    agent.message)
      jq -j '.content[] | select(.type == "text") | .text' <<<"$json"
      ;;
    agent.tool_use)
      printf '\n[Using tool: %s]\n' "$(jq -r '.name' <<<"$json")"
      ;;
    session.status_idle)
      printf '\n\nAgent finished.\n'
      break
      ;;
  esac
done < <(
  curl -sS -N --fail-with-body \
    "https://api.anthropic.com/v1/sessions/$SESSION_ID/stream" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "Accept: text/event-stream"
)

L'agente scriverà uno script Python, lo eseguirà nel container e verificherà che il file di output sia stato creato. Il tuo output sarà simile a questo:

I'll create a Python script that generates the first 20 Fibonacci numbers and saves them to a file.
[Using tool: write]
[Using tool: bash]
The script ran successfully. Let me verify the output file.
[Using tool: bash]
fibonacci.txt contains the first 20 Fibonacci numbers (0 through 4181).

Agent finished.