Riferimento API Agente Jenova

URL di base: https://api.jenova.ai/v1

Autenticazione: Bearer token nell'header Authorization

Indice

• Panoramica
• Guida introduttiva
• Concetti fondamentali
• Autenticazione
• Endpoint API
  • Messaggi
  • Sessioni
  • Operazioni
  • Crediti
  • Agenti
  • Modelli
  • Documentazione
• Streaming (SSE)
• Integrazione server MCP
• Fatturazione
• Limiti di frequenza
• Gestione degli errori
• Paginazione
• Localizzazione
• Privacy e dati
• Supporto

Panoramica

Costruisca ed esegua agenti AI pronti per la produzione senza dover assemblare da zero lo stack sottostante. Jenova Agent API riunisce ogni funzionalità principale in un unico servizio gestito:

Lo stack completo per gli agenti

• Orchestrazione degli Agenti: Un livello di orchestrazione unificato coordina modelli, strumenti, memoria e recupero delle informazioni attraverso flussi di lavoro complessi.
• Memoria e contesto: Memoria di conversazione e contesto illimitati integrati in ogni sessione. Nessuna gestione dello stato esterna richiesta.
• Strumenti e MCP: Integrazioni di strumenti illimitate con strumenti nativi della piattaforma e qualsiasi server MCP remoto, pronti all'uso.
• Utilizzi qualsiasi Modello: Alimenti i Suoi agenti con modelli di OpenAI, Anthropic, Google, xAI, Qwen e altri ancora tramite un'unica integrazione.
• Archiviazione completamente gestita: Database relazionali e vettoriali gestiti con RAG integrato. Nessuna infrastruttura da provisionare o scalare.
• Livello produzione: Utilizzato da centinaia di migliaia di utenti. Infrastruttura completamente gestita, API stabili, progettato per il traffico di produzione.

Guida introduttiva

1. Ottenga la Sua chiave API

Generi una chiave API dal pannello di controllo per sviluppatori all'indirizzo www.jenova.ai/platform. Le chiavi utilizzano il formato jnv_sk_* e vengono passate come Bearer token.

2. Scelga o crei un Agente

Scelga un agente predefinito dalla piattaforma, oppure crei un agente personalizzato nel pannello di controllo con istruzioni, impostazioni del modello, file della base di conoscenza, strumenti e server MCP.

3. Invii il Suo primo Messaggio

Crei una sessione e invii un messaggio in un'unica chiamata:

curl -N -X POST https://api.jenova.ai/v1/messages \
  -H "Authorization: Bearer jnv_sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "my-support-agent",
    "user": "user_12345",
    "content": "What can you help me with?"
  }'

La risposta viene trasmessa in streaming come Server-Sent Events:

event: stream_started
data: {"session_id":"ses_xyz789","run_id":"run_abc123","agent":"my-support-agent"}

event: stream_delta
data: {"session_id":"ses_xyz789","run_id":"run_abc123","chunk_content":"I can help you with ","seq":1}

event: stream_ended
data: {"session_id":"ses_xyz789","run_id":"run_abc123","success":true,"stop_reason":"end_run","usage":{"cost":"0.0032"}}

Acquisisca session_id da stream_started per le richieste successive. Per le risposte JSON sincrone, veda Invia Messaggio.

Concetti fondamentali

Agente

Un agente AI con cui interagisce tramite l'API. Ogni agente ha uno slug univoco (ad es. my-support-agent) utilizzato come valore agent nelle chiamate API.

• Predefinito: Selezioni tra gli agenti già esistenti sulla piattaforma.
• Personalizzato: Configuri il Suo agente nel pannello di controllo con istruzioni, modello, base di conoscenza, strumenti e server MCP.

Sessione

Un thread di conversazione indipendente tra un utente finale e un agente.

• Identificatore: ID con prefisso (ad es. ses_abc123)
• Ambito: Possono esistere più sessioni per lo stesso agente e utente finale, ciascuna con uno stato di conversazione indipendente
• Ciclo di vita: Le sessioni persistono indefinitamente finché non vengono eliminate tramite API. Per attività one-shot senza archiviazione, utilizzi POST /messages con ephemeral: true
• Isolamento della piattaforma: Le sessioni API sono separate dalle conversazioni nell'app web di Jenova. Utenti finali, cronologia delle sessioni e fatturazione sono indipendenti tra l'API e l'app web.

