Utilizzo della Messages API
Pattern pratici ed esempi per utilizzare l’API Messages in modo efficace
Anthropic offre due modi per sviluppare con Claude, ciascuno adatto a casi d’uso diversi:
| Messages API | Claude Managed Agents | |
|---|---|---|
| Cos’è | Accesso diretto al prompting del modello | Harness per agenti preconfigurato e personalizzabile che viene eseguito su un’infrastruttura gestita |
| Ideale per | Loop di agenti personalizzati e controllo granulare | Attività di lunga durata e lavoro asincrono |
Questa guida tratta i pattern comuni per lavorare con l’API Messages, incluse le richieste di base, le conversazioni a più turni, le tecniche di “prefill” (precompilazione) e le capacità di visione. Per le specifiche complete dell’API, consulta il riferimento dell’API MessagesAnteprima disponibile con link al riferimento API (premi Tab finché il focus non entra nella scheda, Esc per tornare indietro). Per l’harness di agenti gestito, consulta invece la panoramica di Claude Managed Agents.
Richiesta e risposta di base
message = anthropic.Anthropic().messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message){
"id": "msg_01XFDUDYJgAACzvnptvVoYEL",
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "Hello!"
}
],
"model": "claude-opus-5-5",
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 12,
"output_tokens": 6
}
}Le risposte di rifiuto (stop_reason: "refusal") includono anche un oggetto stop_details che identifica la categoria di policy che ha attivato il rifiuto, su ogni modello. Consulta Come appare un rifiuto per il riferimento dei campi e codice di esempio per la gestione.
Turni conversazionali multipli
L’API Messages è stateless, il che significa che invii sempre l’intera cronologia conversazionale all’API. Puoi usare questo pattern per costruire una conversazione nel tempo. I turni conversazionali precedenti non devono necessariamente provenire effettivamente da Claude. Puoi usare messaggi assistant sintetici.
Con i thread di messaggi, in beta, l’API può conservare la conversazione, in modo che ogni richiesta successiva invii solo i nuovi messaggi. Un thread scade 5 minuti dopo la sua ultima richiesta e viene eliminato non oltre 1 ora dopo il suo ultimo utilizzo.
message = anthropic.Anthropic().messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[
{"role": "user", "content": "Hello, Claude"},
{"role": "assistant", "content": "Hello!"},
{"role": "user", "content": "Can you describe LLMs to me?"},
],
)
print(message){
"id": "msg_018gCsTGsXkYJVqYPxTgDHBU",
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "Sure, I'd be happy to provide..."
}
],
"model": "claude-opus-5-5",
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 30,
"output_tokens": 309
}
}Ruolo di sistema nei messaggi
Per aggiungere una nuova istruzione di sistema a metà di una conversazione, includi un messaggio con "role": "system" subito dopo un turno dell’utente. Quel messaggio non può essere la prima voce in messages. Questo funziona su Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8, Claude Sonnet 5.5 e Claude Haiku 5.5. Consulta le regole di posizionamento complete.
Un messaggio di sistema a metà conversazione ha la stessa autorità del campo system di primo livello, ma poiché viene aggiunto alla fine della cronologia dei messaggi, non invalida alcun prefisso memorizzato nella cache che lo precede. Usa il campo system di primo livello per le istruzioni che devono applicarsi fin dal primo turno, e un messaggio di sistema a metà conversazione per le istruzioni che diventano rilevanti solo in seguito.
Consulta Messaggi di sistema e modifiche agli strumenti a metà conversazione per la guida completa, incluso come combinarlo con la “prompt caching” (cache dei prompt).
Precompilazione della risposta di Claude
Puoi precompilare parte della risposta di Claude nell’ultima posizione dell’elenco dei messaggi di input. Usa questa tecnica per modellare la risposta di Claude. L’esempio seguente usa "max_tokens": 1 per ottenere da Claude una singola risposta a scelta multipla.
message = anthropic.Anthropic().messages.create(
model="claude-sonnet-4-5",
max_tokens=1,
messages=[
{
"role": "user",
"content": "What is latin for Ant? (A) Apoidea, (B) Rhopalocera, (C) Formicidae",
},
{"role": "assistant", "content": "The answer is ("},
],
)
print(message){
"id": "msg_01Q8Faay6S7QPTvEUUQARt7h",
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "C"
}
],
"model": "claude-sonnet-4-5",
"stop_reason": "max_tokens",
"stop_sequence": null,
"usage": {
"input_tokens": 42,
"output_tokens": 1
}
}Visione
Claude può leggere sia testo che immagini nelle richieste. Puoi fornire immagini usando i tipi di sorgente base64, url o file. Il tipo di sorgente file fa riferimento a un’immagine caricata tramite la Files API. I tipi di media supportati sono image/jpeg, image/png, image/gif e image/webp. Consulta la guida Visione per maggiori dettagli.
import base64
import httpx2
# Opzione 1: immagine codificata in base64
image_url = "https://platform.claude.com/docs/images/vision-example.jpg"
image_media_type = "image/jpeg"
image_data = base64.standard_b64encode(httpx2.get(image_url).content).decode("utf-8")
message = anthropic.Anthropic().messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": [
{
"type": "image",
"source": {
"type": "base64",
"media_type": image_media_type,
"data": image_data,
},
},
{"type": "text", "text": "What is in the above image?"},
],
}
],
)
print(message)
# Opzione 2: immagine referenziata tramite URL
message_from_url = anthropic.Anthropic().messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": [
{
"type": "image",
"source": {
"type": "url",
"url": "https://platform.claude.com/docs/images/vision-example.jpg",
},
},
{"type": "text", "text": "What is in the above image?"},
],
}
],
)
print(message_from_url){
"id": "msg_011CdKmWtV3oFx1C5yUbf5CY",
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "This image is a beautiful minimalist/flat-design illustration of a sunset landscape. Here's what it contains:\n\n**Sky & Sun:**\n- A warm gradient sky transitioning from golden-yellow at the top to deep orange toward the horizon\n- A large pale yellow sun positioned in the upper-right area\n\n**Birds:**\n- Three small silhouetted birds flying in the upper-left portion of the sky, depicted as simple \"M\" or \"v\" shapes\n\n**Mountains:**\n- Multiple layered mountain peaks in purple and maroon tones\n- The mountains overlap to create depth, with varying shades of dusty purple and deep burgundy\n\n**Water:**\n- A dark purple body of water at the bottom of the image\n- A reflection of the sun shown as horizontal cream/peach colored lines in the center-bottom area\n\nThe overall style is clean, geometric, and uses a warm sunset color palette (oranges, yellows, purples, and maroons), giving it a peaceful, serene aesthetic typical of modern vector/flat design artwork."
}
],
"model": "claude-opus-5-5",
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 1030,
"output_tokens": 350
}
}Passaggi successivi
Gestisci ogni valore di stop_reason e decidi cosa fare quando una risposta termina.
Fornisci a Claude strumenti per chiamare servizi e API esterni dall’interno dell’API Messages.
Controlla ambienti desktop con l’API Messages.
Consenti a Claude di navigare, leggere e interagire con pagine web in un browser che esegui tu.
Ottieni da Claude output JSON garantito e convalidato tramite schema.
Imposta un budget di token indicativo su un intero ciclo agentico con output_config.task_budget.
Disponibilità
Claude API
- Modelli
- Tutti i modelli
Amazon Bedrock
- Modelli
- Tutti i modelli
Amazon Bedrock (bedrock-runtime)
- Modelli
- Tutti i modelli
Claude Platform on AWS
- Modelli
- Tutti i modelli
Claude Models on Google Cloud (Anthropic managed)
- Modelli
- Tutti i modelli
Claude Models on Google Cloud (Google managed)
- Modelli
- Tutti i modelli
Microsoft Foundry
- Modelli
- Tutti i modelli
Gestione dei dati
Panoramica sulla gestione dei datiEndpoint applicabili
/v1/messages
Esclude Modelli coperti
Chiamate API standard per generare le risposte di Claude.
Questa pagina ti è stata utile?