OpenAPI 계약으로 연동 클라이언트를 생성하세요. 공개 API, 대시보드, MCP 관리 엔드포인트는 같은 워크스페이스 리소스와 권한을 다룹니다.
| 기능 | 엔드포인트 |
|---|---|
| 재사용 가능한 도구 | GET / POST /api/v1/voice/tools |
| 도구 조회 / 수정 / 삭제 | GET / PATCH / DELETE /api/v1/voice/tools/{id} |
| 도구 미리보기 또는 테스트 | POST /api/v1/voice/tools/{id}/test |
| 에이전트에 도구 연결 | PUT /api/v1/voice/agents/{id}/tools |
| 지식 베이스 | GET / POST /api/v1/voice/knowledge-bases |
| 지식 베이스 조회 / 수정 / 삭제 | GET / PATCH / DELETE /api/v1/voice/knowledge-bases/{id} |
| 문서 추가 / 목록 | POST / GET /api/v1/voice/knowledge-bases/{id}/documents |
| 문서 조회 / 삭제 | GET / DELETE /api/v1/voice/knowledge-bases/{id}/documents/{doc_id} |
| 통화 이벤트 구독 | GET / POST /api/v1/voice/webhooks |
| 구독 조회 / 수정 / 삭제 | GET / PATCH / DELETE /api/v1/voice/webhooks/{id} |
| 서명된 테스트 이벤트 보내기 | POST /api/v1/voice/webhooks/{id}/test |
| 원격 MCP 도구 찾기 | POST /api/v1/voice/mcp/discover |
| MCP 관리 엔드포인트 | /api/v1/voice/mcp |
CRM 어댑터를 조회하는 HTTP 도구를 등록합니다.
{
"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는 { "data": { "id": "TOOL_ID", ... } }를 돌려줍니다. PUT /agents/AGENT_ID/tools와 { "tool_ids": ["TOOL_ID"] }로 그 정의를 에이전트에 연결하세요. 이것은 도구 목록 전체를 스냅샷으로 바꿉니다. 라이브러리 도구가 바뀌면 다시 연결하세요. 라이브러리 정의를 삭제해도 기존 스냅샷은 남습니다. 에이전트 API의 tools 필드로 인라인 정의를 읽고 바꿀 수도 있습니다. 분석과 위젯은 에이전트 API의 analysis_config와 widget_config로 설정합니다.
도구는 GET, POST, PUT, PATCH, DELETE를 쓸 수 있습니다. query와 request_body는 { "customer": { "id": "{{customer_id}}" } } 같은 중첩 JSON 템플릿을 받습니다. 값 전체가 자리 표시자이면 원래 JSON 타입이 유지됩니다. URL 자리 표시자는 인코딩되며, 고정된 공개 HTTPS 호스트 뒤에만 올 수 있습니다. request_body가 없으면 GET이 아닌 도구는 { "arguments": {...}, "call": { "callId": "...", "agentId": "...", "toolCallId": "...", "idempotencyKey": "..." } }를 받습니다. response_path는 점 표기법으로 필드를 고릅니다. 단순한 parameters도 계속 받으며, input_schema는 중첩 객체, 배열, 열거형, 숫자 범위도 지원합니다. 외부 스키마 참조와 정규 표현식은 받지 않습니다.
static_args: 모델이 무엇을 쓰든 매번 보내는 값(예: 매장 ID). 주소와 본문의 {{name}}도 채웁니다.extract: [{name, path}]로 함수 답의 필드(data.id)를 보관해 이후 함수의 {{name}}에 씁니다. 조회로 얻은 customer_id를 모델이 되풀이하지 않아도 이어지는 주문에 넘길 수 있습니다. 시작 조회의 필드도 같은 방식으로 보관됩니다.reject_when: 최대 5개 규칙 {on: caller|agent, pattern, negate}. 마지막 말이 모두를 만족하는 동안에는 함수를 실행하지 않고 에이전트에게 reject_message를 줍니다.model_says: 호출할 때마다 모델이 한 문장을 쓰고, 함수가 실행되는 동안 그것을 말합니다. 고정된 speak_before 대신입니다.연동 → Webhook 및 알림 → 연결된 앱에서 앱을 연결한 다음, 에이전트의 지식 및 도구 탭에서 "준비된 함수 추가"를 쓰세요. 자체 엔드포인트가 필요 없습니다.
check_availability(날짜의 빈 시간)와 book_appointment(발신자가 고른 시간을 예약)를 추가합니다. Google 캘린더 시간은 설정한 시간대, 영업일, 영업시간, 예약 길이를 따릅니다. Cal.com은 이벤트 유형 자체의 가능 시간을 쓰며, 발신자가 이메일을 주지 않으면 설정한 대체 이메일을 씁니다.save_to_sheet를 추가해, 지정한 열에 통화 ID와 시간을 더해 한 행을 덧붙입니다.notify_team을 추가해, 에이전트가 쓴 메시지를 Slack 채널(Incoming Webhook)에 올립니다.이 함수들은 연결한 계정으로 EvaSay 컨트롤 플레인이 실행합니다. Worker도 에이전트 정의도 앱의 자격 증명을 갖지 않습니다. API로 에이전트를 읽으면 이것들은 kind: "app"(app, action, connection_id, app_config 포함)로 보입니다. tools를 바꿀 때 유지하려면 그대로 다시 보내세요. 앱 연결은 대시보드에서만 합니다.
에이전트 도구 중 하나에 run_at_start: true를 설정하면 각 통화가 시작될 때, 에이전트가 인사하거나 답하기 전에 호출됩니다. caller_number, called_number, direction, channel, call_id라는 이름의 매개변수에는 값이 채워집니다. 돌려받은 필드는 first_message, system_prompt, idle_messages의 {{variables}}를 채우고(한 단계 아래 필드는 {{customer.name}}), 답 전체가 배경 정보로 에이전트에게 전달됩니다. 변수가 있는 인사말은 답을 최대 3초 기다리고, 찾지 못한 것은 빈칸으로 둡니다. 시작 시 실행할 수 있는 도구는 에이전트당 하나입니다.
자격 증명은 워크스페이스와 대상별로 서버 환경에 설정됩니다. credential_ref 발급은 support@evasay.com에 요청하세요. API 키를 에이전트 정의, 헤더, 프롬프트, 도구 매개변수에 넣지 마세요. CRM 자격 증명은 어댑터 자체 환경에 둘 수 있습니다.
업무 시스템에 요청을 보내기 전에 도구를 미리 봅니다.
{
"arguments": { "customer_id": "customer-123" },
"dry_run": true,
"mock_result": { "name": "Alex", "order_status": "shipped" }
}
미리보기는 매개변수를 검증하고 변환된 요청을 보여 줍니다. 대화를 실행하거나 업무 시스템에 연결하지 않습니다. 실제로 실행하려면 dry_run=false로 설정하세요. 실제 쓰기 테스트에는 confirmed=true와 idempotency_key(8–128자의 영문자, 숫자, 점, 밑줄, 콜론, 하이픈)도 필요합니다. 테스트 응답에는 ok, status, duration_ms와 크기가 제한된 결과가 있으며, 자격 증명은 돌려주지 않습니다. 읽기와 쓰기 테스트에는 워크스페이스 쓰기 권한이 필요합니다.
통화 중 업무 요청에는 고정된 Idempotency-Key가 붙습니다. 업무 엔드포인트는 이를 지켜야 합니다. 한 통화 안의 같은 쓰기는 시간 초과로 결과를 알 수 없는 작업까지 포함해 중복 제거됩니다. 의도적으로 다른 작업을 하려면 operation_id 같은 다른 업무 인수가 필요합니다. EvaSay는 쓰기를 자동으로 다시 실행하지 않습니다. 도구 실행 이벤트에는 상태와 소요 시간이 있습니다. 대화 테스트 기능은 텍스트 시뮬레이션이며, 도구 실행 테스트가 아닙니다.
POST /mcp/discover는 { "url": "https://crm.example.com/mcp", "credential_ref": "crm" }를 받아 서버의 도구와 스키마를 돌려줍니다. 고른 도구만 등록하세요.
{
"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"]
}
}
에이전트는 등록한 도구만 쓸 수 있습니다. 원격 연결은 요청에 JSON 또는 SSE로 답하는 Streamable HTTP, 공개 HTTPS 대상, 미리 설정된 자격 증명을 지원합니다. 예전 SSE 엔드포인트, OAuth 협상, 서버가 시작하는 sampling/elicitation, 바이너리 첨부는 지원하지 않습니다. 찾기만으로 서버의 모든 도구에 접근 권한이 자동으로 주어지지는 않습니다. 원격 도구 스키마는 인라인이어야 하며 지원되는 JSON Schema 부분 집합을 써야 합니다.