AI Gateway: esempi guidati
Crea un assistant, aggiungi ricerca lessicale, chiedi una decisione tipizzata e genera embeddings.
AI Gateway: esempi guidati
Esegui questi esempi da un backend affidabile. Contenuti e ID sono fittizi: sostituiscili con risorse della company associata alla tua API key. Imposta DONUTWORK_API_KEY nell'ambiente del server senza inserire una chiave reale nel codice o nella cronologia della shell. Gli URL usano la versione 2026-02-01.
Servono connection AI Gateway attive prima di iniziare: una con purpose: generation per la chat, una con purpose: decision per le decisioni e una con purpose: embedding per i vettori. Configura le credenziali provider tramite il tuo flusso sicuro: l'API non le restituisce. Consulta la reference delle connection. Inferenza ed embeddings chiamano un provider e possono consumare il budget mensile.
Elenca le connection disponibili e annota ID e purpose (ai_connections:read):
curl 'https://api.hub.donutwork.com/2026-02-01/ai-gateway/connections.json' \
-H "Authorization: Bearer $DONUTWORK_API_KEY"1. Creare un assistant e fare una domanda
Scope: ai_prompts:write, ai_assistants:write, ai_inference:write.
Crea un prompt pubblicato e conserva l'id come PROMPT_ID. Il prompt resta nella company autenticata: non inserirvi segreti o dati dei clienti.
curl -X POST 'https://api.hub.donutwork.com/2026-02-01/ai-gateway/prompts.json' \
-H "Authorization: Bearer $DONUTWORK_API_KEY" \
-H 'Content-Type: application/json' \
--data '{"name":"Assistente prodotto di esempio","content":"Rispondi usando informazioni approvate. Se non conosci la risposta, dichiaralo chiaramente."}'Crea un assistant con una connection generation attiva e il prompt ottenuto. Conserva l'id dell'assistant come ASSISTANT_ID.
curl -X POST 'https://api.hub.donutwork.com/2026-02-01/ai-gateway/assistants.json' \
-H "Authorization: Bearer $DONUTWORK_API_KEY" \
-H 'Content-Type: application/json' \
--data '{"name":"Assistente prodotto di esempio","connection_id":"GENERATION_CONNECTION_ID","prompt_id":"PROMPT_ID"}'Fai una domanda senza retrieval. La risposta include answer, request_id, usage ed eventuali citazioni. Usa una nuova chiave di idempotenza per ogni richiesta logica; riutilizzala soltanto per ripetere una richiesta identica.
curl -X POST 'https://api.hub.donutwork.com/2026-02-01/ai-gateway/assistants/ASSISTANT_ID/chat.json' \
-H "Authorization: Bearer $DONUTWORK_API_KEY" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: example-chat-request-0001' \
--data '{"message":"In cosa può aiutarmi questo assistente?","retrieval":{"mode":"none"}}'Se connection o prompt diventano indisponibili, la chat può restituire 409. Il budget mensile vincolante può produrre 402; un errore del provider può produrre 502. Consulta la reference degli assistant.
2. Basare le risposte su testi approvati
Scope: ai_knowledge_bases:write, ai_assistants:write, ai_inference:write.
Una knowledge base lessicale non richiede vector store né connection embedding. Creala e conserva l'id restituito come KNOWLEDGE_BASE_ID.
curl -X POST 'https://api.hub.donutwork.com/2026-02-01/ai-gateway/knowledge-bases.json' \
-H "Authorization: Bearer $DONUTWORK_API_KEY" \
-H 'Content-Type: application/json' \
--data '{"name":"Policy di esempio","description":"Testi pubblici approvati","retrieval_mode":"lexical"}'Aggiungi un testo approvato. Se ometti l'ACL, il documento è ricercabile dai chiamanti entro la knowledge base di questa company. Per limitare la visibilità usa i principal di accesso; il backend deve passare i principal dell'utente durante il retrieval.
curl -X POST 'https://api.hub.donutwork.com/2026-02-01/ai-gateway/knowledge-bases/KNOWLEDGE_BASE_ID/documents.json' \
-H "Authorization: Bearer $DONUTWORK_API_KEY" \
-H 'Content-Type: application/json' \
--data '{"name":"Resi di esempio","content":"Gli acquisti di esempio possono essere restituiti entro 30 giorni dalla consegna.","metadata":{"language":"it","section":"Resi"}}'Crea un secondo assistant generation usando prompt e connection precedenti, insieme alla knowledge base. Conserva l'id come RETRIEVAL_ASSISTANT_ID.
curl -X POST 'https://api.hub.donutwork.com/2026-02-01/ai-gateway/assistants.json' \
-H "Authorization: Bearer $DONUTWORK_API_KEY" \
-H 'Content-Type: application/json' \
--data '{"name":"Assistente policy di esempio","connection_id":"GENERATION_CONNECTION_ID","prompt_id":"PROMPT_ID","knowledge_base_ids":["KNOWLEDGE_BASE_ID"]}'
curl -X POST 'https://api.hub.donutwork.com/2026-02-01/ai-gateway/assistants/RETRIEVAL_ASSISTANT_ID/chat.json' \
-H "Authorization: Bearer $DONUTWORK_API_KEY" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: example-policy-request-0001' \
--data '{"message":"Qual è il termine di reso di esempio?","retrieval":{"mode":"assistant","limit":3}}'Controlla answer, citations e retrieval.results_count. Le citazioni dipendono dall'uso effettivo dei passaggi recuperati. Per la ricerca vettoriale consulta la reference delle knowledge base: richiede anche vector store e connection embedding.
3. Richiedere una decisione tipizzata
Scope: ai_assistants:write, ai_inference:write.
Gli assistant decisionali usano una connection attiva con purpose: decision. Le domande sono salvate nell'assistant e non possono essere sovrascritte nella chiamata. Non usano prompt, retrieval, chat o web search.
curl -X POST 'https://api.hub.donutwork.com/2026-02-01/ai-gateway/assistants.json' \
-H "Authorization: Bearer $DONUTWORK_API_KEY" \
-H 'Content-Type: application/json' \
--data '{"name":"Smistamento ticket di esempio","connection_id":"DECISION_CONNECTION_ID","decision_questions":{"team":{"type":"choice","instructions":"Scegli il team per questo ticket di esempio.","criteria":{"billing":"Problema di pagamento o fattura","support":"Altra domanda sul prodotto"}}}}'Conserva l'id come DECISION_ASSISTANT_ID, poi invia soltanto lo stato corrente. La risposta include un oggetto answers indicizzato con il nome delle domande, oltre a usage e request_id; i campi interni delle risposte dipendono dal provider decisionale.
curl -X POST 'https://api.hub.donutwork.com/2026-02-01/ai-gateway/assistants/DECISION_ASSISTANT_ID/decisions.json' \
-H "Authorization: Bearer $DONUTWORK_API_KEY" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: example-decision-request-0001' \
--data '{"state":{"ticket_type":"billing","topic":"copia fattura"}}'Usa POST /ai-gateway/decisions.json se il chiamante deve passare connection_id, state e questions a ogni richiesta. Consulta la reference delle decisioni.
4. Generare embeddings per un indice esterno
Scope: ai_embeddings:write.
Usa una connection attiva con purpose: embedding. input_type e dimensions dipendono dal provider: omettili se non sono supportati. La risposta contiene i vettori in data[].embedding e l'uso normalizzato; conserva i vettori nel tuo indice autorizzato se ti servono in seguito.
curl -X POST 'https://api.hub.donutwork.com/2026-02-01/ai-gateway/embeddings.json' \
-H "Authorization: Bearer $DONUTWORK_API_KEY" \
-H 'Content-Type: application/json' \
--data '{"connection_id":"EMBEDDING_CONNECTION_ID","input":["Policy resi di esempio","Policy spedizioni di esempio"]}'La richiesta accetta al massimo 64 testi e 1 MB totale. Se invii model e non coincide con quello della connection, ricevi 409. Consulta embeddings e usage per limiti e costi.