Messaggio

Una singola voce nella cronologia di conversazione di una sessione, restituita dagli endpoint Messaggi. Ogni messaggio include un oggetto from strutturato con type ("user" o "agent") e name, oltre a un type di messaggio:

• external - un messaggio di conversazione destinato a essere visualizzato come contenuto di chat.
• internal - un messaggio facoltativo che rappresenta i passaggi di lavoro dell'agente durante un'esecuzione, come chiamate a strumenti o recupero di informazioni.

Esecuzione

Una singola esecuzione dell'agente creata quando invia un messaggio. Un'esecuzione ha un run_id, può trasmettere eventi in streaming mentre è attiva e produce uno o più messaggi completati. Ogni sessione può avere solo un'esecuzione attiva alla volta.

Utente finale

Il campo user associa le sessioni a un utente finale nella Sua applicazione. Utilizzi un ID stabile e opaco, come il Suo ID utente interno o un UUID. Eviti indirizzi email o altri dati personali identificativi a meno che la Sua applicazione non li richieda. Le sessioni create con lo stesso valore user vengono raggruppate insieme, consentendo l'elenco delle sessioni per singolo utente.

Se user viene omesso, la sessione viene associata al Suo account sviluppatore e non potrà essere filtrata in seguito per utente finale. Passi user in produzione.

Per le richieste su sessioni esistenti, user è una protezione di proprietà facoltativa. Se lo fornisce, deve corrispondere al valore user utilizzato al momento della creazione della sessione; in caso contrario l'API restituisce 404 session_not_owned. Lo invii come parametro di query nelle richieste GET e DELETE, e nel corpo JSON nelle richieste POST e PATCH.

Autenticazione

Autentichi ogni richiesta con un Bearer token nell'header Authorization:

Authorization: Bearer jnv_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Le chiavi API vengono generate dal pannello di controllo per sviluppatori.

User-Agent è facoltativo. Gli SDK possono impostarlo per finalità diagnostiche, ma l'API non lo richiede.

Formato della chiave: le chiavi iniziano con il prefisso jnv_sk_ seguito da una stringa casuale codificata in base62.

Limiti: ogni account sviluppatore può avere fino a 10 chiavi API attive.

Endpoint API

Messaggi

L'invio di Messaggi è il percorso API principale. Utilizzi POST /messages per il primo messaggio; questo crea la sessione e avvia l'esecuzione in un'unica richiesta. Utilizzi POST /sessions/{session_id}/messages per continuare una sessione di cui ha già acquisito il session_id.

Invia Messaggio

POST /messages

Crea una sessione persistente e invia il primo messaggio in un'unica richiesta atomica. Imposti ephemeral: true per una richiesta one-shot in streaming senza memorizzazione, che non salva alcuna sessione o storico dei messaggi, non restituisce un ID sessione e non può essere continuata.

Corpo della richiesta

Esempio - Streaming (predefinito)

curl -N -X POST https://api.jenova.ai/v1/messages \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "my-support-agent",
    "user": "user_12345",
    "content": "Hello, I need help with my account"
  }'

La risposta è uno stream SSE (per il formato degli eventi, vedere Streaming (SSE)). Le richieste persistenti includono il nuovo session_id; le richieste con ephemeral: true omettono session_id e devono utilizzare lo streaming.

Esempio - JSON (senza streaming)

curl -X POST https://api.jenova.ai/v1/messages \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "my-support-agent",
    "user": "user_12345",
    "content": "Hello, I need help with my account",
    "stream": false
  }'

Risposta

Le risposte in streaming emettono gli eventi SSE documentati in Streaming (SSE). Le risposte senza streaming restituiscono la struttura JSON del messaggio mostrata in Continua Sessione, inclusi stop_reason e usage per la richiesta completata.

Se un'esecuzione senza streaming è ancora in elaborazione dopo 90 secondi, l'API restituisce 202 Accepted con status: "processing", session_id, run_id e message. L'esecuzione continua dopo la risposta o la disconnessione del client; verifichi i messaggi della sessione, oppure utilizzi lo streaming per i flussi di lavoro più lunghi.

Errori

