פונקציות

השתמשו בחוזה ה-OpenAPI כדי ליצור לקוח אינטגרציה. ה-API הציבורי, לוח הבקרה ונקודת הקצה לניהול MCP פועלים על אותם משאבים והרשאות של מרחב העבודה.

יכולת	Endpoint
כלים לשימוש חוזר	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

רשמו כלי HTTP ששואל את מתאם ה-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 מחזיר { "data": { "id": "TOOL_ID", ... } }. קשרו את ההגדרה שלו לסוכן עם PUT /agents/AGENT_ID/tools ו-{ "tool_ids": ["TOOL_ID"] }. פעולה זו מחליפה את כל רשימת הכלים בתצלומי מצב; קשרו מחדש כשכלי בספרייה משתנה. מחיקת הגדרה מהספרייה משאירה את התצלומים הקיימים. אפשר גם לקרוא ולהחליף הגדרות מוטמעות עם השדה tools של ה-API של הסוכן. השתמשו ב-analysis_config וב-widget_config כדי להגדיר את הניתוח והווידג'ט דרך ה-API של הסוכן.

כלי יכול להשתמש ב-GET, ‏POST, ‏PUT, ‏PATCH או DELETE. ‏query ו-request_body מקבלים תבניות JSON מקוננות כמו { "customer": { "id": "{{customer_id}}" } }. מציין מקום שלם שומר על סוג ה-JSON המקורי. מציייני מקום ב-URL מקודדים ויכולים להופיע רק אחרי מארח HTTPS ציבורי קבוע. ללא request_body, כלים שאינם GET מקבלים { "arguments": {...}, "call": { "callId": "...", "agentId": "...", "toolCallId": "...", "idempotencyKey": "..." } }. response_path בוחר שדה בסימון נקודות. parameters פשוטים עדיין מתקבלים; input_schema תומך בנוסף באובייקטים מקוננים, מערכים, רשימות ערכים וגבולות מספריים. הפניות לסכמות חיצוניות וביטויים רגולריים אינם מתקבלים.

ערכים קבועים, העברת ערכים וכללי סירוב

• static_args: ערכים שנשלחים בכל קריאה בלי קשר למה שהמודל כותב, כמו מזהה חנות; הם ממלאים גם את {{name}} בכתובת ובגוף.
• extract: ‏[{name, path}] שומר שדות מתשובת פונקציה (data.id) עבור {{name}} של פונקציות מאוחרות יותר, כך ש-customer_id מחיפוש יכול להיכנס להזמנה שבאה אחריו בלי שהמודל יחזור עליו. שדות של חיפוש התחלה נשמרים באותו אופן.
• reject_when: עד 5 כללים {on: caller|agent, pattern, negate}; כל עוד כולם מתקיימים על המילים האחרונות, הפונקציה אינה רצה והסוכן מקבל את reject_message.
• model_says: בכל קריאה המודל כותב משפט אחד שנאמר בזמן שהפונקציה רצה, במקום speak_before הקבוע.

פונקציות מוכנות: הזמנות, גיליונות, Slack

חברו אפליקציה תחת אינטגרציות ← Webhooks והתראות ← אפליקציות מחוברות, ואז השתמשו ב"הוספת פונקציה מוכנה" בלשונית ידע וכלים של הסוכן; אין צורך ב-endpoint משלכם:

• הזמנות (Google Calendar / Cal.com): מוסיף check_availability (שעות פנויות בתאריך) ו-book_appointment (קובע את השעה שהמתקשר בחר). השעות ב-Google Calendar עוקבות אחר אזור הזמן, ימי הפעילות, השעות ומשך הפגישה שהגדרתם; Cal.com משתמש בזמינות של סוג האירוע עצמו, ובדוא"ל גיבוי שתגדירו למקרה שהמתקשר לא נותן כתובת.
• שמירה ב-Google Sheets: מוסיף save_to_sheet, שמוסיפה שורה עם העמודות שתציינו, יחד עם מזהה השיחה והשעה שלה.
• הודעה לצוות (Slack): מוסיף 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 ממולאים עבורו. השדות שהוא מחזיר ממלאים {{variables}} ב-first_message, ב-system_prompt וב-idle_messages (שדות ברמה אחת מתחת כמו {{customer.name}}), והתשובה כולה ניתנת לסוכן כרקע. ברכה עם משתנים ממתינה לתשובה עד 3 שניות; מה שלא נמצא נשאר ריק. כלי אחד לכל סוכן יכול לרוץ בתחילה.

פרטי גישה מוגדרים בסביבת השרת עבור מרחב העבודה והיעד שלכם; בקשו מ-support@evasay.com להקצות credential_ref. אל תשימו מפתחות 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 יציב. ה-endpoint העסקי שלכם חייב לכבד אותו. כתיבות זהות בתוך שיחה עוברות הסרת כפילויות, כולל פעולות שתוצאתן לא ידועה אחרי פסק זמן. פעולה אחרת שנעשית בכוונה זקוקה לארגומנט עסקי נפרד, כמו operation_id. EvaSay אינה משחזרת כתיבות באופן אוטומטי. אירועי הרצת כלים כוללים סטטוס ומשך; תכונת בדיקת השיחה נשארת הדמיית טקסט, לא בדיקה של הרצת כלים.

לאפשר לסוכן הקולי לקרוא לשרת MCP חיצוני

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"]
  }
}

רק כלים רשומים זמינים לסוכן. חיבורים מרוחקים תומכים ב-Streamable HTTP עם תשובות JSON או SSE לבקשות, יעדי HTTPS ציבוריים ופרטי גישה שהוגדרו מראש. נקודות קצה ישנות של SSE, משא ומתן OAuth, ‏sampling/elicitation שיוזם השרת וקבצים מצורפים בינאריים אינם נתמכים. הגילוי אינו מעניק אוטומטית גישה לכל כלי השרת. סכמת הכלי המרוחק חייבת להיות מוטמעת ולהשתמש בתת-הקבוצה הנתמכת של JSON Schema.