דלג לתוכן הראשי

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 - כל אחת מהן מעניקה גישה.

EndpointScope
POST /ai-agentsai_agents:write (או settings:write)
GET /ai-agentsai_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}/archiveai_agents:write (או settings:write)
DELETE /ai-agents/{id}ai_agents:write (או settings:write)
POST /ai-agents/{id}/testai_agents:write (או settings:write)
GET /ai-agents/{id}/runsai_agents:read (או settings:read)
GET /ai-agents/provider-keysai_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/runai_agents:write (או settings:write)
GET /ai-agents/enrichment/jobsai_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חובהתיאור
namestringכןשם קריא (עד 200).
descriptionstringלאתיאור אופציונלי (עד 1000).
tagsstring[]לאשמות תגיות מסביבת העבודה לצורך סינון וארגון (עד 60 תווים לכל תגית ועד 50 תגיות).
instructionsstringכןמטרה / הנחיות מערכת, מתובנתות ב־Liquid (עד 20000).
modelModestringלאmanaged (ברירת מחדל) או byo.
providerstringלאjoryio, anthropic, openai, google, azure, bedrock. ברירת מחדל joryio ל־managed, anthropic ל־BYO.
modelstringלאmodel id מדויק (למשל claude-opus-4-8).
thinkingLevelstringלאminimal, low, medium או high.
contextSelectorsobjectלאמה שהסוכן רשאי לקרוא (opt-in).
outputSchemaobjectלאצורת הפלט שהמודל מוגבל אליה. ברירת מחדל { "type": "string" }.
fallbackValueanyלאהערך המוחזר כשהרצה נכשלת.
dailyCapintegerלאמכסת הרצות יומית לסוכן (ברירת מחדל 250000, מינימום 0).
guardrailsobjectלא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ברירת מחדלתיאור
statusstring-מסנן אופציונלי: 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חובהתיאור
attributesobjectלאattributes לדוגמה של איש קשר, לפי שם.
segmentMembershipsstring[]לאsegment memberships לדוגמה.
catalogRecordobjectלארשומת קטלוג/entity לדוגמה שמועשרת.
engagementobjectלאסיכום 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ברירת מחדלתיאור
limitnumber50שורות להחזרה (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חובהתיאור
credentialsobjectכןפרטי גישה ייעודיים לספק (למשל { "apiKey": "..." }; Azure ו־Bedrock דורשים שדות נוספים). מוצפנים במצב מנוחה ולעולם אינם מוחזרים.
labelstringלאתווית אופציונלית (עד 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חובהתיאור
agentIdstringכןהסוכן להרצה (חייב להיות סוכן active בסביבת העבודה הזו).
entityDefinitionIdstringכןהגדרת הישות המותאמת שרשומותיה מועשרות.
targetFieldstringכןשדה הרשומה שהפלט נכתב אליו (חייב להיות שדה מוצהר על ה־entity).
filterobjectלאמסנן אופציונלי בסגנון MongoDB לצמצום הרשומות המועשרות.
limitintegerלאמספר הרשומות המרבי לעיבוד במשימה זו (עד 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ברירת מחדלתיאור
limitinteger20שורות להחזרה (החדשות תחילה).

בקשה לדוגמה

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 לא נמצאו

הצעדים הבאים