Continua Sessione

POST /sessions/{session_id}/messages

Invia un Messaggio a una Sessione persistente esistente e riceve la risposta dell'agente. Per impostazione predefinita, le risposte sono trasmesse in streaming tramite SSE; impostare stream: false per JSON.

Corpo della richiesta

Esempio - Streaming (predefinito)

curl -N -X POST https://api.jenova.ai/v1/sessions/ses_abc123/messages \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "How do I reset my password?"
  }'

Esempio - JSON (senza streaming)

curl -X POST https://api.jenova.ai/v1/sessions/ses_abc123/messages \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "How do I reset my password?",
    "stream": false
  }'

Risposta 200 OK

{
  "id": "msg_xyz789",
  "session_id": "ses_abc123",
  "sequence": 4,
  "from": {
    "type": "agent",
    "name": "my-support-agent"
  },
  "type": "external",
  "time": "2026-05-19T10:31:05Z",
  "content": "To reset your password, go to Settings > Security > Change Password...",
  "model": "claude-sonnet-5",
  "files": [],
  "stop_reason": "end_run",
  "usage": {
    "cost": "0.0015"
  }
}

Se la Sessione ha già un'Esecuzione attiva o Messaggi in coda, l'API restituisce JSON 202 Accepted con status: "queued", session_id, run_id e message_id. Il Messaggio dell'utente viene elaborato dall'Esecuzione attiva.

Errori

Idempotenza

POST /messages e POST /sessions/{session_id}/messages accettano un header opzionale Idempotency-Key. Utilizzi una chiave univoca per ogni invio logico dell'utente, in modo che i nuovi tentativi di rete o i doppi invii non creino esecuzioni duplicate.

curl -N -X POST https://api.jenova.ai/v1/messages \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: send-user_12345-2026-05-19T10:30:00Z" \
  -d '{
    "agent": "my-support-agent",
    "user": "user_12345",
    "content": "Hello"
  }'

Non in streaming: Ripetere la richiesta restituisce la risposta salvata 200 o 202 con l'header Idempotent-Replayed: true.

Streaming: Lo stream non viene riprodotto. Ripetere la richiesta mentre è in esecuzione o dopo il completamento restituisce un errore di idempotenza con il run_id originale e, per le richieste persistenti, il session_id. Utilizzi GET /sessions/{session_id}/runs/{run_id} per verificare un'esecuzione attiva, oppure GET /sessions/{session_id}/messages per recuperare i risultati persistiti.

Esempio di nuovo tentativo su streaming completato:

HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "error": {
    "code": "idempotency_key_reused",
    "message": "This Idempotency-Key has already completed. Streaming responses cannot be replayed; use the returned session_id and run_id to retrieve the result."
  },
  "idempotency": {
    "status": "completed",
    "session_id": "ses_abc123",
    "run_id": "run_abc123"
  }
}

Errori di idempotenza

Elenca Messaggi

GET /sessions/{session_id}/messages

Restituisce un elenco paginato dei messaggi visibili della conversazione. La prima pagina contiene i messaggi più recenti; all'interno di ciascuna pagina, i messaggi sono in ordine cronologico (dal più vecchio al più recente). sequence è un numero d'ordine stabile all'interno della sessione.

Parametri di query

Esempio

curl "https://api.jenova.ai/v1/sessions/ses_abc123/messages?limit=50" \
  -H "Authorization: Bearer jnv_sk_xxx"

Risposta 200 OK

{
  "items": [
    {
      "id": "msg_002",
      "session_id": "ses_abc123",
      "sequence": 4,
      "from": {
        "type": "agent",
        "name": "my-support-agent"
      },
      "type": "external",
      "time": "2026-05-19T10:31:05Z",
      "content": "To reset your password, go to Settings > Security...",
      "model": "claude-sonnet-5",
      "files": []
    }
  ],
  "next_cursor": "",
  "has_more": false
}

Oggetto Messaggio

Oggetto File

Errori

Ottieni Messaggio

GET /sessions/{session_id}/messages/{message_id}

Recupera un singolo messaggio visibile tramite ID.

Risposta 200 OK

Restituisce un singolo oggetto messaggio con la stessa struttura della risposta dell'elenco.

Errori

Allegati file

