Guida rapida

Usa l'Agent SDK per costruire un agente AI che legge il tuo codice, trova i bug e li corregge, il tutto senza intervento manuale.

Quello che farai:

1. Configurare un progetto con l'Agent SDK
2. Creare un file con del codice buggy
3. Eseguire un agente che trova e corregge i bug automaticamente

Prerequisiti

• Node.js 18+ o Python 3.10+
• Un account Anthropic (iscriviti qui)

Configurazione

Crea un file buggy

Questa guida rapida ti guida attraverso la costruzione di un agente che può trovare e correggere i bug nel codice. Per prima cosa, hai bisogno di un file con alcuni bug intenzionali che l'agente possa correggere. Crea utils.py nella directory my-agent e incolla il seguente codice:

def calculate_average(numbers):
    total = 0
    for num in numbers:
        total += num
    return total / len(numbers)

def get_user_name(user):
    return user["name"].upper()

Questo codice ha due bug:

1. calculate_average([]) si arresta in modo anomalo con divisione per zero
2. get_user_name(None) si arresta in modo anomalo con un TypeError

Costruisci un agente che trova e corregge i bug

Crea agent.py se stai usando l'SDK Python, o agent.ts per TypeScript:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage

async def main():
    # Agentic loop: streams messages as Claude works
    async for message in query(
        prompt="Review utils.py for bugs that would cause crashes. Fix any issues you find.",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Glob"],  # Tools Claude can use
            permission_mode="acceptEdits"            # Auto-approve file edits
        )
    ):
        # Print human-readable output
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)              # Claude's reasoning
                elif hasattr(block, "name"):
                    print(f"Tool: {block.name}")   # Tool being called
        elif isinstance(message, ResultMessage):
            print(f"Done: {message.subtype}")      # Final result

asyncio.run(main())

Questo codice ha tre parti principali:

1. query: il punto di ingresso principale che crea il ciclo agentico. Restituisce un iteratore asincrono, quindi usi async for per trasmettere i messaggi mentre Claude lavora. Vedi l'API completa nel riferimento SDK Python o TypeScript.

2. prompt: quello che vuoi che Claude faccia. Claude capisce quali strumenti usare in base al compito.

3. options: configurazione per l'agente. Questo esempio usa allowedTools per limitare Claude a Read, Edit e Glob, e permissionMode: "acceptEdits" per approvare automaticamente i cambiamenti ai file. Altre opzioni includono systemPrompt, mcpServers e altro. Vedi tutte le opzioni per Python o TypeScript.

Il ciclo async for continua a funzionare mentre Claude pensa, chiama strumenti, osserva i risultati e decide cosa fare dopo. Ogni iterazione produce un messaggio: il ragionamento di Claude, una chiamata a uno strumento, un risultato dello strumento, o il risultato finale. L'SDK gestisce l'orchestrazione (esecuzione dello strumento, gestione del contesto, tentativi) quindi consumi semplicemente il flusso. Il ciclo termina quando Claude completa il compito o incontra un errore.

La gestione dei messaggi all'interno del ciclo filtra l'output leggibile dall'uomo. Senza filtri, vedresti oggetti messaggio grezzi inclusa l'inizializzazione del sistema e lo stato interno, il che è utile per il debug ma rumoroso altrimenti.

Esegui il tuo agente

Il tuo agente è pronto. Eseguilo con il seguente comando:

Dopo l'esecuzione, controlla utils.py. Vedrai codice difensivo che gestisce elenchi vuoti e utenti nulli. Il tuo agente autonomamente:

1. Ha letto utils.py per comprendere il codice
2. Ha analizzato la logica e identificato i casi limite che causerebbero arresti anomali
3. Ha modificato il file per aggiungere una corretta gestione degli errori

Questo è ciò che rende diverso l'Agent SDK: Claude esegue gli strumenti direttamente invece di chiederti di implementarli.

Prova altri prompt

Ora che il tuo agente è configurato, prova alcuni prompt diversi:

• "Add docstrings to all functions in utils.py"
• "Add type hints to all functions in utils.py"
• "Create a README.md documenting the functions in utils.py"

Personalizza il tuo agente

Puoi modificare il comportamento del tuo agente cambiando le opzioni. Ecco alcuni esempi:

Aggiungi capacità di ricerca web:

options=ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob", "WebSearch"],
    permission_mode="acceptEdits"
)

Dai a Claude un prompt di sistema personalizzato:

options=ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob"],
    permission_mode="acceptEdits",
    system_prompt="You are a senior Python developer. Always follow PEP 8 style guidelines."
)

Esegui comandi nel terminale:

options=ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob", "Bash"],
    permission_mode="acceptEdits"
)

Con Bash abilitato, prova: "Write unit tests for utils.py, run them, and fix any failures"

Concetti chiave

Strumenti controllano cosa può fare il tuo agente:

Modalità di permesso controllano quanto controllo umano desideri:

L'esempio precedente usa la modalità acceptEdits, che approva automaticamente le operazioni sui file in modo che l'agente possa funzionare senza prompt interattivi. Se vuoi richiedere agli utenti l'approvazione, usa la modalità default e fornisci un callback canUseTool che raccoglie l'input dell'utente. Per un maggiore controllo, vedi Permessi.

Passaggi successivi

Ora che hai creato il tuo primo agente, impara come estendere le sue capacità e adattarlo al tuo caso d'uso:

• Permessi: controlla cosa può fare il tuo agente e quando ha bisogno di approvazione
• Hook: esegui codice personalizzato prima o dopo le chiamate agli strumenti
• Sessioni: costruisci agenti multi-turn che mantengono il contesto
• Server MCP: connettiti a database, browser, API e altri sistemi esterni
• Hosting: distribuisci agenti a Docker, cloud e CI/CD
• Agenti di esempio: vedi esempi completi: assistente email, agente di ricerca e altro