Usa el contrato OpenAPI para generar un cliente de integración. La API pública, el panel y el endpoint de gestión MCP operan sobre los mismos recursos y permisos del espacio de trabajo.
| Capacidad | Endpoint |
|---|---|
| Herramientas reutilizables | GET / POST /api/v1/voice/tools |
| Leer / actualizar / eliminar una herramienta | GET / PATCH / DELETE /api/v1/voice/tools/{id} |
| Previsualizar o probar una herramienta | POST /api/v1/voice/tools/{id}/test |
| Vincular herramientas a un agente | PUT /api/v1/voice/agents/{id}/tools |
| Bases de conocimiento | GET / POST /api/v1/voice/knowledge-bases |
| Leer / actualizar / eliminar una base de conocimiento | GET / PATCH / DELETE /api/v1/voice/knowledge-bases/{id} |
| Añadir / listar documentos | POST / GET /api/v1/voice/knowledge-bases/{id}/documents |
| Leer / eliminar un documento | GET / DELETE /api/v1/voice/knowledge-bases/{id}/documents/{doc_id} |
| Suscripciones a eventos de llamada | GET / POST /api/v1/voice/webhooks |
| Leer / actualizar / eliminar una suscripción | GET / PATCH / DELETE /api/v1/voice/webhooks/{id} |
| Enviar un evento de prueba firmado | POST /api/v1/voice/webhooks/{id}/test |
| Descubrir herramientas MCP remotas | POST /api/v1/voice/mcp/discover |
| Endpoint de gestión MCP | /api/v1/voice/mcp |
Registra una herramienta HTTP que consulta tu adaptador de 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 devuelve { "data": { "id": "TOOL_ID", ... } }. Vincula su definición a un agente con PUT /agents/AGENT_ID/tools y { "tool_ids": ["TOOL_ID"] }. Esto sustituye toda la lista de herramientas por instantáneas; vuelve a vincular cuando cambie una herramienta de la biblioteca. Eliminar una definición de la biblioteca conserva las instantáneas existentes. También puedes leer y sustituir definiciones en línea con el campo tools de la API de agentes. Usa analysis_config y widget_config para configurar el análisis y el widget mediante la API de agentes.
Una herramienta puede usar GET, POST, PUT, PATCH o DELETE. query y request_body aceptan plantillas JSON anidadas como { "customer": { "id": "{{customer_id}}" } }. Un marcador completo conserva el tipo JSON original. Los marcadores de la URL se codifican y solo pueden aparecer después de un host HTTPS público fijo. Sin request_body, las herramientas que no son GET reciben { "arguments": {...}, "call": { "callId": "...", "agentId": "...", "toolCallId": "...", "idempotencyKey": "..." } }. response_path selecciona un campo con notación de puntos. Los parameters simples se siguen aceptando; input_schema admite además objetos anidados, arrays, enumeraciones y límites numéricos. No se aceptan referencias a esquemas externos ni expresiones regulares.
static_args: valores enviados en cada llamada escriba lo que escriba el modelo, como un id de tienda; también rellenan {{name}} en la dirección y el cuerpo.extract: [{name, path}] conserva campos de la respuesta de una función (data.id) para el {{name}} de funciones posteriores, de modo que el customer_id de una consulta pueda pasar al pedido siguiente sin que el modelo lo repita. Los campos de una consulta de inicio se conservan igual.reject_when: hasta 5 reglas {on: caller|agent, pattern, negate}; mientras todas se cumplan en las últimas palabras, la función no se ejecuta y el agente recibe reject_message.model_says: en cada llamada, el modelo escribe una frase que se dice mientras la función se ejecuta, en lugar del speak_before fijo.Conecta una app en Integraciones → Webhooks y notificaciones → Apps conectadas y después usa «Añadir una función predefinida» en la pestaña Conocimiento y herramientas del agente; no necesitas ningún endpoint propio:
check_availability (horas libres en una fecha) y book_appointment (reserva la hora que eligió quien llama). Las horas de Google Calendar siguen la zona horaria, los días de apertura, el horario y la duración de cita que definas; Cal.com usa la disponibilidad propia del tipo de evento, y un correo de reserva que definas cuando quien llama no da ninguno.save_to_sheet, que añade una fila con las columnas que indiques, más el ID y la hora de la llamada.notify_team, que publica en un canal de Slack (incoming webhook) un mensaje que escribe el agente.El plano de control de EvaSay ejecuta estas funciones con la cuenta que conectaste; ni el worker ni la definición del agente guardan las credenciales de la app. Al leer un agente con la API, aparecen como kind: "app" (con app, action, connection_id, app_config); devuélvelas sin cambios al sustituir tools para conservarlas. Las apps se conectan solo desde el panel.
Define run_at_start: true en una de las herramientas de un agente y se llamará al empezar cada llamada, antes de que el agente salude o responda. Los parámetros llamados caller_number, called_number, direction, channel o call_id se rellenan por ti. Los campos que devuelve rellenan {{variables}} en first_message, system_prompt e idle_messages (los campos un nivel más abajo, como {{customer.name}}), y la respuesta completa se entrega al agente como contexto. Un saludo con variables espera hasta 3 segundos la respuesta; lo que no se encuentre queda en blanco. Solo una herramienta por agente puede ejecutarse al inicio.
Las credenciales se configuran en el entorno del servidor para tu espacio de trabajo y destino; pide a support@evasay.com que aprovisione un credential_ref. No pongas claves de API en las definiciones de agente, cabeceras, prompts ni parámetros de herramientas. Tu adaptador puede guardar las credenciales del CRM en su propio entorno.
Previsualiza una herramienta antes de hacer solicitudes al sistema de negocio:
{
"arguments": { "customer_id": "customer-123" },
"dry_run": true,
"mock_result": { "name": "Alex", "order_status": "shipped" }
}
Una vista previa valida los parámetros y muestra la solicitud resultante; no ejecuta una conversación ni contacta con el sistema de negocio. Define dry_run=false para una ejecución real. Una prueba de escritura real también exige confirmed=true e idempotency_key (8–128 letras, números, puntos, guiones bajos, dos puntos o guiones). Las respuestas de prueba incluyen ok, status, duration_ms y un resultado acotado. No devuelven credenciales. Las pruebas de lectura y escritura requieren permiso de escritura en el espacio de trabajo.
Durante una llamada, las solicitudes de negocio llevan un Idempotency-Key estable. Tu endpoint de negocio debe respetarlo. Las escrituras idénticas dentro de una llamada se deduplican, incluidas las operaciones con resultado desconocido tras un tiempo de espera agotado. Una operación distinta e intencionada necesita un argumento de negocio distinto, como operation_id. EvaSay no reproduce escrituras automáticamente. Los eventos de ejecución de herramientas incluyen estado y duración; la función de prueba de conversación sigue siendo una simulación de texto, no una prueba de ejecución de herramientas.
POST /mcp/discover acepta { "url": "https://crm.example.com/mcp", "credential_ref": "crm" } y devuelve las herramientas y los esquemas del servidor. Registra solo la herramienta seleccionada:
{
"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 las herramientas registradas quedan disponibles para el agente. Las conexiones remotas admiten Streamable HTTP con respuestas JSON o SSE a las solicitudes, destinos HTTPS públicos y credenciales preconfiguradas. No se admiten los endpoints SSE heredados, la negociación OAuth, el muestreo ni la elicitación iniciados por el servidor, ni los adjuntos binarios. El descubrimiento no concede automáticamente acceso a todas las herramientas del servidor. El esquema de la herramienta remota debe estar en línea y usar el subconjunto admitido de JSON Schema.