Fornisca URL HTTPS pubblicamente accessibili nel campo file_urls.

Formati supportati

• Immagini: JPG, JPEG, PNG, WebP
• Documenti: PDF, DOCX, XLSX, PPTX, TXT, CSV, RTF, MD, HTML, XML, JSON, LOG
• Codice: JS, TS, TSX, JSX, PY, Java, Go, C, CPP, H, HPP, CS, RB, PHP, RS, Swift, KT, Scala, SQL, CSS, YAML, YML

Quando si elencano i messaggi, i file allegati compaiono nell'array files del messaggio.

Sessioni

Le sessioni sono conversazioni persistenti tra un utente finale e un agente. La maggior parte delle integrazioni può crearle implicitamente con POST /messages.

Crea Sessione

POST /sessions

Crea una sessione persistente vuota associata a un agente specifico. Utilizzi questo endpoint quando ha bisogno di un ID di sessione prima del primo messaggio; altrimenti preferisca POST /messages.

Nota: ephemeral non è accettato su POST /sessions; utilizzi POST /messages con ephemeral: true per richieste occasionali senza archiviazione.

Corpo della richiesta

Esempio

curl -X POST https://api.jenova.ai/v1/sessions \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "my-support-agent",
    "user": "user_12345",
    "session_name": "Billing inquiry"
  }'

Risposta 201 Created

{
  "id": "ses_abc123",
  "session_name": "Billing inquiry",
  "agent": "my-support-agent",
  "user": "user_12345",
  "model": "claude-sonnet-5",
  "created_at": "2026-05-19T10:30:00Z",
  "updated_at": "2026-05-19T10:30:00Z"
}

Errori

Elenca Sessioni

GET /sessions

Restituisce un elenco paginato delle Sue sessioni, ordinato per data di ultimo aggiornamento più recente.

Parametri di query

Esempio

curl "https://api.jenova.ai/v1/sessions?user=user_12345&limit=10" \
  -H "Authorization: Bearer jnv_sk_xxx"

Risposta 200 OK

{
  "items": [
    {
      "id": "ses_abc123",
      "session_name": "Billing inquiry",
      "agent": "my-support-agent",
      "user": "user_12345",
      "model": "claude-sonnet-5",
      "created_at": "2026-05-19T10:30:00Z",
      "updated_at": "2026-05-19T11:15:00Z"
    }
  ],
  "next_cursor": "eyJ2IjoxLCJrIjoiY3VyXzAxIn0",
  "has_more": true
}

Errori

Ottieni Sessione

GET /sessions/{session_id}

Recupera una singola sessione tramite ID.

Risposta 200 OK

Restituisce un oggetto sessione con la stessa struttura della risposta di creazione.

Errori

Rinomina Sessione

PATCH /sessions/{session_id}

Aggiorna il nome visualizzato di una sessione.

Corpo della richiesta

Risposta 200 OK

Restituisce l'oggetto sessione aggiornato.

Errori

Elimina Sessione

DELETE /sessions/{session_id}

Elimina definitivamente una sessione e tutti i suoi messaggi. La sessione non deve avere un'esecuzione attiva.

Risposta 204 No Content

Errori

Operazioni

Questi endpoint sono controlli di ripristino e modifica per le sessioni persistenti. La maggior parte delle integrazioni necessita solo di Annulla; utilizzi le altre operazioni quando desidera intenzionalmente modificare o ripristinare lo stato della sessione. Tutte le operazioni supportano il controllo facoltativo di proprietà user descritto in Utente finale.

Annulla Esecuzione attiva

POST /sessions/{session_id}/cancel

Annulla l'esecuzione dell'agente attualmente in corso. Questo non elimina i messaggi già completati prima dell'annullamento.

Corpo della richiesta

Risposta 204 No Content

Errori

Annulla e rimuovi l'Esecuzione attiva

POST /sessions/{session_id}/undo

Annulla l'esecuzione attiva, attende che si interrompa, quindi rimuove tutti i messaggi che aveva già aggiunto. Nessun output aggiuntivo viene salvato dopo l'emissione del comando di annullamento e rimozione.

Corpo della richiesta

Risposta 200 OK

{
  "session_id": "ses_abc123",
  "run_id": "run_abc123",
  "deleted": ["msg_002", "msg_001"]
}

