Guida rapida

Inizia con l'Agent SDK per Python o TypeScript per creare agenti AI che funzionano autonomamente

Utilizza l'Agent SDK per creare 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 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
pip3 install claude-agent-sdk

ANTHROPIC_API_KEY=your-api-key

Crea un file buggy

Questa guida rapida ti guida attraverso la creazione 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 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

Crea agent.py se stai utilizzando 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())

import { query } from "@anthropic-ai/claude-agent-sdk";

// Agentic loop: streams messages as Claude works
for await (const message of query({
prompt: "Review utils.py for bugs that would cause crashes. Fix any issues you find.",
options: {
allowedTools: ["Read", "Edit", "Glob"], // Tools Claude can use
permissionMode: "acceptEdits" // Auto-approve file edits
}
})) {
// Print human-readable output
if (message.type === "assistant" && message.message?.content) {
for (const block of message.message.content) {
if ("text" in block) {
console.log(block.text); // Claude's reasoning
} else if ("name" in block) {
console.log(`Tool: ${block.name}`); // Tool being called
}
}
} else if (message.type === "result") {
console.log(`Done: ${message.subtype}`); // Final result
}
}

Questo codice ha tre parti principali:

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.

Il loop 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 loop termina quando Claude completa il compito o incontra un errore.

La gestione dei messaggi all'interno del loop filtra l'output leggibile dall'uomo. Senza filtraggio, 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:

python3 agent.py

npx tsx agent.ts

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 la gestione corretta 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"
)

const _ = {
options: {
allowedTools: ["Read", "Edit", "Glob", "WebSearch"],
permissionMode: "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.",
)

const _ = {
options: {
allowedTools: ["Read", "Edit", "Glob"],
permissionMode: "acceptEdits",
systemPrompt: "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"
)

const _ = {
options: {
allowedTools: ["Read", "Edit", "Glob", "Bash"],
permissionMode: "acceptEdits"
}
};

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

Concetti chiave

Tools controllano cosa può fare il tuo agente:

Permission modes controllano quanto controllo umano desideri:

L'esempio sopra utilizza la modalità acceptEdits, che auto-approva le operazioni sui file in modo che l'agente possa funzionare senza prompt interattivi. Se desideri richiedere agli utenti l'approvazione, utilizza la modalità default e fornisci un callback canUseTool che raccoglie l'input dell'utente. Per un maggiore controllo, vedi Permissions.

Risoluzione dei problemi

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

Claude Opus 4.7 sostituisce thinking.type.enabled con thinking.type.adaptive. Le versioni precedenti di Agent SDK falliscono con il seguente errore API quando selezioni claude-opus-4-7:

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."}

Aggiorna a Agent SDK v0.2.111 o successivo per utilizzare Opus 4.7.

Passaggi successivi

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

• 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