AI Agents API
ה־AI Agents API מנהל סוכני AI מסוג generate-only: אובייקטים לשימוש חוזר שקוראים הקשר תחום ומפיקים פלט מובנה ומאומת שהמסעות ועבודות הקטלוג פועלים לפיו. לסוכן אין כלים ואין פעולות - הוא לעולם אינו שולח, מסתעף או כותב בעצמו. להסבר על המושגים, ראו את מדריך AI Agents בלוח הבקרה.
ה־API הזה משקף את המסך Settings → AI Agents בלוח הבקרה. השתמשו בו כדי ליצור סוכנים באמצעות קוד, לרשום מפתחות ספק מסוג bring-your-own (BYO), להריץ סוכן בהרצת ניסיון מול הקשר לדוגמה ולקרוא את נתוני ההרצות.
כל נקודות הקצה בעמוד זה יחסיות לכתובת הבסיס: https://api-eu1.joryio.com - ראו סקירת API.
אימות
כל בקשה מאומתת באמצעות מפתח API בעל ההרשאה המתאימה, או באמצעות סשן של לוח הבקרה (JWT). הסוכנים מוגבלים לסביבת העבודה - מפתח יכול לראות ולערוך רק את הסוכנים בסביבת העבודה שלו.
Authorization: Bearer your_api_key_or_jwt
Content-Type: application/json
הרשאות לכל נקודת קצה
נקודות קצה לקריאה דורשות ai_agents:read; נקודות קצה לכתיבה דורשות ai_agents:write. סשנים של לוח הבקרה יכולים להשתמש במקום זאת בהרשאת התפקיד settings:read או settings:write, המשותפת למסכי ה־AI - כל אחת מהן מעניקה גישה.
| Endpoint | Scope |
|---|---|
POST /ai-agents | ai_agents:write (או settings:write) |
GET /ai-agents | ai_agents:read (או settings:read) |
GET /ai-agents/{id} | ai_agents:read (או settings:read) |
PUT /ai-agents/{id} | ai_agents:write (או settings:write) |
POST /ai-agents/{id}/archive | ai_agents:write (או settings:write) |
DELETE /ai-agents/{id} | ai_agents:write (או settings:write) |
POST /ai-agents/{id}/test | ai_agents:write (או settings:write) |
GET /ai-agents/{id}/runs | ai_agents:read (או settings:read) |
GET /ai-agents/provider-keys | ai_agents:read (או settings:read) |
PUT /ai-agents/provider-keys/{provider} | ai_agents:write (או settings:write) |
DELETE /ai-agents/provider-keys/{provider} | ai_agents:write (או settings:write) |
POST /ai-agents/enrichment/run | ai_agents:write (או settings:write) |
GET /ai-agents/enrichment/jobs | ai_agents:read (או settings:read) |
GET /ai-agents/enrichment/jobs/{jobId} | ai_agents:read (או settings:read) |
מושגי יסוד
Model mode ו־provider
ה־modelMode של סוכן הוא managed או byo:
managed- מודל ה־Claude המתארח של Joryio. ה־providerהואjoryio. חיוב של credit אחד להרצה.byo- המפתח שלכם. ה־providerהוא אחד מ־anthropic,openai,google,azure,bedrock. רשמו תחילה את המפתח דרך נקודות הקצה של provider-keys. כל הרצה מחויבת בעמלת פלטפורמה קטנה וקבועה.
Output schema
outputSchema.type הוא string, number, boolean או json. עבור json, ספקו מערך fields של { name, type, description? } כאשר type הוא פרימיטיבי. הגדירו includeExplanation: true כדי ללכוד את נימוק המודל בשדה explanation.
Context selectors
contextSelectors הוא opt-in - הסוכן לא קורא דבר אלא אם צוין: attributeKeys, segmentIds, catalogFields, requiredCatalogFields (שדות קטלוג שחייבים להיות קיימים - ההעשרה מדלגת, ואינה מחייבת, שורה שחסר בה אחד מהם), includeBrandVoice, includeRecentEngagement ו־maskPiiKeys (מפתחות ממוסכים לפני שההקשר מגיע למודל; PII שסומן גלובלית תחת Custom Attributes גם ממוסך תמיד).
Run outcomes
כל הרצה מגיעה לתוצאה אחת: success, fallback, timeout, rate_limited, invalid_config או budget_exceeded. ראו את חוזה השגיאות.
יצירת סוכן
Endpoint
POST /ai-agents
גוף הבקשה
| שדה | Type | חובה | תיאור |
|---|---|---|---|
name | string | כן | שם קריא (עד 200). |
description | string | לא | תיאור אופציונלי (עד 1000). |
tags | string[] | לא | שמות תגיות מסביבת העבודה לצורך סינון וארגון (עד 60 תווים לכל תגית ועד 50 תגיות). |
instructions | string | כן | מטרה / הנחיות מערכת, מתובנתות ב־Liquid (עד 20000). |
modelMode | string | לא | managed (ברירת מחדל) או byo. |
provider | string | לא | joryio, anthropic, openai, google, azure, bedrock. ברירת מחדל joryio ל־managed, anthropic ל־BYO. |
model | string | לא | model id מדויק (למשל claude-opus-4-8). |
thinkingLevel | string | לא | minimal, low, medium או high. |
contextSelectors | object | לא | מה שהסוכן רשאי לקרוא (opt-in). |
outputSchema | object | לא | צורת הפלט שהמודל מוגבל אליה. ברירת מחדל { "type": "string" }. |
fallbackValue | any | לא | הערך המוחזר כשהרצה נכשלת. |
dailyCap | integer | לא | מכסת הרצות יומית לסוכן (ברירת מחדל 250000, מינימום 0). |
guardrails | object | לא | maxOutputTokens, timeoutMs, retryOnTransient. |
בקשה לדוגמה
curl -X POST https://api-eu1.joryio.com/ai-agents \
-H "Authorization: Bearer your_api_key" \
-H "Content-Type: application/json" \
-d '{
"name": "Cart subject-line writer",
"instructions": "Write a short, upbeat email subject line for the abandoned cart. Max 60 characters.",
"modelMode": "managed",
"contextSelectors": {
"attributeKeys": ["first_name", "cart_total"],
"includeBrandVoice": true
},
"outputSchema": {
"type": "json",
"fields": [{ "name": "subject", "type": "string" }],
"includeExplanation": true
},
"fallbackValue": { "subject": "You left something behind" },
"dailyCap": 50000,
"guardrails": { "timeoutMs": 20000, "retryOnTransient": true }
}'
תגובה
{
"id": "8f0e2b3a-1c4d-4e5f-9a0b-1c2d3e4f5a6b",
"organizationId": "org_123",
"workspaceId": "ws_456",
"name": "Cart subject-line writer",
"description": null,
"status": "active",
"instructions": "Write a short, upbeat email subject line for the abandoned cart. Max 60 characters.",
"modelMode": "managed",
"provider": "joryio",
"model": "",
"thinkingLevel": null,
"contextSelectors": {
"attributeKeys": ["first_name", "cart_total"],
"includeBrandVoice": true
},
"outputSchema": {
"type": "json",
"fields": [{ "name": "subject", "type": "string" }],
"includeExplanation": true
},
"fallbackValue": { "subject": "You left something behind" },
"dailyCap": 50000,
"guardrails": { "timeoutMs": 20000, "retryOnTransient": true },
"createdBy": "user_789",
"createdAt": "2026-07-11T09:00:00.000Z",
"updatedAt": "2026-07-11T09:00:00.000Z"
}
רשימת סוכנים
Endpoint
GET /ai-agents
פרמטרים בשאילתה
| פרמטר | Type | ברירת מחדל | תיאור |
|---|---|---|---|
status | string | - | מסנן אופציונלי: active או archived. |
הסוכנים מוחזרים לפי סדר העדכון האחרון תחילה.
בקשה לדוגמה
curl -X GET "https://api-eu1.joryio.com/ai-agents?status=active" \
-H "Authorization: Bearer your_api_key"
תגובה
[
{
"id": "8f0e2b3a-1c4d-4e5f-9a0b-1c2d3e4f5a6b",
"name": "Cart subject-line writer",
"status": "active",
"modelMode": "managed",
"provider": "joryio",
"dailyCap": 50000,
"updatedAt": "2026-07-11T09:00:00.000Z"
}
]
קבלת סוכן בודד
Endpoint
GET /ai-agents/{id}
פרמטר הנתיב {id} הוא ה־UUID של הסוכן.
בקשה לדוגמה
curl -X GET https://api-eu1.joryio.com/ai-agents/8f0e2b3a-1c4d-4e5f-9a0b-1c2d3e4f5a6b \
-H "Authorization: Bearer your_api_key"
מחזיר את אובייקט הסוכן המלא (באותו מבנה כמו תגובת היצירה). מחזיר 404 אם הסוכן אינו קיים בסביבת העבודה הזו.
עדכון סוכן
Endpoint
PUT /ai-agents/{id}
עדכון חלקי - שלחו רק את השדות שברצונכם לשנות. כל שדות היצירה מתקבלים, בתוספת status (active או archived).
בקשה לדוגמה
curl -X PUT https://api-eu1.joryio.com/ai-agents/8f0e2b3a-1c4d-4e5f-9a0b-1c2d3e4f5a6b \
-H "Authorization: Bearer your_api_key" \
-H "Content-Type: application/json" \
-d '{
"dailyCap": 100000,
"guardrails": { "timeoutMs": 15000, "retryOnTransient": false }
}'
מחזיר את אובייקט הסוכן המעודכן.
ארכוב סוכן
ארכוב רך של סוכן: ה־status הופך ל־archived, מה שעוצר את השימוש אך שומר את היסטוריית ההרצות.
Endpoint
POST /ai-agents/{id}/archive
בקשה לדוגמה
curl -X POST https://api-eu1.joryio.com/ai-agents/8f0e2b3a-1c4d-4e5f-9a0b-1c2d3e4f5a6b/archive \
-H "Authorization: Bearer your_api_key"
מחזיר את אובייקט הסוכן המאורכב ("status": "archived").
מחיקת סוכן
Endpoint
DELETE /ai-agents/{id}
בקשה לדוגמה
curl -X DELETE https://api-eu1.joryio.com/ai-agents/8f0e2b3a-1c4d-4e5f-9a0b-1c2d3e4f5a6b \
-H "Authorization: Bearer your_api_key"
תגובה
{ "success": true }
בדיקה (תצוגה מקדימה) של סוכן
הרצה מדומה של הסוכן מול הקשר לדוגמה שאתם מספקים. ההרצה משתמשת במפתח הרצה חדש ובמשטח test, ולכן לעולם אינה נספרת מול מסע אמיתי. היא מחזירה רק את התוצאה שמוצגת ללקוח, ללא שדות מדידה.
Endpoint
POST /ai-agents/{id}/test
גוף הבקשה
| שדה | Type | חובה | תיאור |
|---|---|---|---|
attributes | object | לא | attributes לדוגמה של איש קשר, לפי שם. |
segmentMemberships | string[] | לא | segment memberships לדוגמה. |
catalogRecord | object | לא | רשומת קטלוג/entity לדוגמה שמועשרת. |
engagement | object | לא | סיכום engagement אחרון לדוגמה. |
בקשה לדוגמה
curl -X POST https://api-eu1.joryio.com/ai-agents/8f0e2b3a-1c4d-4e5f-9a0b-1c2d3e4f5a6b/test \
-H "Authorization: Bearer your_api_key" \
-H "Content-Type: application/json" \
-d '{
"attributes": { "first_name": "Dana", "cart_total": 249.90 },
"segmentMemberships": ["vip"]
}'
תגובה
{
"outcome": "success",
"output": { "subject": "Dana, your cart misses you" },
"explanation": "Used the first name and an upbeat tone from the brand voice."
}
outcome הוא אחד מ־success, fallback, timeout, rate_limited, invalid_config או budget_exceeded. explanation הוא null כאשר ה־schema אינו כולל אותו.
רשימת הרצות של סוכן
מחזיר run traces אחרונים לסוכן, החדשים תחילה.
Endpoint
GET /ai-agents/{id}/runs
פרמטרים בשאילתה
| פרמטר | Type | ברירת מחדל | תיאור |
|---|---|---|---|
limit | number | 50 | שורות להחזרה (1–200). |
בקשה לדוגמה
curl -X GET "https://api-eu1.joryio.com/ai-agents/8f0e2b3a-1c4d-4e5f-9a0b-1c2d3e4f5a6b/runs?limit=25" \
-H "Authorization: Bearer your_api_key"
תגובה
{
"rows": [
{
"id": "run_abc123",
"agentId": "8f0e2b3a-1c4d-4e5f-9a0b-1c2d3e4f5a6b",
"surface": "journey",
"provider": "joryio",
"model": "claude-opus-4-8",
"modelMode": "managed",
"inputTokens": 420,
"outputTokens": 28,
"latencyMs": 1180,
"outcome": "success",
"output": { "subject": "Dana, your cart misses you" },
"explanation": "Used the first name and an upbeat tone.",
"error": null,
"createdAt": "2026-07-11T09:05:00.000Z"
}
]
}
ה־trace שומר רק הפניות לקלט (איזה execution, node, רשומה או משתמש) - לעולם לא את טקסט ה־prompt הגולמי.
רשימת מפתחות ספק BYO
מחזיר את מפתחות הספק מסוג bring-your-own שרשומים בסביבת העבודה. ערכי פרטי הגישה לעולם אינם מוחזרים - האובייקט credentials תמיד ריק.
Endpoint
GET /ai-agents/provider-keys
בקשה לדוגמה
curl -X GET https://api-eu1.joryio.com/ai-agents/provider-keys \
-H "Authorization: Bearer your_api_key"
תגובה
[
{
"id": "key_111",
"provider": "openai",
"credentials": {},
"label": "Production OpenAI",
"status": "active",
"lastUsedAt": "2026-07-11T08:00:00.000Z",
"lastError": null,
"createdAt": "2026-07-01T00:00:00.000Z",
"updatedAt": "2026-07-11T08:00:00.000Z"
}
]
Upsert של מפתח ספק BYO
יוצר או מחליף את המפתח של ספק אחד. יש מפתח אחד לכל צירוף (workspace, provider). הספק המנוהל joryio אינו מקבל מפתח, ולכן בקשה כזו נדחית.
Endpoint
PUT /ai-agents/provider-keys/{provider}
פרמטר הנתיב {provider} הוא אחד מ־anthropic, openai, google, azure, bedrock.
גוף הבקשה
| שדה | Type | חובה | תיאור |
|---|---|---|---|
credentials | object | כן | פרטי גישה ייעודיים לספק (למשל { "apiKey": "..." }; Azure ו־Bedrock דורשים שדות נוספים). מוצפנים במצב מנוחה ולעולם אינם מוחזרים. |
label | string | לא | תווית אופציונלית (עד 120). |
בקשה לדוגמה
curl -X PUT https://api-eu1.joryio.com/ai-agents/provider-keys/openai \
-H "Authorization: Bearer your_api_key" \
-H "Content-Type: application/json" \
-d '{
"credentials": { "apiKey": "sk-your-openai-key" },
"label": "Production OpenAI"
}'
תגובה
{
"id": "key_111",
"provider": "openai",
"credentials": {},
"label": "Production OpenAI",
"status": "active",
"lastUsedAt": null,
"lastError": null,
"createdAt": "2026-07-11T09:10:00.000Z",
"updatedAt": "2026-07-11T09:10:00.000Z"
}
מחיקת מפתח ספק BYO
Endpoint
DELETE /ai-agents/provider-keys/{provider}
בקשה לדוגמה
curl -X DELETE https://api-eu1.joryio.com/ai-agents/provider-keys/openai \
-H "Authorization: Bearer your_api_key"
תגובה
{ "success": true }
הרצת העשרת קטלוג
מריץ סוכן מסוג generate-only על רשומות של ישות מותאמת וכותב כל פלט לשדה יעד - למשל תיאורי מוצר, תגיות או קטגוריה מנורמלת. העבודה אסינכרונית ונכנסת לתור: נקודת הקצה יוצרת משימה (status: queued), מכניסה אותה לתור ומחזירה מיד. קטלוג גדול (עד 100 אלף שורות) מעובד מחוץ לנתיב הבקשה. בצעו תשאול מחזורי של קבלת משימת העשרה כדי לעקוב אחר ההתקדמות. העבודה אידמפוטנטית לכל רשומה (מפתח ההרצה הוא jobId:recordId), ולכן הרצה חוזרת לעולם אינה מחייבת שוב רשומה שכבר הועשרה.
Endpoint
POST /ai-agents/enrichment/run
גוף הבקשה
| שדה | Type | חובה | תיאור |
|---|---|---|---|
agentId | string | כן | הסוכן להרצה (חייב להיות סוכן active בסביבת העבודה הזו). |
entityDefinitionId | string | כן | הגדרת הישות המותאמת שרשומותיה מועשרות. |
targetField | string | כן | שדה הרשומה שהפלט נכתב אליו (חייב להיות שדה מוצהר על ה־entity). |
filter | object | לא | מסנן אופציונלי בסגנון MongoDB לצמצום הרשומות המועשרות. |
limit | integer | לא | מספר הרשומות המרבי לעיבוד במשימה זו (עד 100000, עם מגבלה קשיחה בצד השרת). |
בקשה לדוגמה
curl -X POST https://api-eu1.joryio.com/ai-agents/enrichment/run \
-H "Authorization: Bearer your_api_key" \
-H "Content-Type: application/json" \
-d '{
"agentId": "8f0e2b3a-1c4d-4e5f-9a0b-1c2d3e4f5a6b",
"entityDefinitionId": "product",
"targetField": "ai_description",
"filter": { "category": "shoes" },
"limit": 200
}'
תגובה
המשימה נמצאת בתור. בעת השליחה status הוא queued; הספירות מתעדכנות תוך כדי הרצת המשימה. בצעו תשאול מחזורי של קבלת משימת העשרה כדי לעקוב עד לסיום.
{
"jobId": "job_9a8b7c",
"status": "queued",
"agentId": "8f0e2b3a-1c4d-4e5f-9a0b-1c2d3e4f5a6b",
"entityDefinitionId": "product",
"targetField": "ai_description",
"counts": {
"total": 200,
"processed": 0,
"succeeded": 0,
"failed": 0,
"skipped": 0
},
"error": null,
"createdAt": "2026-07-11T09:20:00.000Z",
"updatedAt": "2026-07-11T09:20:00.000Z"
}
קבלת משימת העשרה
תשאול מחזורי של המצב והספירות של משימת העשרה אחת.
Endpoint
GET /ai-agents/enrichment/jobs/{jobId}
פרמטר הנתיב {jobId} הוא מזהה המשימה שהוחזר מהרצת העשרת קטלוג.
בקשה לדוגמה
curl -X GET https://api-eu1.joryio.com/ai-agents/enrichment/jobs/job_9a8b7c \
-H "Authorization: Bearer your_api_key"
תגובה
status הוא אחד מ־queued, running, completed או failed. error מאוכלס רק כאשר ה־job כולו נכשל.
{
"jobId": "job_9a8b7c",
"status": "completed",
"agentId": "8f0e2b3a-1c4d-4e5f-9a0b-1c2d3e4f5a6b",
"entityDefinitionId": "product",
"targetField": "ai_description",
"counts": {
"total": 200,
"processed": 200,
"succeeded": 194,
"failed": 2,
"skipped": 4
},
"error": null,
"createdAt": "2026-07-11T09:20:00.000Z",
"updatedAt": "2026-07-11T09:22:30.000Z"
}
מחזיר 404 אם המשימה אינה קיימת בסביבת העבודה הזו. דורש ai_agents:read (או settings:read).
רשימת משימות העשרה
מחזיר את משימות ההעשרה האחרונות בסביבת העבודה, החדשות תחילה, לצורך מעקב אחר התקדמות והיסטוריה.
Endpoint
GET /ai-agents/enrichment/jobs
פרמטרים בשאילתה
| פרמטר | Type | ברירת מחדל | תיאור |
|---|---|---|---|
limit | integer | 20 | שורות להחזרה (החדשות תחילה). |
בקשה לדוגמה
curl -X GET "https://api-eu1.joryio.com/ai-agents/enrichment/jobs?limit=20" \
-H "Authorization: Bearer your_api_key"
תגובה
מערך של משימות, כל אחת באותו מבנה כמו קבלת משימת העשרה.
[
{
"jobId": "job_9a8b7c",
"status": "completed",
"agentId": "8f0e2b3a-1c4d-4e5f-9a0b-1c2d3e4f5a6b",
"entityDefinitionId": "product",
"targetField": "ai_description",
"counts": {
"total": 200,
"processed": 200,
"succeeded": 194,
"failed": 2,
"skipped": 4
},
"error": null,
"createdAt": "2026-07-11T09:20:00.000Z",
"updatedAt": "2026-07-11T09:22:30.000Z"
}
]
דורש ai_agents:read (או settings:read).
תגובות שגיאה
כל השגיאות משתמשות במבנה הסטנדרטי - אין אוסף נפרד של קודי שגיאה לקריאה ממוכנת; השתמשו בקוד המצב של HTTP יחד עם השדה message. ראו תגובת שגיאה בסקירת ה־API.
{
"statusCode": 404,
"message": "AI agent 8f0e2b3a-1c4d-4e5f-9a0b-1c2d3e4f5a6b not found",
"timestamp": "2026-07-11T09:20:00.000Z",
"path": "/ai-agents/8f0e2b3a-1c4d-4e5f-9a0b-1c2d3e4f5a6b"
}
סטטוסים בולטים ב-API הזה:
| סטטוס | מתי |
|---|---|
400 | תצורה לא תקינה - למשל "instructions are required", "No BYO key configured for provider 'openai' - add a key before using it in BYO mode", "status must be one of: active, draft, archived" |
401 | מפתח API חסר או לא תקין |
403 | למפתח חסרה הרשאת ai_agents:read / ai_agents:write הנדרשת |
404 | סוכן, משימת העשרה או מפתח ספק BYO לא נמצאו |