Se l'esecuzione viene annullata prima che qualsiasi messaggio sia completato, deleted è un array vuoto.

Errori

Elimina Messaggi recenti

POST /sessions/{session_id}/messages/delete

Rimuove gli N Messaggi più recenti da una Sessione inattiva. La Sessione non deve avere un'Esecuzione attiva.

Corpo della richiesta

Risposta 200 OK

{
  "deleted": ["msg_002", "msg_001"]
}

Errori

Duplica Sessione

POST /sessions/{session_id}/fork

Crea una nuova Sessione copiando la Sessione di origine fino a un Messaggio specifico. La Sessione di origine non deve avere un'Esecuzione attiva.

Corpo della richiesta

Risposta 201 Created

Restituisce l'oggetto Sessione appena creato, con la stessa struttura della creazione di una Sessione.

Errori

Ottieni stato Esecuzione

GET /sessions/{session_id}/runs/{run_id}

Restituisce lo stato attuale di un'Esecuzione attiva. Utilizzi questo endpoint dopo una connessione SSE interrotta o dopo una risposta di idempotenza che ha restituito un run_id. Al termine di un'Esecuzione, recuperi i risultati con GET /sessions/{session_id}/messages.

Risposta 200 OK

{
  "session_id": "ses_abc123",
  "run_id": "run_abc123",
  "status": "streaming",
  "started_at": "2026-05-19T10:30:00Z",
  "updated_at": "2026-05-19T10:30:06Z",
  "content": "Partial visible response text so far"
}

La risposta può anche includere indicazioni sui progressi recenti mentre l'Esecuzione è attiva.

Errori

Crediti

Ottieni saldo

GET /credits/balance

Restituisce il Suo saldo Crediti attuale.

Risposta 200 OK

{
  "balance": "123.45"
}

Agenti

Crei e modifichi Agenti personalizzati nel Pannello di controllo. Il supporto API per la creazione e la modifica degli Agenti sarà disponibile a breve.

I flussi di lavoro pianificati/in background non sono attualmente supportati tramite l'API. Il supporto sarà disponibile a breve.

Elenca Agenti

GET /agents

Restituisce gli agenti disponibili per la Sua chiave API. Utilizzi il valore agent quando crea Sessioni o invia messaggi.

Risposta 200 OK

{
  "agents": [
    {
      "agent": "jenova",
      "display_name": "Jenova",
      "description": "General-purpose Jenova agent"
    },
    {
      "agent": "my-support-agent",
      "display_name": "Support Agent",
      "description": "Answers customer questions"
    }
  ]
}

Modelli

Elenca Modelli

GET /models

Restituisce tutti i modelli disponibili per l'uso nel campo model durante l'invio dei Messaggi.

Risposta 200 OK

{
  "models": [
    {
      "id": "claude-opus-4-8",
      "name": "Claude Opus 4.8",
      "thinking_variant": "claude-opus-4-8-thinking"
    },
    {
      "id": "claude-opus-4-8-thinking",
      "name": "Claude Opus 4.8 (Thinking)"
    },
    {
      "id": "kimi-k2.6",
      "name": "Kimi K2.6",
      "thinking_variant": "kimi-k2.6-thinking"
    }
  ]
}

I Modelli con un thinking_variant supportano il ragionamento estesa. Utilizzi l'ID della variante direttamente nel campo model per attivarla.

Se non viene specificato alcun model durante l'invio di un Messaggio, viene utilizzato il Modello predefinito dell'Agente.

Documentazione

GET /docs?lang=en
GET /doc?lang=en

Restituisce questo riferimento in formato Markdown. Utilizzi lang per selezionare la lingua.

Streaming (SSE)

Quando stream viene omesso o impostato su true (valore predefinito), le risposte ai Messaggi vengono fornite come Server-Sent Events. Utilizzi gli Eventi message_completed per identificare i Messaggi pronti da recuperare o visualizzare.

Timeout: le connessioni SSE restano aperte per un massimo di 60 minuti. Le richieste non in Streaming attendono fino a 90 secondi, poi restituiscono 202 Accepted mentre l'Esecuzione continua.

Header di connessione

La risposta SSE imposta questi header:

Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive
X-Accel-Buffering: no
X-Run-Id: run_abc123

