Endpoint: Agenti, Chat e Conversazioni

Riferimento degli endpoint per la gestione degli agenti conversazionali, l'invio di messaggi (sincrono o in streaming), lo storico delle conversazioni, i server MCP associabili agli agenti, le valutazioni e i template di prompt riutilizzabili.

Tutte le richieste utilizzano l'URL base https://ai.askme.it/api/v2 e gli header descritti in Autenticazione (X-Api-Key, X-Source-App, X-External-Id opzionale). Le liste seguono la paginazione offset/limit descritta in Panoramica.

1. Agenti

Gestione degli agenti AI: configurazione, knowledge base associate, server MCP, prompt, modelli e politiche RAG.

`POST /agents`

Crea un nuovo agente nel tenant.

Attributi richiesta

Campo	In	Tipo	Obbligatorio	Default	Descrizione
`name`	body	string (1–255)	Sì	—	Nome visualizzato dell'agente.
`description`	body	string	No	—	Descrizione libera.
`model_provider`	body	string	No	`openai`	Provider del modello. Valori: `openai`, `anthropic`, `google`, `mistral`, `ollama`, `local`.
`model_name`	body	string (max 100)	No	`gpt-4o-mini`	Nome del modello da usare (es. `gpt-4o`, `claude-sonnet-4-5-20250929`).
`system_prompt`	body	string	No	—	Prompt di sistema dell'agente. Supporta variabili `{{nome_var}}`.
`temperature`	body	float (0.0–2.0)	No	`0.7`	Temperatura di campionamento.
`max_tokens`	body	int (1–128000)	No	`2048`	Token massimi nella risposta.
`reasoning_effort`	body	string	No	—	Solo per modelli con reasoning. Valori: `minimal`, `low`, `medium`, `high`.
`tools_config`	body	object	No	—	Configurazione tool (function calling, structured output).
`rag_config`	body	object	No	—	Configurazione RAG. Campi: `enabled`, `knowledge_base_ids` (array di id KB, come stringhe), `top_k`, `score_threshold`, `rerank_enabled`, `hybrid_search`, `hybrid_alpha`, `query_rewrite_enabled`, `query_rewrite_mode` (`none`/`simple`/`multi`), `rewrite_instructions`, `crag_enabled`, `crag_max_loops`, `crag_quality_threshold`, `no_context_message`. Chiavi non riconosciute vengono memorizzate ma ignorate: un nome errato non produce errore, l'agente usa il valore di default.
`handoff_config`	body	object	No	—	Configurazione del passaggio a operatore umano (regole di confidenza, intent).
`output_schema`	body	object (JSON Schema)	No	—	Schema JSON forzato sulla risposta del modello (structured output).
`mcp_server_ids`	body	int[]	No	`null`	ID dei server MCP da associare. `null` o omesso = nessuna associazione; `[]` = svuota.
`parent_id`	body	int	No	—	Agente genitore: il prompt di sistema effettivo è la concatenazione lungo la catena (max 10 livelli).
`is_temporary`	body	bool	No	`false`	Se `true`, l'agente è nascosto dalle liste standard.

Esempio richiesta

curl -X POST "https://ai.askme.it/api/v2/agents" \
  -H "X-Api-Key: amai_xxxxxxxxxxxxxxxx" \
  -H "X-Source-App: api_direct" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Assistente customer care",
    "description": "Risponde alle domande dei clienti su spedizioni e resi.",
    "model_provider": "openai",
    "model_name": "gpt-4o-mini",
    "system_prompt": "Sei un assistente cortese di supporto clienti.",
    "temperature": 0.4,
    "max_tokens": 1024,
    "mcp_server_ids": [12]
  }'

Esempio risposta (201 Created)

