Usa il contratto OpenAPI per generare un client di integrazione. L'API pubblica, la dashboard e l'endpoint di gestione MCP operano sulle stesse risorse e sugli stessi permessi dello spazio di lavoro.
| Funzionalità | Endpoint |
|---|---|
| Strumenti riutilizzabili | GET / POST /api/v1/voice/tools |
| Leggere / aggiornare / eliminare uno strumento | GET / PATCH / DELETE /api/v1/voice/tools/{id} |
| Anteprima o test di uno strumento | POST /api/v1/voice/tools/{id}/test |
| Associare strumenti a un agente | PUT /api/v1/voice/agents/{id}/tools |
| Basi di conoscenza | GET / POST /api/v1/voice/knowledge-bases |
| Leggere / aggiornare / eliminare una base di conoscenza | GET / PATCH / DELETE /api/v1/voice/knowledge-bases/{id} |
| Aggiungere / elencare documenti | POST / GET /api/v1/voice/knowledge-bases/{id}/documents |
| Leggere / eliminare un documento | GET / DELETE /api/v1/voice/knowledge-bases/{id}/documents/{doc_id} |
| Sottoscrizioni agli eventi di chiamata | GET / POST /api/v1/voice/webhooks |
| Leggere / aggiornare / eliminare una sottoscrizione | GET / PATCH / DELETE /api/v1/voice/webhooks/{id} |
| Inviare un evento di prova firmato | POST /api/v1/voice/webhooks/{id}/test |
| Scoprire gli strumenti MCP remoti | POST /api/v1/voice/mcp/discover |
| Endpoint di gestione MCP | /api/v1/voice/mcp |
Registra uno strumento HTTP che interroga il tuo adattatore CRM:
{
"name": "lookup_customer",
"description": "Find a customer after confirming their customer ID.",
"kind": "http",
"url": "https://crm.example.com/customers/{{customer_id}}",
"method": "GET",
"read_only": true,
"credential_ref": "crm",
"input_schema": {
"type": "object",
"properties": { "customer_id": { "type": "string" } },
"required": ["customer_id"],
"additionalProperties": false
},
"response_path": "data"
}
POST /tools restituisce { "data": { "id": "TOOL_ID", ... } }. Associa la sua definizione a un agente con PUT /agents/AGENT_ID/tools e { "tool_ids": ["TOOL_ID"] }. Questo sostituisce l'intero elenco di strumenti con degli snapshot; riassocia quando uno strumento della libreria cambia. Eliminare una definizione della libreria mantiene gli snapshot esistenti. Puoi anche leggere e sostituire le definizioni incorporate con il campo tools dell'API degli agenti. Usa analysis_config e widget_config per configurare l'analisi e il widget tramite l'API degli agenti.
Uno strumento può usare GET, POST, PUT, PATCH o DELETE. query e request_body accettano modelli JSON annidati come { "customer": { "id": "{{customer_id}}" } }. Un segnaposto intero conserva il tipo JSON originale. I segnaposto dell'URL vengono codificati e possono comparire solo dopo un host HTTPS pubblico fisso. Senza request_body, gli strumenti diversi da GET ricevono { "arguments": {...}, "call": { "callId": "...", "agentId": "...", "toolCallId": "...", "idempotencyKey": "..." } }. response_path seleziona un campo con la notazione a punti. I semplici parameters sono ancora accettati; input_schema supporta inoltre oggetti annidati, array, enumerazioni e limiti numerici. Non sono accettati riferimenti a schemi esterni ed espressioni regolari.
static_args: valori inviati a ogni chiamata qualunque cosa scriva il modello, come l'id di un negozio; riempiono anche {{name}} nell'indirizzo e nel corpo.extract: [{name, path}] conserva campi della risposta di una funzione (data.id) per il {{name}} delle funzioni successive, così il customer_id di una consultazione può passare all'ordine seguente senza che il modello lo ripeta. I campi di una consultazione di avvio vengono conservati allo stesso modo.reject_when: fino a 5 regole {on: caller|agent, pattern, negate}; finché valgono tutte per le ultime parole, la funzione non viene eseguita e l'agente riceve reject_message.model_says: a ogni chiamata il modello scrive una frase che viene detta mentre la funzione è in esecuzione, al posto del speak_before fisso.Collega un'app in Integrazioni → Webhook e notifiche → App collegate, poi usa «Aggiungi una funzione predefinita» nella scheda Conoscenza e strumenti dell'agente; non serve alcun endpoint tuo:
check_availability (orari liberi in una data) e book_appointment (prenota l'orario scelto da chi chiama). Gli orari di Google Calendar seguono il fuso orario, i giorni di apertura, gli orari e la durata dell'appuntamento che imposti; Cal.com usa la disponibilità del tipo di evento stesso, e un'e-mail di riserva che imposti quando chi chiama non ne fornisce una.save_to_sheet, che accoda una riga con le colonne che elenchi, più l'ID e l'ora della chiamata.notify_team, che pubblica in un canale Slack (incoming webhook) un messaggio scritto dall'agente.Il piano di controllo di EvaSay esegue queste funzioni con l'account che hai collegato; né il worker né la definizione dell'agente conservano le credenziali dell'app. Leggendo un agente tramite l'API compaiono come kind: "app" (con app, action, connection_id, app_config); rimandale invariate quando sostituisci tools per mantenerle. Le app si collegano solo dalla dashboard.
Imposta run_at_start: true su uno strumento di un agente e verrà chiamato all'inizio di ogni chiamata, prima che l'agente saluti o risponda. I parametri chiamati caller_number, called_number, direction, channel o call_id vengono compilati per lui. I campi che restituisce riempiono {{variables}} in first_message, system_prompt e idle_messages (i campi un livello più giù come {{customer.name}}), e l'intera risposta viene data all'agente come contesto. Un saluto con variabili aspetta la risposta fino a 3 secondi; ciò che non viene trovato resta vuoto. Può essere eseguito all'avvio uno strumento per agente.
Le credenziali si configurano nell'ambiente del server per il tuo spazio di lavoro e la destinazione; chiedi a support@evasay.com di predisporre un credential_ref. Non inserire chiavi API nelle definizioni degli agenti, negli header, nei prompt o nei parametri degli strumenti. Il tuo adattatore può tenere le credenziali del CRM nel proprio ambiente.
Fai un'anteprima di uno strumento prima di inviare richieste al sistema aziendale:
{
"arguments": { "customer_id": "customer-123" },
"dry_run": true,
"mock_result": { "name": "Alex", "order_status": "shipped" }
}
Un'anteprima convalida i parametri e mostra la richiesta risultante; non esegue una conversazione né contatta il sistema aziendale. Imposta dry_run=false per un'esecuzione reale. Un test di scrittura reale richiede anche confirmed=true e idempotency_key (8–128 lettere, numeri, punti, trattini bassi, due punti o trattini). Le risposte dei test includono ok, status, duration_ms e un risultato limitato. Non restituiscono credenziali. I test di lettura e di scrittura richiedono il permesso di scrittura nello spazio di lavoro.
Durante una chiamata, le richieste aziendali portano un Idempotency-Key stabile. Il tuo endpoint aziendale deve rispettarlo. Le scritture identiche all'interno di una chiamata vengono deduplicate, comprese le operazioni con esito sconosciuto dopo un timeout. Un'altra operazione intenzionale richiede un argomento aziendale distinto, come operation_id. EvaSay non ripete automaticamente le scritture. Gli eventi di esecuzione degli strumenti includono stato e durata; la funzione di test della conversazione resta una simulazione di testo, non un test di esecuzione degli strumenti.
POST /mcp/discover accetta { "url": "https://crm.example.com/mcp", "credential_ref": "crm" } e restituisce gli strumenti e gli schemi del server. Registra solo lo strumento selezionato:
{
"name": "lookup_customer",
"description": "Find a CRM customer by confirmed ID.",
"kind": "mcp",
"url": "https://crm.example.com/mcp",
"mcp_tool": "get_customer",
"credential_ref": "crm",
"read_only": true,
"input_schema": {
"type": "object",
"properties": { "customer_id": { "type": "string" } },
"required": ["customer_id"]
}
}
Solo gli strumenti registrati diventano disponibili per l'agente. Le connessioni remote supportano Streamable HTTP con risposte JSON o SSE alle richieste, destinazioni HTTPS pubbliche e credenziali preconfigurate. Non sono supportati endpoint SSE legacy, negoziazione OAuth, sampling o elicitation avviati dal server e allegati binari. La scoperta non concede automaticamente l'accesso a tutti gli strumenti del server. Lo schema dello strumento remoto deve essere incorporato e usare il sottoinsieme supportato di JSON Schema.