Use o contrato OpenAPI para gerar um cliente de integração. A API pública, o painel e o endpoint de gerenciamento MCP operam sobre os mesmos recursos e permissões do workspace.
| Capacidade | Endpoint |
|---|---|
| Ferramentas reutilizáveis | GET / POST /api/v1/voice/tools |
| Ler / atualizar / excluir uma ferramenta | GET / PATCH / DELETE /api/v1/voice/tools/{id} |
| Visualizar ou testar uma ferramenta | POST /api/v1/voice/tools/{id}/test |
| Vincular ferramentas a um agente | PUT /api/v1/voice/agents/{id}/tools |
| Bases de conhecimento | GET / POST /api/v1/voice/knowledge-bases |
| Ler / atualizar / excluir uma base de conhecimento | GET / PATCH / DELETE /api/v1/voice/knowledge-bases/{id} |
| Adicionar / listar documentos | POST / GET /api/v1/voice/knowledge-bases/{id}/documents |
| Ler / excluir um documento | GET / DELETE /api/v1/voice/knowledge-bases/{id}/documents/{doc_id} |
| Assinaturas de eventos de chamada | GET / POST /api/v1/voice/webhooks |
| Ler / atualizar / excluir uma assinatura | GET / PATCH / DELETE /api/v1/voice/webhooks/{id} |
| Enviar um evento de teste assinado | POST /api/v1/voice/webhooks/{id}/test |
| Descobrir ferramentas MCP remotas | POST /api/v1/voice/mcp/discover |
| Endpoint de gerenciamento MCP | /api/v1/voice/mcp |
Registre uma ferramenta HTTP que consulta o seu 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 retorna { "data": { "id": "TOOL_ID", ... } }. Vincule a definição a um agente com PUT /agents/AGENT_ID/tools e { "tool_ids": ["TOOL_ID"] }. Isso substitui toda a lista de ferramentas por instantâneos; vincule de novo quando uma ferramenta da biblioteca mudar. Excluir uma definição da biblioteca mantém os instantâneos existentes. Você também pode ler e substituir definições embutidas com o campo tools da API de agentes. Use analysis_config e widget_config para configurar a análise e o widget pela API de agentes.
Uma ferramenta pode usar GET, POST, PUT, PATCH ou DELETE. query e request_body aceitam modelos JSON aninhados como { "customer": { "id": "{{customer_id}}" } }. Um marcador inteiro preserva o tipo JSON original. Os marcadores da URL são codificados e só podem aparecer depois de um host HTTPS público fixo. Sem request_body, as ferramentas que não são GET recebem { "arguments": {...}, "call": { "callId": "...", "agentId": "...", "toolCallId": "...", "idempotencyKey": "..." } }. response_path seleciona um campo com notação de pontos. Os parameters simples continuam aceitos; input_schema também aceita objetos aninhados, arrays, enumerações e limites numéricos. Referências a esquemas externos e expressões regulares não são aceitas.
static_args: valores enviados em toda chamada, não importa o que o modelo escreva, como um id de loja; também preenchem {{name}} no endereço e no corpo.extract: [{name, path}] guarda campos da resposta de uma função (data.id) para o {{name}} de funções posteriores, de modo que o customer_id de uma consulta possa ir para o pedido seguinte sem o modelo repeti-lo. Os campos de uma consulta de início são guardados do mesmo jeito.reject_when: até 5 regras {on: caller|agent, pattern, negate}; enquanto todas valerem para as últimas palavras, a função não é executada e o agente recebe reject_message.model_says: a cada chamada, o modelo escreve uma frase que é dita enquanto a função roda, no lugar do speak_before fixo.Conecte um app em Integrações → Webhooks e notificações → Apps conectados e depois use «Adicionar uma função pronta» na aba Conhecimento e ferramentas do agente; você não precisa de nenhum endpoint próprio:
check_availability (horários livres em uma data) e book_appointment (agenda o horário que quem liga escolheu). Os horários do Google Calendar seguem o fuso horário, os dias de funcionamento, o horário e a duração do atendimento que você definir; o Cal.com usa a disponibilidade do próprio tipo de evento, e um e-mail reserva que você definir quando quem liga não informa nenhum.save_to_sheet, que acrescenta uma linha com as colunas que você listar, além do ID e da hora da chamada.notify_team, que publica em um canal do Slack (incoming webhook) uma mensagem escrita pelo agente.O plano de controle da EvaSay executa essas funções com a conta que você conectou; nem o worker nem a definição do agente guardam as credenciais do app. Ao ler um agente pela API, elas aparecem como kind: "app" (com app, action, connection_id, app_config); devolva-as sem alterações ao substituir tools para mantê-las. Os apps são conectados somente no painel.
Defina run_at_start: true em uma das ferramentas de um agente e ela será chamada no início de cada chamada, antes de o agente cumprimentar ou responder. Os parâmetros chamados caller_number, called_number, direction, channel ou call_id são preenchidos para ela. Os campos que ela retorna preenchem {{variables}} em first_message, system_prompt e idle_messages (campos um nível abaixo, como {{customer.name}}), e a resposta inteira é dada ao agente como contexto. Uma saudação com variáveis espera até 3 segundos pela resposta; o que não for encontrado fica em branco. Apenas uma ferramenta por agente pode rodar no início.
As credenciais são configuradas no ambiente do servidor para o seu workspace e destino; peça a support@evasay.com para provisionar um credential_ref. Não coloque chaves de API em definições de agente, cabeçalhos, prompts nem parâmetros de ferramentas. Seu adaptador pode guardar as credenciais do CRM no próprio ambiente.
Visualize uma ferramenta antes de fazer requisições ao sistema de negócio:
{
"arguments": { "customer_id": "customer-123" },
"dry_run": true,
"mock_result": { "name": "Alex", "order_status": "shipped" }
}
Uma visualização valida os parâmetros e mostra a requisição resultante; ela não executa uma conversa nem contata o sistema de negócio. Defina dry_run=false para uma execução real. Um teste de escrita real também exige confirmed=true e idempotency_key (8–128 letras, números, pontos, sublinhados, dois-pontos ou hifens). As respostas de teste incluem ok, status, duration_ms e um resultado limitado. Elas não retornam credenciais. Os testes de leitura e de escrita exigem permissão de escrita no workspace.
Durante uma chamada, as requisições de negócio levam um Idempotency-Key estável. Seu endpoint de negócio deve respeitá-lo. Escritas idênticas dentro de uma chamada são deduplicadas, inclusive operações de resultado desconhecido após um tempo esgotado. Uma operação diferente e intencional precisa de um argumento de negócio distinto, como operation_id. A EvaSay não reenvia escritas automaticamente. Os eventos de execução de ferramentas incluem status e duração; o recurso de teste de conversa continua sendo uma simulação de texto, não um teste de execução de ferramentas.
POST /mcp/discover aceita { "url": "https://crm.example.com/mcp", "credential_ref": "crm" } e retorna as ferramentas e os esquemas do servidor. Registre somente a ferramenta selecionada:
{
"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"]
}
}
Somente as ferramentas registradas ficam disponíveis para o agente. As conexões remotas aceitam Streamable HTTP com respostas JSON ou SSE às requisições, destinos HTTPS públicos e credenciais pré-configuradas. Não são aceitos endpoints SSE legados, negociação OAuth, amostragem e elicitação iniciadas pelo servidor, nem anexos binários. A descoberta não concede automaticamente acesso a todas as ferramentas do servidor. O esquema da ferramenta remota deve ser embutido e usar o subconjunto compatível de JSON Schema.