{
  "id": 87,
  "tenant_id": "acme",
  "name": "Assistente customer care",
  "description": "Risponde alle domande dei clienti su spedizioni e resi.",
  "model_provider": "openai",
  "model_name": "gpt-4o-mini",
  "system_prompt": "Sei un assistente cortese di supporto clienti.",
  "temperature": 0.4,
  "max_tokens": 1024,
  "tools_config": null,
  "rag_config": null,
  "handoff_config": null,
  "reasoning_effort": null,
  "mcp_server_ids": [12],
  "parent_id": null,
  "is_temporary": false,
  "output_schema": null,
  "status": "draft",
  "version": 1,
  "created_by": "user-uuid",
  "created_at": "2026-04-30T09:12:33Z",
  "updated_at": "2026-04-30T09:12:33Z"
}

Errori specifici

Codice	Significato
`400`	Nome vuoto, valore di `model_provider` non ammesso, oppure `mcp_server_ids` contiene ID non appartenenti al tenant.
`429`	Quota `agents` esaurita per il piano corrente.

`GET /agents`

Elenca gli agenti del tenant in modo paginato.

Attributi richiesta

Campo	In	Tipo	Obbligatorio	Default	Descrizione
`offset`	query	int (≥0)	No	`0`	Offset di paginazione.
`limit`	query	int (1–100)	No	`50`	Numero massimo di elementi.
`search`	query	string	No	—	Ricerca testuale su nome e descrizione.
`status`	query	string	No	—	Filtro stato. Valori: `draft`, `active`, `paused`, `archived`.
`model_name`	query	string	No	—	Filtro per modello esatto.
`include_temporary`	query	bool	No	`false`	Include agenti temporanei (creati da analisi PDF chat-with-doc).
`sort_by`	query	string	No	—	Campo di ordinamento (`name`, `created_at`, `updated_at`).
`order`	query	string	No	`desc`	Direzione: `asc` o `desc`.

Esempio richiesta

curl -G "https://ai.askme.it/api/v2/agents" \
  -H "X-Api-Key: amai_xxxxxxxxxxxxxxxx" \
  -H "X-Source-App: api_direct" \
  --data-urlencode "limit=20" \
  --data-urlencode "status=active"

Esempio risposta (200 OK)

{
  "items": [
    {
      "id": 87,
      "tenant_id": "acme",
      "name": "Assistente customer care",
      "model_provider": "openai",
      "model_name": "gpt-4o-mini",
      "status": "active",
      "version": 3,
      "mcp_server_ids": [12],
      "created_at": "2026-04-30T09:12:33Z",
      "updated_at": "2026-04-30T11:02:00Z"
    }
  ],
  "total": 1,
  "offset": 0,
  "limit": 20
}

`GET /agents/{agent_id}`

Recupera un agente specifico.

Attributi richiesta

Campo	In	Tipo	Obbligatorio	Descrizione
`agent_id`	path	int	Sì	Identificativo dell'agente.

Esempio richiesta

curl "https://ai.askme.it/api/v2/agents/87" \
  -H "X-Api-Key: amai_xxxxxxxxxxxxxxxx" \
  -H "X-Source-App: api_direct"

Esempio risposta (200 OK): stesso schema di POST /agents.

Errori specifici

Codice	Significato
`404`	Agente non trovato o appartenente ad altro tenant.

`PUT /agents/{agent_id}`

Aggiorna l'agente. Tutti i campi del body sono opzionali; solo i campi forniti vengono modificati. La modifica incrementa version e crea uno snapshot.

Attributi richiesta

Stessi campi di POST /agents, tutti opzionali. In più:

Campo	In	Tipo	Descrizione
`status`	body	string	Stato dell'agente. Valori: `draft`, `active`, `paused`, `archived`.
`mcp_server_ids`	body	int[] \| null	`null` = mantiene attuali; `[]` = rimuove tutte; `[n,m]` = sostituisce esattamente con questi (semantica idempotente: il backend calcola il diff e applica add/remove).

Esempio richiesta

curl -X PUT "https://ai.askme.it/api/v2/agents/87" \
  -H "X-Api-Key: amai_xxxxxxxxxxxxxxxx" \
  -H "X-Source-App: api_direct" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "active",
    "temperature": 0.2,
    "mcp_server_ids": [12, 15]
  }'

