DocumentazioneThread ed esecuzioni
I tuoi assistenti
Thread ed esecuzioni
Un thread conserva una conversazione con un assistente. Ogni domanda vi avvia un’esecuzione, che segui fino alla risposta.
In questa pagina
Un turno di conversazione
Aprire un thread
POST /v1/threadCon l’ID dell’assistente.Fare la domanda
POST /v1/thread/{id}/messagesIl messaggio della persona.Avviare l’esecuzione
POST /v1/thread/{id}/runsL’assistente lavora su questo messaggio. La risposta contiene l’ID dell’esecuzione.
# Open a thread with the assistant.
curl https://api.learnya.ai/v1/thread \
-H "Authorization: Bearer $LEARNYA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"assistantId": "ASSISTANT_ID", "title": "Ticket 42"}'
# Post the question.
curl https://api.learnya.ai/v1/thread/THREAD_ID/messages \
-H "Authorization: Bearer $LEARNYA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"content": "Where is my invoice?"}'
# Start the run on it. The answer carries the run id.
curl https://api.learnya.ai/v1/thread/THREAD_ID/runs \
-H "Authorization: Bearer $LEARNYA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"triggerMessageId": "MESSAGE_ID"}'def post(path, body):
reply = requests.post(
f"{API}{path}", headers=HEADERS, json=body
)
reply.raise_for_status()
return reply.json()
thread = post("/thread", {"assistantId": assistant["id"]})
question = post(
f"/thread/{thread['id']}/messages",
{"content": "Where is my invoice?"},
)
run = post(
f"/thread/{thread['id']}/runs",
{"triggerMessageId": question["id"]},
)
run_id = run["id"]async function post(path, body) {
const r = await fetch(`${API}${path}`, {
method: "POST",
headers,
body: JSON.stringify(body),
})
if (!r.ok) throw new Error(`${r.status} on ${path}`)
return r.json()
}
const thread = await post("/thread", {
assistantId: assistant.id,
})
const question = await post(`/thread/${thread.id}/messages`, {
content: "Where is my invoice?",
})
const run = await post(`/thread/${thread.id}/runs`, {
triggerMessageId: question.id,
})
const runId = run.idasync function post<T>(path: string, body: unknown) {
const r = await fetch(`${API}${path}`, {
method: "POST",
headers,
body: JSON.stringify(body),
})
if (!r.ok) throw new Error(`${r.status} on ${path}`)
return (await r.json()) as T
}
const thread = await post<{ id: string }>("/thread", {
assistantId: assistant.id,
})
const question = await post<{ id: string }>(
`/thread/${thread.id}/messages`,
{ content: "Where is my invoice?" },
)
const run = await post<{ id: string; status: string }>(
`/thread/${thread.id}/runs`,
{ triggerMessageId: question.id },
)
const runId = run.idSeguire l’esecuzione
Interroga l’esecuzione finché non si conclude. Quando è terminata, la risposta si trova in output.
| Stato | Cosa significa |
|---|---|
queued | In attesa di un worker libero |
in_progress | L’assistente sta lavorando |
completed | Terminata, la risposta è pronta |
failed | Interrotta da un errore, descritto in error |
canceled | Fermata prima della fine |
import time
while True:
reply = requests.get(f"{API}/run/{run_id}", headers=HEADERS)
run = reply.json()
if run["status"] in ("completed", "failed", "canceled"):
break
time.sleep(1)
if run["status"] == "completed":
print(run["output"][0]["text"])
else:
print(run["status"], run.get("error"))const DONE = ["completed", "failed", "canceled"]
let run
do {
await new Promise((done) => setTimeout(done, 1000))
run = await fetch(`${API}/run/${runId}`, { headers }).then(
(r) => r.json(),
)
} while (!DONE.includes(run.status))
const done = run.status === "completed"
console.log(done ? run.output[0].text : run.error)type RunStatus =
| "queued"
| "in_progress"
| "completed"
| "failed"
| "canceled"
interface Run {
id: string
status: RunStatus
output?: { type: "text"; text: string }[] | null
error?: string | null
}
const DONE: RunStatus[] = ["completed", "failed", "canceled"]
let run: Run
do {
await new Promise((done) => setTimeout(done, 1000))
const r = await fetch(`${API}/run/${runId}`, { headers })
run = (await r.json()) as Run
} while (!DONE.includes(run.status))
const done = run.status === "completed"
console.log(done ? run.output?.[0].text : run.error)Risposta
{
"id": "c2a7e9d4-1b3f-4e6a-8c5d-9f0b2e4a6d18",
"threadId": "8e4b1d6f-2c9a-4f7e-b3d5-0a6c8e2f4b91",
"assistantId": "6f1c2b0e-3a4d-4c8e-9b7a-2d5e8f1a0c34",
"status": "completed",
"output": [
{ "type": "text", "text": "Your invoice 2026-114 was sent on 2 October." }
],
"modelUsed": "learnya-flash",
"error": null
}Disponibile anche
GET /v1/thread/{id}/messages I messaggi del thread, fino a 400 per pagina.
GET /v1/run/{id}/stream La risposta come eventi inviati dal server, mentre viene scritta.
POST /v1/runs/{id}/stop Interrompe un’esecuzione.
GET /v1/threads I thread della persona, filtrabili per assistente.
Configurare un’esecuzione
modelOverridetesto- Il modello di questa sola esecuzione: flash o max.
reasoning_efforttesto- Lo sforzo di ragionamento: none, low, medium o high.
maxStepsintero- Il numero massimo di passaggi dell’esecuzione, da 1 a 500.
Limiti
- 20 esecuzioni al minuto per persona
- 600 richieste al minuto per le altre route
- Il numero di esecuzioni al giorno dipende dal piano dello spazio di lavoro