X-Run-Id è disponibile prima del primo Evento SSE.

Riconnessione e ripristino

I flussi SSE non vengono riproposti. Se la connessione si interrompe, utilizzi il session_id e il run_id acquisiti per ripristinare lo stato:

curl "https://api.jenova.ai/v1/sessions/ses_abc123/runs/run_abc123" \
  -H "Authorization: Bearer jnv_sk_xxx"

Se l'Esecuzione è ancora attiva, questo restituisce lo stato attuale, il testo parziale e i progressi recenti. Se restituisce 404 not_found, l'Esecuzione non è più attiva; recuperi i messaggi della Sessione per riconciliare l'output completato:

curl "https://api.jenova.ai/v1/sessions/ses_abc123/messages?limit=20" \
  -H "Authorization: Bearer jnv_sk_xxx"

Formato del frame

Ogni frame SSE segue il formato standard:

event: <event_type>
data: <json_payload>

Due caratteri di nuova riga terminano ogni frame.

Tipi di Evento

Gli stream includono eventi di ciclo di vita, delta di testo, pensiero, avanzamento, avviso, completamento messaggio, connessione MCP, errore, finale e ping. Alcuni tipi di evento vengono inviati solo quando pertinenti.

Per le richieste effimere (ephemeral: true), ogni Evento SSE omette session_id. Utilizzi run_id solo per correlare gli Eventi all'interno di quel singolo stream.

Per la riconciliazione finale sulle richieste persistenti, attenda stream_ended, quindi chiami List Messages.

Campi comuni sugli Eventi con ambito Esecuzione:

stream_started

Inviato una volta all'avvio dell'Esecuzione.

stream_delta

Inviato ripetutamente mentre l'Agente genera testo di risposta visibile. Concateni i valori di chunk_content nell'ordine di seq per costruire la risposta in streaming.

event: stream_delta
data: {"session_id":"ses_abc123","run_id":"run_abc123","chunk_content":"To reset your ","seq":1}

stream_thinking

Inviato ripetutamente mentre l'Agente emette output di thinking. Utilizzi questo Evento per un indicatore di thinking separato o una visualizzazione di traccia; non lo concateni nel testo di risposta finale.

stream_progress

Segnala attività visibili all’utente durante la generazione, come la lettura di un documento, la ricerca sul web o l’attesa di un’azione dell’utente. Questi eventi sono pensati per una visualizzazione temporanea nell’interfaccia; ignori i campi sconosciuti. Usi i messaggi completati come cronologia dei messaggi autorevole.

Avanzato: le richieste di Messaggio accettano include_progress: false per omettere solo stream_progress. Gli Eventi di ciclo di vita, ping, message_completed, gli errori e gli Eventi terminali vengono comunque inviati quando pertinenti.

Alcuni Eventi di avanzamento possono includere url, file_name o server_name come suggerimenti facoltativi per la visualizzazione.

message_completed

Inviato ogni volta che un Messaggio è completo e pronto per essere recuperato o visualizzato.

Questo è un marcatore di confine, non l'oggetto Messaggio completo. Recuperi il Messaggio se ha bisogno del contenuto o dei metadati.

event: message_completed
data: {"session_id":"ses_abc123","run_id":"run_abc123","message_id":"msg_abc123","sequence":4,"from":{"type":"agent","name":"Jenova"},"type":"external"}

mcp_connection

Inviato quando l’agente ha bisogno che l’utente finale connetta o autorizzi uno o più server MCP prima di poter continuare. Questo evento è disponibile solo in modalità streaming.

mcp_connection_resolved

Inviato quando l’azione utente di connessione MCP è stata risolta o è scaduta.

Nessun campo aggiuntivo oltre ai campi comuni con ambito Esecuzione.

warning

Inviato per avvisi non fatali durante un'Esecuzione.

stream_error

Inviato quando un'Esecuzione fallisce. Potrebbe seguire un Evento finale stream_ended con success:false e stop_reason:"error".

stream_ended

Inviato una volta quando l'esecuzione termina. Questo è l'evento finale dello stream.

event: stream_ended
data: {"session_id":"ses_abc123","run_id":"run_abc123","success":true,"stop_reason":"end_run","usage":{"cost":"0.0032"}}