`DELETE /agents/{agent_id}`

Elimina l'agente. La quota agents viene rilasciata. Risposta 204 No Content.

`POST /agents/{agent_id}/rollback/{version_number}`

Riporta la configurazione dell'agente a una versione precedente. Crea automaticamente una nuova entry di versione con changelog "Rollback to version N".

Attributi richiesta

Campo	In	Tipo	Obbligatorio	Descrizione
`agent_id`	path	int	Sì	Agente target.
`version_number`	path	int	Sì	Numero di versione da ripristinare.

Errori specifici

Codice	Significato
`404`	Versione inesistente per l'agente.

`GET /agents/{agent_id}/versions`

Elenca le versioni archiviate della configurazione dell'agente.

Associazioni MCP per agente

Oltre al campo mcp_server_ids nei POST/PUT /agents, sono disponibili endpoint dedicati per gestire singole associazioni:

POST /agents/{agent_id}/mcp-servers — body { "mcp_server_id": 12 }. Risponde 201 o 409 se già associato.
GET /agents/{agent_id}/mcp-servers — elenco completo dei server associati con il dettaglio.
DELETE /agents/{agent_id}/mcp-servers/{mcp_server_id} — rimuove l'associazione (204 o 404).

2. Chat

Endpoint principale per inviare un messaggio a un agente o a un modello LLM diretto. Supporta streaming Server-Sent Events.

`POST /chat`

Invia un messaggio. Due modalità:

Modalità agente: passa agent_id. Modello, system prompt, RAG e MCP vengono dedotti dalla configurazione dell'agente.
Modalità diretta: ometti agent_id e fornisci model + system_prompt espliciti.

Attributi richiesta

Campo	In	Tipo	Obbligatorio	Default	Descrizione
`message`	body	string (1–32000)	Sì	—	Testo del messaggio utente.
`agent_id`	body	int \| null	No*	`null`	ID dell'agente. *Se omesso, sono richiesti `model` e `system_prompt`.
`conversation_id`	body	int	No	—	Conversazione esistente; se assente ne viene creata una nuova.
`external_conversation_id`	body	string	No	—	ID conversazione del sistema chiamante (alternativa a `conversation_id`).
`stream`	body	bool	No	`false`	Se `true` la risposta è uno stream SSE.
`model`	body	string	No*	—	Solo modalità diretta (es. `gpt-4o-mini`).
`system_prompt`	body	string	No*	—	Solo modalità diretta.
`temperature`	body	float	No	(default agente)	Override della temperatura.
`max_tokens`	body	int	No	(default agente)	Override del limite token.
`files`	body	array	No	—	Allegati: `[{ filename, content_type, data }]` con `data` base64.
`include_sources`	body	bool	No	`true`	Se `true` la risposta include `rag_sources`.
`include_hidden_sources`	body	bool	No	`false`	Se `true` include anche fonti con `is_visible=false` (usate ma normalmente non citate).
`template_vars`	body	object (string→string)	No	—	Variabili sostituite nel system prompt (es. `{{nome_cliente}}`).
`classification_intents`	body	array	No	—	Intent custom per la classificazione: `[{ name, description }]`.
`force_handoff`	body	bool	No	`false`	Forza il passaggio a operatore umano.
`skip_handoff`	body	bool	No	`false`	Disabilita la valutazione handoff per questo messaggio.
`skip_scope_check`	body	bool	No	`false`	Disabilita il controllo "fuori scope" per questo messaggio.
`response_format`	body	string	No	`markdown`	`markdown` o `html`.
`llm_response_format`	body	object	No	—	Schema JSON per structured output one-shot.
`metadata`	body	object	No	—	Metadati liberi propagati nel record di costo.
`mcp_auth`	body	object (string→string)	No	—	Token utente per MCP che richiedono auth (passati come header per quel MCP).
`tool_approval`	body	object	No	—	Risposta a un'approvazione di tool: `{ approved: bool, pending_message_id: int }`.
`external_id`	body	string (max 255)	No	—	Override dell'header `X-External-Id` a livello di richiesta.
`source_app`	body	string (max 50)	No	—	Override dell'header `X-Source-App` a livello di richiesta.
`X-External-Id`	header	string	No	—	ID esterno per il record di costo e attribuzione.

