Utilisez le contrat OpenAPI pour générer un client d’intégration. L’API publique, le tableau de bord et le point de terminaison de gestion MCP agissent sur les mêmes ressources et permissions de l’espace de travail.
| Capacité | Point de terminaison |
|---|---|
| Outils réutilisables | GET / POST /api/v1/voice/tools |
| Lire / modifier / supprimer un outil | GET / PATCH / DELETE /api/v1/voice/tools/{id} |
| Prévisualiser ou tester un outil | POST /api/v1/voice/tools/{id}/test |
| Lier des outils à un agent | PUT /api/v1/voice/agents/{id}/tools |
| Bases de connaissances | GET / POST /api/v1/voice/knowledge-bases |
| Lire / modifier / supprimer une base de connaissances | GET / PATCH / DELETE /api/v1/voice/knowledge-bases/{id} |
| Ajouter / lister des documents | POST / GET /api/v1/voice/knowledge-bases/{id}/documents |
| Lire / supprimer un document | GET / DELETE /api/v1/voice/knowledge-bases/{id}/documents/{doc_id} |
| Abonnements aux événements d’appel | GET / POST /api/v1/voice/webhooks |
| Lire / modifier / supprimer un abonnement | GET / PATCH / DELETE /api/v1/voice/webhooks/{id} |
| Envoyer un événement de test signé | POST /api/v1/voice/webhooks/{id}/test |
| Découvrir des outils MCP distants | POST /api/v1/voice/mcp/discover |
| Point de terminaison de gestion MCP | /api/v1/voice/mcp |
Enregistrez un outil HTTP qui interroge votre adaptateur 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 renvoie { "data": { "id": "TOOL_ID", ... } }. Liez sa définition à un agent avec PUT /agents/AGENT_ID/tools et { "tool_ids": ["TOOL_ID"] }. Cela remplace toute la liste d’outils par des instantanés ; reliez à nouveau quand un outil de la bibliothèque change. Supprimer une définition de la bibliothèque conserve les instantanés existants. Vous pouvez aussi lire et remplacer les définitions en ligne avec le champ tools de l’API des agents. Utilisez analysis_config et widget_config pour configurer l’analyse et le widget via l’API des agents.
Un outil peut utiliser GET, POST, PUT, PATCH ou DELETE. query et request_body acceptent des modèles JSON imbriqués comme { "customer": { "id": "{{customer_id}}" } }. Une variable qui occupe toute la valeur conserve le type JSON d’origine. Les variables d’URL sont encodées et ne peuvent apparaître qu’après un hôte HTTPS public fixe. Sans request_body, les outils non GET reçoivent { "arguments": {...}, "call": { "callId": "...", "agentId": "...", "toolCallId": "...", "idempotencyKey": "..." } }. response_path sélectionne un champ en notation pointée. Les parameters simples sont toujours acceptés ; input_schema prend en charge en plus les objets imbriqués, tableaux, énumérations et bornes numériques. Les références de schéma externes et les expressions régulières ne sont pas acceptées.
static_args : valeurs envoyées à chaque appel quoi que le modèle écrive, comme un identifiant de magasin ; elles remplissent aussi {{name}} dans l’adresse et le corps.extract : [{name, path}] conserve des champs de la réponse d’une fonction (data.id) pour le {{name}} des fonctions suivantes, afin que le customer_id d’une recherche passe dans la commande qui suit sans que le modèle le répète. Les champs d’une consultation au démarrage sont conservés de la même façon.reject_when : jusqu’à 5 règles {on: caller|agent, pattern, negate} ; tant qu’elles sont toutes vraies pour les derniers mots, la fonction n’est pas exécutée et l’agent reçoit reject_message.model_says : à chaque appel, le modèle écrit une phrase dite pendant l’exécution de la fonction, au lieu du speak_before fixe.Connectez une app sous Intégrations → Webhooks et notifications → Applications connectées, puis utilisez « Ajouter une fonction prête à l’emploi » dans l’onglet Connaissances et outils de l’agent ; aucun point de terminaison à vous n’est nécessaire :
check_availability (créneaux libres à une date) et book_appointment (réserve le créneau choisi par l’appelant). Les créneaux Google Agenda suivent le fuseau horaire, les jours d’ouverture, les horaires et la durée de rendez-vous que vous définissez ; Cal.com utilise les disponibilités propres au type d’événement, et un e-mail de secours que vous définissez quand l’appelant n’en donne pas.save_to_sheet, qui ajoute une ligne avec les colonnes que vous listez, plus l’identifiant et l’heure de l’appel.notify_team, qui publie un message rédigé par l’agent dans un canal Slack (incoming webhook).Le plan de contrôle d’EvaSay exécute ces fonctions avec le compte que vous avez connecté ; ni le worker ni la définition de l’agent ne détiennent les identifiants de l’app. Lire un agent via l’API les montre comme kind: "app" (avec app, action, connection_id, app_config) ; renvoyez-les inchangées en remplaçant tools pour les garder. Les apps ne se connectent que dans le tableau de bord.
Réglez run_at_start: true sur l’un des outils d’un agent et il est appelé au début de chaque appel, avant que l’agent salue ou réponde. Les paramètres nommés caller_number, called_number, direction, channel ou call_id sont remplis pour lui. Les champs qu’il renvoie remplissent les {{variables}} dans first_message, system_prompt et idle_messages (les champs d’un niveau plus bas en {{customer.name}}), et toute la réponse est donnée à l’agent comme contexte. Un accueil avec des variables attend la réponse jusqu’à 3 secondes ; ce qui n’est pas trouvé reste vide. Un seul outil par agent peut s’exécuter au début.
Les identifiants sont configurés dans l’environnement serveur pour votre espace de travail et votre destination ; demandez à support@evasay.com de créer une credential_ref. Ne mettez pas de clés API dans les définitions d’agent, les en-têtes, les prompts ou les paramètres d’outil. Votre adaptateur peut garder les identifiants du CRM dans son propre environnement.
Prévisualisez un outil avant d’envoyer des requêtes au système métier :
{
"arguments": { "customer_id": "customer-123" },
"dry_run": true,
"mock_result": { "name": "Alex", "order_status": "shipped" }
}
Une prévisualisation valide les paramètres et montre la requête produite ; elle n’exécute pas de conversation et ne contacte pas le système métier. Réglez dry_run=false pour une exécution réelle. Un test d’écriture réel exige aussi confirmed=true et idempotency_key (8–128 lettres, chiffres, points, tirets bas, deux-points ou tirets). Les réponses de test contiennent ok, status, duration_ms et un résultat borné. Elles ne renvoient pas d’identifiants. Les tests de lecture et d’écriture exigent le droit d’écriture sur l’espace de travail.
Pendant un appel, les requêtes métier portent un Idempotency-Key stable. Votre point de terminaison métier doit le respecter. Les écritures identiques dans un appel sont dédupliquées, y compris les opérations au résultat inconnu après un délai dépassé. Une autre opération voulue nécessite un argument métier distinct, comme operation_id. EvaSay ne rejoue pas automatiquement les écritures. Les événements d’exécution d’outil incluent le statut et la durée ; la fonction de tests de conversation reste une simulation textuelle, pas un test d’exécution d’outil.
POST /mcp/discover accepte { "url": "https://crm.example.com/mcp", "credential_ref": "crm" } et renvoie les outils et schémas du serveur. N’enregistrez que l’outil choisi :
{
"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"]
}
}
Seuls les outils enregistrés sont disponibles pour l’agent. Les connexions distantes prennent en charge le Streamable HTTP avec réponses JSON ou SSE aux requêtes, des destinations HTTPS publiques et des identifiants préconfigurés. Les anciens points de terminaison SSE, la négociation OAuth, le sampling/elicitation initié par le serveur et les pièces jointes binaires ne sont pas pris en charge. La découverte n’accorde pas automatiquement l’accès à tous les outils du serveur. Le schéma de l’outil distant doit être en ligne et utiliser le sous-ensemble de JSON Schema pris en charge.