Esempio di fallimento:

event: stream_ended
data: {"session_id":"ses_abc123","run_id":"run_abc123","success":false,"stop_reason":"user_cancelled","usage":{"cost":"0.0012"}}

ping

Frame di keepalive inviati ogni 15 secondi per evitare timeout di proxy/CDN. Ignorarli nel client.

Integrazione server MCP

Colleghi i Suoi Agenti a strumenti esterni tramite il Model Context Protocol (MCP):

• Server MCP gestiti da Jenova: server ospitati da Jenova per ricerca, recupero di contenuti, generazione di documenti e altre funzionalità integrate
• Server MCP remoti: altri server MCP remoti configurati per il Suo Agente

I server MCP devono essere configurati nel Pannello di controllo durante la creazione o la modifica del Suo Agente. Per utilizzare un proprio server MCP, lo aggiunga a un Agente personalizzato, quindi chiami tale Agente tramite l'API. L'API esegue gli Strumenti abilitati nella configurazione dell'Agente; non è richiesta alcuna configurazione aggiuntiva nelle richieste API.

Quando un Agente utilizza Strumenti MCP durante una risposta, gli Eventi di progresso vengono inviati nello stream nel momento in cui si verificano:

event: stream_progress
data: {"session_id":"ses_...","run_id":"run_...","state":"running","label":"Searching Google"}

Se l’agente richiede che l’utente finale connetta o autorizzi un server MCP durante l’esecuzione, le risposte in streaming possono includere gli eventi mcp_connection e mcp_connection_resolved. Presenti l’elenco dei server da connettere al suo utente finale e apra l’auth_url fornito, quando presente. Mantenga aperto lo stream SSE mentre l’utente connette o autorizza il server.

Dopo l'autorizzazione, Jenova memorizza il token, la finestra di autorizzazione mostra una pagina di completamento e la stessa Esecuzione continua automaticamente. Non è necessario che l'Utente finale rinvii il Messaggio.

Se l’utente finale non connette, autorizza, salta o silenzia prima di user_action_deadline_unix, l’esecuzione termina con stop_reason:"user_action_timeout". È inoltre possibile annullare l’esecuzione attiva con POST /sessions/{session_id}/cancel.

Memorizzi l’auth_url lato client. Se il client si disconnette durante l’autorizzazione, l’URL rimane valido fino a user_action_deadline_unix. Per le richieste persistenti, si riconnetta con Get Run Status oppure recuperi i messaggi dopo il termine dell’esecuzione.

Le richieste non in streaming (stream: false) non supportano azioni utente di connessione MCP; usi lo streaming per agenti che potrebbero richiedere questa interazione.

Saltare la connessione MCP

POST /sessions/{session_id}/mcp/connection/skip

Ignora un’azione utente di connessione MCP in sospeso e consente all’esecuzione di continuare senza quella connessione.

Per silenziare le future richieste di connessione per un server per lo stesso utente API, includa mcp_server_id e mute. I valori supportati sono 24h e forever.

Corpo della richiesta

Risposta 204 No Content

Lo stream emette mcp_connection_resolved, quindi l’esecuzione continua con lo stesso run_id.

Errori

Fatturazione

Tutti i costi vengono detratti dal Suo saldo di Crediti sviluppatore. Consulti l'Utilizzo e ricarichi i Crediti su www.jenova.ai/platform.

Prezzi

Il costo del Messaggio dipende da:

• Modello - Modelli diversi hanno costi per token diversi
• Lunghezza del contesto - Sessioni più lunghe consumano più token di input per richiesta
• Complessità del workflow - workflow più lunghi e un uso più intenso degli Strumenti (ricerca web, generazione di file, analisi di documenti) aumentano il consumo totale di token

Il costo effettivo viene restituito come stream_ended.usage.cost per le richieste in Streaming e come usage.cost per le richieste JSON non in Streaming.

Blocchi crediti

Ogni nuova Esecuzione di Messaggio applica un blocco di $0,50 sul Suo saldo Crediti prima dell'inizio dell'esecuzione. Questo riserva i fondi per l'Esecuzione. I Messaggi di follow-up in coda in un'Esecuzione attiva non creano blocchi aggiuntivi; l'Utilizzo dell'Esecuzione attiva viene verificato rispetto al Suo saldo residuo.