Esempio richiesta (non-streaming, cURL)

curl -X POST "https://ai.askme.it/api/v2/chat" \
  -H "X-Api-Key: amai_xxxxxxxxxxxxxxxx" \
  -H "X-Source-App: api_direct" \
  -H "X-External-Id: ordine-7728" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": 87,
    "message": "Quali sono i tempi medi di consegna in Italia?",
    "stream": false
  }'

Esempio richiesta (Python, httpx)

import os
import httpx

client = httpx.Client(
    base_url=os.environ["ASKMEAI_HOST"] + "/api/v2",
    headers={
        "X-Api-Key": os.environ["ASKMEAI_API_KEY"],
        "X-Source-App": os.environ.get("ASKMEAI_SOURCE_APP", "api_direct"),
    },
    timeout=30.0,
)

resp = client.post("/chat", json={
    "agent_id": 12,
    "message": "Quali sono i tempi medi di consegna?",
    "stream": False,
}, headers={"X-External-Id": "ticket-9281"})
resp.raise_for_status()
data = resp.json()
print(data["message"]["content"])

Esempio risposta (200 OK, non-streaming)

{
  "message_id": 5512,
  "conversation_id": 4421,
  "external_conversation_id": null,
  "content": "I tempi medi di consegna in Italia sono compresi tra 24 e 72 ore lavorative ...",
  "thinking_content": null,
  "content_format": "markdown",
  "role": "assistant",
  "model_used": "gpt-4o-mini",
  "tokens_input": 412,
  "tokens_output": 88,
  "latency_ms": 1430,
  "rag_sources": [
    {
      "document_id": "117",
      "chunk_id": "chunk-117-3",
      "title": "Politica spedizioni",
      "content_preview": "Le spedizioni standard partono entro 24 ore lavorative ...",
      "relevance_score": 0.83,
      "metadata": { "page": 2 },
      "is_visible": true
    }
  ],
  "confidence_score": 0.91,
  "needs_review": false,
  "handoff_requested": false,
  "handoff_reason": null,
  "intent": "delivery_info",
  "sentiment": "neutral",
  "is_in_scope": true,
  "tool_calls_count": 0,
  "tools_used": [],
  "pending_tool_approval": false,
  "created_at": "2026-04-30T11:22:14Z"
}

Risposta in streaming (SSE)

Quando stream: true, il server risponde con Content-Type: text/event-stream. Ogni evento ha la forma:

data: {"type": "...", ...}\n\n

Tipi di evento emessi (campo type):

Tipo	Descrizione	Campi principali
`rag_thinking`	Status testuale durante la fase RAG (es. "ricerca documenti…").	`content`
`thinking`	Token del ragionamento interno (per modelli con reasoning).	`content`
`delta` / `content`	Token incrementale della risposta.	`content`
`sources`	Lista delle fonti RAG individuate.	`sources[]`
`tool_call`	Il modello sta invocando un tool MCP.	`tool_name`, `tool_args`
`tool_approval_required`	Tool che richiede approvazione esplicita.	`pending_tool_calls[]`, `pending_message_id`
`confidence`	Confidence score consolidato.	`confidence_score`, `confidence_signals`, `needs_review`
`handoff_decision`	Decisione di handoff verso operatore umano.	`handoff_requested`, `handoff_reason`, `handoff_trigger`
`usage`	Bilancio finale token + metadati turn.	`usage.{message_id,conversation_id,model_used,tokens_input,tokens_output,latency_ms,…}`
`done`	Marker di fine stream.	—
`error`	Errore in corso di stream.	`error`, `code`

Esempio di stream (estratto):

data: {"type":"rag_thinking","content":"Cerco nelle fonti..."}

