Guida rapida

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

​

Prerequisiti

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

​

Configurazione

mkdir my-agent
cd my-agent

npm install @anthropic-ai/claude-agent-sdk

uv init
uv add claude-agent-sdk

python3 -m venv .venv
source .venv/bin/activate
pip install claude-agent-sdk

py -m venv .venv
.venv\Scripts\Activate.ps1
pip install claude-agent-sdk

ANTHROPIC_API_KEY=your-api-key

​

Crea un file buggy

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()

1. calculate_average([]) si arresta in modo anomalo con una 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

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"],  # Auto-approve these tools
            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())

1. query: il punto di ingresso principale che crea il loop 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 utilizza allowedTools per pre-approvare Read, Edit e Glob, e permissionMode: "acceptEdits" per auto-approvare i cambiamenti ai file. Altre opzioni includono systemPrompt, mcpServers e altro. Vedi tutte le opzioni per Python o TypeScript.

​

Esegui il tuo agente

npx tsx agent.ts

uv run agent.py

python agent.py

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 la gestione corretta degli errori

​

Prova altri prompt

• "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

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

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

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

​

Concetti chiave

​

Risoluzione dei problemi

​

Errore API thinking.type.enabled non è supportato per questo modello

API Error: 400 {"type":"invalid_request_error","message":"\"thinking.type.enabled\" is not supported for this model. Use \"thinking.type.adaptive\" and \"output_config.effort\" to control thinking behavior."}

​

Passaggi successivi

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