Al termine dell'Esecuzione, il blocco viene liquidato in base al costo effettivo e la differenza viene rilasciata. Le Esecuzioni annullate o non riuscite vengono addebitate solo per l'Utilizzo già maturato. Se una richiesta fallisce prima di raggiungere il Modello, il blocco completo viene rilasciato.

Ciò significa che il Suo saldo disponibile potrebbe apparire temporaneamente inferiore durante le richieste in corso. È necessario disporre di almeno $0,50 di saldo disponibile per inviare un Messaggio a una Sessione esistente o per inviare un Messaggio effimero. Una prima richiesta POST /messages persistente crea una Sessione e richiede almeno $0,51 per coprire il blocco del Messaggio più la commissione di creazione della Sessione.

Limiti di frequenza

Ogni account sviluppatore è soggetto a tre dimensioni di Limite di frequenza:

Le richieste GET e HEAD non consumano slot concorrenti. cancel, undo e mcp/connection/skip non consumano slot concorrenti, quindi queste operazioni rimangono disponibili quando tutti gli slot sono in uso. Queste richieste continuano comunque a conteggiare per RPM e RPD.

Header di risposta

Le risposte API autenticate includono header relativi al limite di frequenza:

Quando un limite viene superato, l'API restituisce 429 Too Many Requests:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please retry after 12 seconds."
  }
}

Gestione degli errori

Gli errori HTTP immediati e gli errori di esecuzione non in streaming seguono una struttura coerente:

{
  "error": {
    "code": "error_code_string",
    "message": "Human-readable description"
  }
}

I messaggi di errore sono localizzati in base al parametro lang (vedere Localizzazione).

Gli errori di Esecuzione in streaming vengono trasmessi come Eventi stream_error. Un'Esecuzione non riuscita può comunque inviare un Evento finale stream_ended con success:false e stop_reason impostato. Gli errori di Esecuzione non in streaming possono anche includere un oggetto usage di primo livello quando sono disponibili dati sui costi.

Gli errori specifici di ciascun endpoint sono documentati direttamente nella relativa sezione.

Errori di Esecuzione dopo l'avvio

Gli errori di Esecuzione emergono dopo che l'esecuzione di un Messaggio è già iniziata. In modalità streaming, appaiono come Eventi stream_error e possono essere seguiti da stream_ended con success:false. In modalità non streaming, vengono restituiti come risposta di errore JSON con il codice di stato HTTP indicato di seguito.

Paginazione

Gli endpoint di elenco utilizzano la paginazione basata su cursore:

{
  "items": [],
  "next_cursor": "eyJ2IjoxLCJrIjoiY3VyXzAyIn0",
  "has_more": true
}

Passi next_cursor come parametro di query cursor per recuperare la pagina successiva. Quando has_more è false, non ci sono ulteriori risultati.

Localizzazione

Tutti gli endpoint accettano un parametro di query facoltativo lang per controllare la lingua dei messaggi di errore e di qualsiasi contenuto localizzato.

Può aggiungere ?lang=xx a qualsiasi URL di richiesta:

POST /sessions?lang=zh
GET /sessions/ses_abc123/messages?lang=ja

Lingue supportate: en, zh, ja, ko, es, fr, de, it, pt, ru, id, th, vi

Privacy e dati

Jenova non utilizza i prompt API, gli output, la cronologia delle conversazioni, i file caricati, le istruzioni degli Agenti o le Basi di conoscenza per addestrare i modelli Jenova.

Per quanto riguarda i provider di Modelli terzi, Jenova utilizza canali API commerciali, impostazioni dell'account, impegni contrattuali o meccanismi di opt-out volti a impedire che i contenuti dei clienti vengano utilizzati per addestrare i Modelli dei provider.

Jenova archivia ed elabora i dati API utilizzando infrastrutture statunitensi. I provider terzi possono elaborare i dati in altre giurisdizioni, come descritto nell'Informativa sulla privacy e nei Termini di utilizzo.

Per maggiori dettagli, consulti i Termini di utilizzo, l'Informativa sulla privacy e la Politica di utilizzo.

Supporto

• Pannello di controllo: www.jenova.ai/platform
• Email: [email protected]