data: {"type":"sources","sources":[{"document_id":"117","relevance_score":0.83,...}]}

data: {"type":"delta","content":"I tempi"}

data: {"type":"delta","content":" medi di consegna"}

data: {"type":"confidence","confidence_score":0.91,"needs_review":false}

data: {"type":"usage","usage":{"message_id":5512,"conversation_id":4421,"model_used":"gpt-4o-mini","tokens_input":412,"tokens_output":88,"latency_ms":1430}}

data: {"type":"done"}

Esempio Python (httpx, consumo dello stream)

import json, os, httpx

with httpx.stream(
    "POST",
    os.environ["ASKMEAI_HOST"] + "/api/v2/chat",
    headers={
        "X-Api-Key": os.environ["ASKMEAI_API_KEY"],
        "X-Source-App": "api_direct",
        "Content-Type": "application/json",
        "Accept": "text/event-stream",
    },
    json={"agent_id": 12, "message": "Riassumi la policy resi", "stream": True},
    timeout=None,
) as resp:
    resp.raise_for_status()
    for raw in resp.iter_lines():
        if not raw or not raw.startswith("data: "):
            continue
        evt = json.loads(raw[6:])
        if evt.get("type") == "delta":
            print(evt["content"], end="", flush=True)
        elif evt.get("type") == "done":
            print()
            break

Errori specifici

Codice	Significato
`400`	`agent_id` mancante senza `model`/`system_prompt`; `message` vuoto o oltre 32000 caratteri.
`404`	Agente o conversazione non trovati.
`429`	Quota messaggi del piano esaurita.

3. Conversazioni

Storico, lookup tramite ID esterno, feedback sui messaggi.

`GET /conversations`

Elenca le conversazioni dell'utente corrente.

Attributi richiesta

Campo	In	Tipo	Default	Descrizione
`offset`	query	int	`0`	Paginazione.
`limit`	query	int (1–100)	`50`	Page size.

Esempio risposta (200 OK)

{
  "items": [
    {
      "id": 4421,
      "tenant_id": "acme",
      "agent_id": 87,
      "agent_name": "Assistente customer care",
      "user_id": "user-uuid",
      "title": "Domanda spedizioni",
      "status": "active",
      "message_count": 6,
      "external_id": "ordine-7728",
      "created_at": "2026-04-30T11:20:00Z",
      "updated_at": "2026-04-30T11:24:10Z"
    }
  ],
  "total": 1,
  "offset": 0,
  "limit": 50
}

`GET /conversations/monitoring`

Vista monitoring: tutte le conversazioni del tenant (richiede permessi adeguati). Supporta filtri estesi.

Attributi richiesta

Campo	In	Tipo	Descrizione
`offset`, `limit`	query	int	Paginazione standard.
`status`	query	string	Filtra per stato (`active`, `closed`, `archived`).
`agent_id`	query	int	Filtra per agente.
`date_from`	query	datetime ISO 8601	Dalla data inclusa.
`date_to`	query	datetime ISO 8601	Fino alla data inclusa.

`GET /conversations/{conversation_id}`

Dettaglio di una conversazione (senza messaggi).

Esempio risposta (200 OK)

{
  "id": 4421,
  "tenant_id": "acme",
  "agent_id": 87,
  "user_id": "user-uuid",
  "title": "Domanda spedizioni",
  "status": "active",
  "metadata": null,
  "external_id": "ordine-7728",
  "insights": null,
  "created_at": "2026-04-30T11:20:00Z",
  "updated_at": "2026-04-30T11:24:10Z"
}

`GET /conversations/by-external-id/{external_id}`

Recupera la conversazione tramite l'ID esterno fornito al primo POST /chat. Utile per riprendere una sessione lato backend chiamante senza dover mantenere traccia dei conversation_id interni.

Attributi richiesta

Campo	In	Tipo	Descrizione
`external_id`	path	string	ID opaco fornito alla creazione.
`agent_id`	query	int	(opzionale) limita la ricerca a un singolo agente, utile se lo stesso `external_id` è stato usato con più agenti.

