Claude Platform Docs
Managed AgentsPrimi passi

Inizia con Claude Managed Agents

Crea il tuo primo agente autonomo.

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.

Claude Code

Lascia che Claude Code configuri il tuo agente per te

/claude-api managed-agents-onboard

Concetti fondamentali

ConcettoDescrizione
AgenteIl modello, il prompt di sistema, gli strumenti, i server MCP e le skill
AmbienteConfigurazione del luogo in cui vengono eseguite le sessioni: una sandbox cloud gestita da Anthropic oppure una sandbox self-hosted sulla tua infrastruttura
SessioneUn’istanza di agente in esecuzione all’interno di un ambiente, che svolge un compito specifico e genera output
EventiMessaggi scambiati tra la tua applicazione e l’agente (turni dell’utente, risultati degli strumenti, aggiornamenti di stato)

Prima di iniziare

  1. Crea un account Claude Console

    Registrati per un account Claude Console, oppure accedi a quello che hai già.

  2. Scegli come autenticarti

    L’accesso tramite la CLI è consigliato per lo sviluppo locale.

    CLIChiave API
  1. Installa la CLI

    brew install anthropics/tap/ant
  2. Accedi

    ant auth login

    Una volta completato l’accesso, gli SDK e la CLI rileveranno automaticamente le tue credenziali.

Installa l’SDK

pip install anthropic

Crea la tua prima sessione

  1. Crea un agente

    Crea un agente che definisca il modello, il “system prompt” (prompt di sistema) e gli strumenti disponibili.

    ant apply coding-assistant.md
    coding-assistant.md
    ---
    name: Coding Assistant
    model: claude-opus-5-5
    tools:
      - type: agent_toolset_20260401
        configs:
          - name: web_search
            enabled: false
          - name: web_fetch
            enabled: false
    ---
    
    You are a helpful coding assistant. Write clean, well-documented code.

    ant apply stampa l’ID dell’agente e lo registra in claude-lock.json. Lo utilizzerai in ogni sessione che crei.

    Il tipo di strumento agent_toolset_20260401 abilita gli strumenti predefiniti per agenti (bash, operazioni sui file, ricerca web e altro). Questo esempio disabilita la ricerca web e il recupero web perché il compito di questa guida, scrivere un breve script Python, non fa uso del web. Fornisci a un agente solo gli strumenti di cui ha bisogno. Consulta Strumenti per l’elenco completo e le opzioni di configurazione per ciascuno strumento.

  2. Crea un ambiente

    Un ambiente definisce la “sandbox” (ambiente isolato) in cui viene eseguito il tuo agente. Questo utilizza una rete limited con i gestori di pacchetti consentiti, così il codice eseguito nella sandbox può raggiungere i registri di pacchetti e gli host di codice pubblici. Con la rete limited, l’elenco allowed_hosts si applica anche alla ricerca web e al recupero web, sebbene vengano eseguiti al di fuori della sandbox. Se non è elencato alcun host, come in questo ambiente, non restituiscono pagine né risultati di ricerca. Se un tuo agente usa questi strumenti, aggiungi a quell’elenco gli host di cui ha bisogno.

    ant apply environment.yaml
    environment.yaml
    # yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json
    name: quickstart-env
    config:
      type: cloud
      networking:
        type: limited
        allow_package_managers: true

    ant apply registra anche l’ID dell’ambiente in claude-lock.json. Per creare l’agente e l’ambiente con un solo comando, passa entrambi i file: ant apply coding-assistant.md environment.yaml.

  3. Avvia una sessione

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

    session = client.beta.sessions.create(
        agent=agent.id,
        environment_id=environment.id,
        title="Quickstart session",
    )
    
    print(f"Session ID: {session.id}")
  4. Invia un messaggio e ricevi la risposta in streaming

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

    with client.beta.sessions.events.stream(session.id) as stream:
        # Invia il messaggio dell'utente dopo l'apertura dello stream
        client.beta.sessions.events.send(
            session.id,
            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",
                        },
                    ],
                },
            ],
        )
    
        # Elabora gli eventi di streaming
        for event in stream:
            match event.type:
                case "agent.message":
                    for block in event.content:
                        if block.type == "text":
                            print(block.text, end="")
                case "agent.tool_use":
                    print(f"\n[Using tool: {event.name}]")
                case "session.status_idle":
                    print("\n\nAgent finished.")
                    break

    L’agente scrive uno script Python, lo esegue nella sandbox e verifica 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.

Cosa succede

Quando invii un evento utente, Claude Managed Agents:

  1. Predispone una sandbox: la configurazione del tuo ambiente determina come viene costruita.
  2. Esegue il ciclo dell’agente: Claude determina quali strumenti utilizzare in base al tuo messaggio.
  3. Esegue gli strumenti: scritture di file, comandi bash e altre chiamate agli strumenti vengono eseguiti all’interno della sandbox.
  4. Trasmette gli eventi in streaming: ricevi aggiornamenti in tempo reale mentre l’agente lavora.
  5. Entra in stato di inattività: l’agente emette un evento session.status_idle quando non ha più nulla da fare.

Crea un’app completa

Ciascuna di queste guide rapide abbina Claude Managed Agents a un popolare framework di chat per creare un’applicazione completa ed eseguibile. In ognuna, il framework visualizza l’interfaccia di chat mentre una sessione gestita esegue il ciclo dell’agente lato server: la sessione conserva la trascrizione, esegue gli strumenti in una sandbox e trasmette in streaming gli eventi che il front end visualizza.

Un analista di ricerca in una chat nel browser creata con Chat SDK di Vercel. Ogni conversazione è una sessione persistente che trasmette in streaming la propria risposta mentre un feed in tempo reale mostra le chiamate agli strumenti. Sostituendo l’adattatore di Chat SDK, lo stesso handler si sposta su Slack, Teams, Discord o WhatsApp.

Un analista di fogli di calcolo in una chat creata con le primitive di assistant-ui. Le sessioni costituiscono l’elenco dei thread, un reducer trasforma il registro degli eventi della sessione in messaggi e schede degli strumenti, e ogni comando bash mostra un controllo Consenti/Nega in linea prima di essere eseguito.

Un assistente per la finanza personale in una chat CopilotKit. L’adattatore AG-UI per Claude Managed Agents associa ogni thread di chat a una sessione gestita e trasmette in streaming le risposte token per token, mentre gli strumenti personalizzati visualizzano grafici interattivi in linea nella conversazione.

Prossimi passi

Crea configurazioni di agenti riutilizzabili e con versioni

Personalizza le impostazioni di rete e della sandbox

Abilita strumenti specifici per il tuo agente

Gestisci gli eventi e guida l’agente durante l’esecuzione

Esegui il tuo agente secondo una pianificazione cron ricorrente

Distilla una volta un corpus di documenti in un wiki della conoscenza, quindi rispondi a domande ricorrenti a partire da esso a una frazione del costo

Questa pagina ti è stata utile?