Esempio richiesta

curl "https://ai.askme.it/api/v2/conversations/by-external-id/ordine-7728" \
  -H "X-Api-Key: amai_xxxxxxxxxxxxxxxx" \
  -H "X-Source-App: api_direct"

Per agganciare i messaggi successivi alla stessa conversazione, va passato conversation_id nel body del POST /chat.

Errori specifici

Codice	Significato
`404`	Nessuna conversazione corrisponde all'`external_id` per il tenant.

`GET /conversations/{conversation_id}/messages`

Recupera i messaggi della conversazione.

Attributi richiesta

Campo	In	Tipo	Default	Descrizione
`conversation_id`	path	int	—	Conversazione target.
`offset`	query	int	`0`	Paginazione.
`limit`	query	int (1–500)	`100`	Page size.

Esempio risposta (200 OK)

{
  "items": [
    {
      "id": 5511,
      "conversation_id": 4421,
      "role": "user",
      "content": "Quali sono i tempi medi di consegna in Italia?",
      "created_at": "2026-04-30T11:22:00Z"
    },
    {
      "id": 5512,
      "conversation_id": 4421,
      "role": "assistant",
      "content": "I tempi medi di consegna ...",
      "tokens_input": 412,
      "tokens_output": 88,
      "model_used": "gpt-4o-mini",
      "created_at": "2026-04-30T11:22:14Z"
    }
  ],
  "total": 2,
  "offset": 0,
  "limit": 100
}

`PUT /conversations/{conversation_id}`

Aggiorna titolo o stato della conversazione (anche PATCH).

Attributi richiesta

Campo	In	Tipo	Descrizione
`title`	body	string (max 500)	Nuovo titolo.
`status`	body	string	`active`, `closed` o `archived`.

`DELETE /conversations/{conversation_id}`

Elimina la conversazione e tutti i messaggi. Risposta 204 No Content.

`POST /conversations/{conversation_id}/messages/{message_id}/feedback`

Registra il feedback dell'utente finale su una risposta dell'assistente.

Attributi richiesta

Campo	In	Tipo	Obbligatorio	Descrizione
`rating`	body	string	Sì	`positive` o `negative`.
`comment`	body	string	No	Commento testuale.

Esempio risposta (200 OK)

{ "message_id": 5512, "rating": "positive", "comment": "Risposta chiara." }

4. Server MCP

Server MCP (Model Context Protocol) registrati a livello tenant e associabili agli agenti.

`POST /mcp-servers`

Registra un nuovo server MCP.

Attributi richiesta

Campo	In	Tipo	Obbligatorio	Descrizione
`name`	body	string (1–255)	Sì	Nome visualizzato.
`description`	body	string	No	Descrizione libera.
`transport`	body	string	Sì	Trasporto. Valori: `stdio`, `sse`, `streamable-http`.
`command`	body	string (max 500)	Solo per `stdio`	Comando eseguibile.
`args`	body	string[]	No	Argomenti del comando.
`url`	body	string (max 500)	Solo per `sse`/`streamable-http`	URL del server.
`env`	body	object (string→string)	No	Variabili ambiente (per `stdio`) o header custom.

Esempio richiesta

curl -X POST "https://ai.askme.it/api/v2/mcp-servers" \
  -H "X-Api-Key: amai_xxxxxxxxxxxxxxxx" \
  -H "X-Source-App: api_direct" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Calendar MCP",
    "description": "Server MCP per gestione calendario",
    "transport": "streamable-http",
    "url": "https://mcp.example.com/calendar",
    "env": { "Authorization": "Bearer ..." }
  }'

Esempio risposta (201 Created)

{
  "id": 12,
  "tenant_id": "acme",
  "name": "Calendar MCP",
  "description": "Server MCP per gestione calendario",
  "transport": "streamable-http",
  "command": null,
  "args": null,
  "url": "https://mcp.example.com/calendar",
  "env": { "Authorization": "Bearer ..." },
  "status": "unknown",
  "tools_count": 0,
  "tools_cache": null,
  "last_health_check": null,
  "created_at": "2026-04-30T10:50:00Z",
  "updated_at": "2026-04-30T10:50:00Z"
}

Errori specifici

Codice	Significato
`400`	Validazione fallita (es. `transport=sse` senza `url`, `transport=stdio` senza `command`).

`GET /mcp-servers`

Elenca i server MCP del tenant. Filtri: search, status, transport, oltre a offset/limit.

`GET /mcp-servers/{server_id}`

Dettaglio e cache dei tool.

`PATCH /mcp-servers/{server_id}`

Aggiorna il server (campi opzionali). Stessi vincoli di trasporto.

`DELETE /mcp-servers/{server_id}`

Elimina il server (204).

`GET /mcp-servers/{server_id}/tools`

Restituisce i tool esposti dal server, con relativo input_schema (JSON Schema).

`POST /mcp-servers/{server_id}/refresh-tools`

Forza il refresh della cache tool dal server. Restituisce conteggio e lista aggiornata.

`POST /mcp-servers/{server_id}/test`

Esegue un test di connessione live. Risposta { "success": bool, "message": string }.

Health

Lo stato status del server è cacheato in database. Le chiamate di health probano i server in tempo reale e persistono il risultato.

`GET /mcp-servers/health`

Stato cacheato di tutti i server (nessuna probe). Restituisce un array di McpServerResponse.

`POST /mcp-servers/health/refresh`

Probe live in parallelo di tutti i server e persiste i risultati.

`POST /mcp-servers/{server_id}/health/refresh`

Probe live di un singolo server.

5. Valutazioni e A/B Testing

note

Endpoint disponibili lato piattaforma; il riferimento sintetico seguente è derivato dall'inventario delle funzionalità e verrà esteso con parametri di dettaglio ed esempi in un aggiornamento successivo.

Endpoint	Metodo	Descrizione
`/evaluations/datasets`	GET, POST, PUT, DELETE	Gestione dei dataset di valutazione.
`/evaluations/run`	POST	Avvia l'esecuzione di una valutazione su un dataset.
`/evaluations/runs`	GET	Elenca le esecuzioni di valutazione.
`/ab-experiments`	GET, POST, PUT, DELETE	Gestione degli esperimenti A/B tra varianti di agente.
`/ab-experiments/{id}/run`	POST	Avvia un esperimento A/B.
`/ab-experiments/{id}/results`	GET	Risultati aggregati dell'esperimento.
`/ab-experiments/{id}/promote/{variant}`	POST	Promuove una variante a configurazione attiva.

6. Template Prompt

Template di prompt riutilizzabili e versionabili.

`POST /prompt-templates`

Crea un template.

Attributi richiesta

Campo	In	Tipo	Obbligatorio	Default	Descrizione
`name`	body	string (1–255)	Sì	—	Nome del template.
`content`	body	string	Sì	—	Testo del prompt; può contenere `{{variabile}}`.
`role`	body	string	No	`system`	Ruolo del messaggio (`system`, `user`, `assistant`).
`description`	body	string	No	—	Descrizione.
`variables`	body	array	No	`[]`	`[{ name, description, default_value }]`.
`parent_id`	body	int	No	—	Template genitore.
`tags`	body	string[]	No	`[]`	Tag liberi.
`status`	body	string	No	`draft`	`draft`, `published`, `archived`.

Esempio risposta (201 Created)

{
  "id": 55,
  "tenant_id": "acme",
  "name": "Saluto cliente",
  "description": "Apertura standard delle conversazioni di supporto",
  "content": "Buongiorno {{nome_cliente}}, sono l'assistente di {{azienda}}.",
  "role": "system",
  "variables": [
    { "name": "nome_cliente", "description": "Nome del cliente", "default_value": "" },
    { "name": "azienda", "description": "Nome azienda", "default_value": "Askme" }
  ],
  "parent_id": null,
  "tags": ["welcome", "support"],
  "status": "draft",
  "version": 1,
  "created_by": "user-uuid",
  "created_at": "2026-04-30T12:00:00Z",
  "updated_at": "2026-04-30T12:00:00Z"
}

`GET /prompt-templates`

Elenca i template.

Attributi richiesta

Campo	In	Tipo	Default	Descrizione
`parent_id`	query	int	—	Filtra per template genitore.
`status`	query	string	—	Filtro stato.
`search`	query	string	—	Ricerca testuale.
`root_only`	query	bool	`false`	Se `true` mostra solo i template senza genitore.
`offset`, `limit`	query	int	`0`, `50`	Paginazione (limit max 200).

`PUT /prompt-templates/{template_id}`

Aggiornamento (campi opzionali). Incrementa version.

`DELETE /prompt-templates/{template_id}`

Eliminazione (204).

1. Agenti​

POST /agents​

GET /agents​

GET /agents/{agent_id}​

PUT /agents/{agent_id}​

DELETE /agents/{agent_id}​

POST /agents/{agent_id}/rollback/{version_number}​

GET /agents/{agent_id}/versions​

Associazioni MCP per agente​

2. Chat​

POST /chat​

Risposta in streaming (SSE)​

3. Conversazioni​

GET /conversations​

GET /conversations/monitoring​

GET /conversations/{conversation_id}​

GET /conversations/by-external-id/{external_id}​

GET /conversations/{conversation_id}/messages​

PUT /conversations/{conversation_id}​

DELETE /conversations/{conversation_id}​

POST /conversations/{conversation_id}/messages/{message_id}/feedback​

4. Server MCP​

POST /mcp-servers​

GET /mcp-servers​

GET /mcp-servers/{server_id}​

PATCH /mcp-servers/{server_id}​

DELETE /mcp-servers/{server_id}​

GET /mcp-servers/{server_id}/tools​

POST /mcp-servers/{server_id}/refresh-tools​

POST /mcp-servers/{server_id}/test​

Health​

GET /mcp-servers/health​

POST /mcp-servers/health/refresh​

POST /mcp-servers/{server_id}/health/refresh​

5. Valutazioni e A/B Testing​

6. Template Prompt​

POST /prompt-templates​

GET /prompt-templates​

PUT /prompt-templates/{template_id}​

DELETE /prompt-templates/{template_id}​

Pagine correlate​

1. Agenti

`POST /agents`

`GET /agents`

`GET /agents/{agent_id}`

`PUT /agents/{agent_id}`

`DELETE /agents/{agent_id}`

`POST /agents/{agent_id}/rollback/{version_number}`

`GET /agents/{agent_id}/versions`

Associazioni MCP per agente

2. Chat

`POST /chat`

Risposta in streaming (SSE)

3. Conversazioni

`GET /conversations`

`GET /conversations/monitoring`

`GET /conversations/{conversation_id}`

`GET /conversations/by-external-id/{external_id}`

`GET /conversations/{conversation_id}/messages`

`PUT /conversations/{conversation_id}`

`DELETE /conversations/{conversation_id}`

`POST /conversations/{conversation_id}/messages/{message_id}/feedback`

4. Server MCP

`POST /mcp-servers`

`GET /mcp-servers`

`GET /mcp-servers/{server_id}`

`PATCH /mcp-servers/{server_id}`

`DELETE /mcp-servers/{server_id}`

`GET /mcp-servers/{server_id}/tools`

`POST /mcp-servers/{server_id}/refresh-tools`

`POST /mcp-servers/{server_id}/test`

Health

`GET /mcp-servers/health`

`POST /mcp-servers/health/refresh`

`POST /mcp-servers/{server_id}/health/refresh`

5. Valutazioni e A/B Testing

6. Template Prompt

`POST /prompt-templates`

`GET /prompt-templates`

`PUT /prompt-templates/{template_id}`

`DELETE /prompt-templates/{template_id}`

Pagine correlate