# אפליקציות ורכיבים שמורים

> מצאו אפליקציות ורכיבים שמורים ב-Nodaro, בדקו את הקלטים שלהם והריצו אותם דרך עוזר AI, כולל ניסיון חוזר להרצות שנכשלו, עם run_app ו-retry_app_run.

Source: https://nodaro.ai/he/docs/mcp/tools/apps-and-components

**כלי האפליקציות והרכיבים השמורים** מאפשרים לעוזר AI להשתמש בתהליכים שאנשים פרסמו. [אפליקציה](https://nodaro.ai/docs/concepts/apps) היא תהליך שפורסם עם טופס פשוט, כגון שחזור תמונות או עריכה בנושא מסוים, ו[רכיב שמור](https://nodaro.ai/docs/concepts/components-and-sub-workflows) הוא אבן בניין שפורסמה. העוזר מחפש אפליקציה או רכיב שמור, קורא את הקלטים שלהם ומריץ אותם עם הקרדיטים שלכם.

אפליקציות מכסות הרבה בקשות שאף כלי יצירה יחיד לא מטפל בהן, כגון המרות לא שגרתיות, עריכות בנושא מסוים ופייפליינים של כמה שלבים. עוזר AI צריך לחפש באפליקציות לפני שהוא עונה שאי אפשר לעשות משהו.

## `list_apps`
מחפש באפליקציות שפורסמו: בשוק הציבורי, או באפליקציות שלכם.

**הרשאה:** `apps:read`. **קרדיטים:** חינם.

| פרמטר | סוג | הערות |
| --- | --- | --- |
| `scope` | string | `public` (ברירת המחדל) לשוק, או `mine` לאפליקציות שלכם. |
| `search` | string | נושא לחיפוש, עד 100 תווים. |
| `category` | string | קטגוריה, עד 50 תווים. |
| `limit` | integer | מ-1 עד 50. |
| `cursor` | string | ה-cursor מהעמוד הקודם. |

**מה חוזר:** האפליקציות שמתאימות לחיפוש, עם המזהים בכתובת (slug) שלהן. השדה `estimated_credits` של כל אפליקציה הוא המחיר הרשום שלה. כשהמחיר נקבע לפי האורך של הקלטה שנותנים לאפליקציה, כגון רינדור של פרק שלם ברכיב החלת רשימת עריכה, `estimated_credits` הוא החלק הקבוע ו-`per_minute_credits` הוא הקרדיטים לכל דקה של ההקלטה. כשלאפליקציה יש קלט רשימה שממלאים, `per_item_credits` הוא מה שמוסיף כל פריט מעבר לפריטים שהיוצר שמר. כששני השדות האלה לא רלוונטיים, הערך שלהם הוא `0` או שהם חסרים.

המחיר הרשום הוא טווח. השדות שלמעלה הם מחיר ה״החל מ״, בהגדרות השמורות של האפליקציה. השדות `max_estimated_credits`, `max_per_minute_credits` ו-`max_per_item_credits` הם מחיר ה״עד״: הסכום הגבוה ביותר שהרצה יכולה לעלות, בכל הבחירות שעומדות לרשות מי שמשתמש באפליקציה. הם מופיעים רק כשהם שונים ממחיר ה״החל מ״. באפליקציה שפורסמה לפני שהטווח נוסף, הם מופיעים רק אחרי הפרסום הבא שלה.

כשמחיר רשום כולל קריאה ל-LLM שמחויבת לפי שימוש, בשורה מופיע `estimated_credits_is_estimate: true`. המספר הוא אז המחיר של קריאה טיפוסית למודל, וההרצה מחויבת לפי הטוקנים שהקריאה השתמשה בהם בפועל, ולכן הציגו את המחיר כ-`≈N`. במחיר קבוע השדה לא מופיע.

## `get_app_inputs`
מחזיר את הקלטים של אפליקציה, אותו טופס שמוצג בדף של האפליקציה. קראו לכלי לפני `run_app` כדי לגלות את המפתחות של הקלטים.

**הרשאה:** `apps:read`. **קרדיטים:** חינם.

| פרמטר | סוג | הערות |
| --- | --- | --- |
| `slug` | string | **נדרש.** המזהה בכתובת של האפליקציה, למשל `photo-restoration`. |

**מה חוזר:** ה-`slug`, ה-`name` וה-`description` של האפליקציה, ופריט אחד לכל קלט, עם ה-`key`, ה-`label` וה-`type` שלו (`image`, `video`, `audio`, `text`, `select`, `number`, `boolean`, `list` או `color`), ציון אם הוא `required`, וה-`options` של קלט בחירה.

- **מחוון שהאפליקציה חושפת**, כגון **יציבות** של רכיב טקסט לדיבור, **טמפרטורה** של LLM או **משך**, הוא `type: "number"` עם ה-`min`, ה-`max` וה-`step` של המחוון עצמו. הכלי `run_app` מקבל בשבילו מספר או מחרוזת מספרית.
- **הגדרה מהירה שהאפליקציה חושפת**, כגון המודל, הרזולוציה, האורך, יחס הגובה־רוחב או הבחירה **טיוטה** של רכיב, מקבלת סוג לפי סוג הערכים שלה. היא `select` שה-`options` שלו הם הערכים שלה, `number` עם `min` ו-`max` להגדרה שמקבלת כל ערך בטווח, או `boolean`, כגון **טיוטה** או **כלי (ללא שירה)**. כשהאפשרויות תלויות במודל של הרכיב, `options` מפרט את הערכים של כל המודלים, וה-`description` מציין זאת. בחרו ערך שהמודל של הרכיב מקבל. בקלטים האלה, `run_app` הופך מחרוזת מספרית למספר, ו-`"true"` או `"false"` לערך בוליאני. ערך שלא נמצא ברשימה קבועה נדחה עם `400 validation_error`.
- **קלט של רכיב [כתובת וידאו](https://nodaro.ai/docs/nodes/automate/video-url)** הוא `type: "video"` ו-`required: true`. הערך שלו הוא קישור לסרטון: הדף של הסרטון, או קישור ציבורי אחר באינטרנט. ערך שהוא לא קישור לאינטרנט נדחה עם `400 locked_field`. מאתר ש-Nodaro קורא בו קודם את אורך הסרטון, סרטון של 4 דקות או יותר יורד רק כקטע שאתם מציינים ב-`inputOverrides`, עם `sectionStartSec` ו-`sectionEndSec` ברכיב. הרצה בלי הקטע נדחית לפני כל חיוב.

## `run_app`
מריץ אפליקציה שפורסמה. אתם משלמים את הקרדיטים של ההרצה.

**הרשאה:** `workflows:execute`. **קרדיטים:** הקרדיטים של הרכיבים שרצים בתוך האפליקציה.

| פרמטר | סוג | הערות |
| --- | --- | --- |
| `slug` | string | **נדרש.** המזהה בכתובת של האפליקציה. |
| `inputs` | object | אובייקט שטוח שהמפתחות שלו הם המפתחות של הקלטים מ-`get_app_inputs`. השמיטו אותו כדי להשתמש בערכי ברירת המחדל. |
| `inputOverrides` | object | מתקדם. שדות גולמיים של רכיבים, לפי מזהה רכיב ושם שדה, שמוחלים מעל `inputs`, למשל `{ "n1": { "promptPrefix": "..." } }`. שדה שמוגדר ל-`null` מתרוקן בהרצה הזו: הרכיב רץ בלי ערך בשדה, ולא עם הערך שהיוצר שמר. |
| `client_request_id` | string | אסימון ניסיון חוזר: בין 8 ל-128 תווים של אותיות, ספרות ו-`_ - . :`. אם אתם מנסים שוב אחרי פסק זמן, שלחו את אותו ערך, כדי ש-Nodaro לא יתחיל את ההרצה ולא יחייב אותה פעמיים. |

**מה חוזר:** מזהה הרצה, וה-`runId` של הרצת האפליקציה. בדקו את מצב ההרצה עם [`get_app_run`](https://nodaro.ai/docs/mcp/tools/gallery-and-assets#get_app_run). כשההרצה נכשלת, הכלי [`retry_app_run`](#retry_app_run) מקבל את ה-`runId`.

הפרמטר `inputOverrides` לא יכול לקבוע לאן פלט נשלח, כגון הכתובת של רכיב **פלט Webhook**, החשבון של רכיב פרסום או היעד של רכיב גריפה. הרצה שמנסה לעשות זאת נדחית עם `400 locked_field`.

## `retry_app_run`
מנסה שוב הרצת אפליקציה **שנכשלה**, מהמקום שבו היא נעצרה. זה הכפתור **נסו שוב** בדף של האפליקציה. רק השלבים שההרצה לא השלימה רצים, ורק עליהם משלמים. כל שלב שההרצה השלימה מעביר הלאה את התוצאה שלו. רכיב קליפ UGC שנכשל מרנדר רק את הקליפים שהוא לא סיים. הניסיון החוזר מריץ את גרסת האפליקציה שההרצה הריצה, עם הקלטים שההרצה השתמשה בהם, ולא מקבל קלטים משלו.

**הרשאה:** `workflows:execute`. **קרדיטים:** השלבים שרצים שוב, ועוד תוספת המחיר של היוצר על האפליקציה.

| פרמטר | סוג | הערות |
| --- | --- | --- |
| `slug` | string | **נדרש.** המזהה בכתובת של האפליקציה. |
| `run_id` | string | **נדרש.** המזהה של הרצת האפליקציה: ה-`runId` מ-`run_app`, או המזהה שמופיע ברמז להמשך ההרצה. |
| `version` | integer | גרסת האפליקציה שאתם מצפים שהניסיון החוזר יריץ. ברירת המחדל היא הגרסה האחרונה של האפליקציה. שלחו את הגרסה של ההרצה עצמה כדי להמשיך עליה אחרי שהאפליקציה השתנתה. |
| `confirm` | boolean | הערך `true` רק אחרי שהקרדיטים שבאומדן אושרו בשיחה הזו. |

**מה חוזר:** בלי `confirm`, אומדן מחיר, ושום דבר לא מתחיל. באומדן נמצאים השלבים שירוצו שוב, המחיר (`estimatedCredits`, כולל תוספת המחיר של היוצר), `reusedClips` ו-`sufficient`. השדה `sufficient` מציין אם היתרה והקרדיטים לאפליקציות מכסים את הניסיון החוזר. השדה `appCreditsAllowance` מופיע כשהקרדיטים לאפליקציות הם מה שעוצר את הניסיון החוזר, והאומדן מציין זאת. הציגו את האומדן, וקראו שוב עם `confirm: true` רק אחרי שהוא אושר. אז הכלי נותן אומדן נוסף, שגם בודק את ההרצה, ומתחיל את הניסיון החוזר. הכלי מחזיר את מזהה ההרצה: בדקו את הסטטוס שלה מדי כמה שניות עם [`get_app_run`](https://nodaro.ai/docs/mcp/tools/gallery-and-assets#get_app_run).

- **ניסיון חוזר אחד בכל פעם.** קריאה שנייה בזמן שהניסיון החוזר עדיין ממתין נדחית עם `already_running`, והשגיאה מציינת את ההרצה שצריך לבדוק.
- **אפליקציה שהשתנתה.** כשהאפליקציה השתנתה מאז ההרצה, ניסיון חוזר רגיל נדחה עם `app_run_version_changed`, שמציין את הגרסה של ההרצה ואת הגרסה של האפליקציה. התחילו את ההרצה מחדש עם `run_app`, או העבירו את הגרסה של ההרצה עצמה כדי להמשיך עליה.
- **הרצות שמתחילות מחדש.** כשהרצה הושלמה או נעצרה במקום להיכשל, או כשהגרסה שלה כבר לא זמינה, מתחילים אותה מחדש עם `run_app`. השגיאה מציינת איזה מהמקרים חל.
- **תצוגה מקדימה.** ניסיון חוזר שהיה נעצר ברינדור של תצוגה מקדימה נדחה עם `preview_review_required`. נסו שוב מהדף של האפליקציה, שבו אדם יכול לבדוק את התצוגה המקדימה.
- **קרדיטים.** דחייה בגלל קרדיטים שומרת על ההודעה של הנתיב עצמו, על הקרדיטים לאפליקציות או על היתרה.

כל הדחיות מפורטות בסעיף [ניסיון חוזר של הרצה שנכשלה](https://nodaro.ai/docs/developers/embed/miniapps#retry-a-failed-run) בדף הטמעת מיני־אפליקציה.

## `delete_app_run`
מעביר הרצת אפליקציה לארכיון שלכם. אפשר לשחזר אותה או למחוק אותה לצמיתות בכתובת [app.nodaro.ai/archived-runs](https://app.nodaro.ai/archived-runs). אפשר למחוק הרצה לצמיתות רק אחרי שהיא הסתיימה או נעצרה.

**הרשאה:** `workflows:execute`. **קרדיטים:** חינם.

| פרמטר | סוג | הערות |
| --- | --- | --- |
| `slug` | string | **נדרש.** המזהה בכתובת של האפליקציה, החלק האחרון בכתובת ה-URL שלה. |
| `runId` | string | **נדרש.** מזהה ההרצה. |

**מה חוזר:** אישור.

## `list_components`
מחפש ברכיבים שמורים שפורסמו: בשוק הציבורי, או ברכיבים השמורים שלכם. כדאי להשתמש בו כשמבקשים רכיב שמור בשמו, או כשמבקשים פייפליין של כמה שלבים שתואם רכיב שמור מוכר.

**הרשאה:** `workflows:read`. **קרדיטים:** חינם.

| פרמטר | סוג | הערות |
| --- | --- | --- |
| `scope` | string | `public` (ברירת המחדל) לשוק, או `mine` לרכיבים השמורים שלכם. |
| `search` | string | נושא לחיפוש, עד 100 תווים. |
| `limit` | integer | מ-1 עד 50. |
| `cursor` | string | ה-cursor מהעמוד הקודם. |

**מה חוזר:** הרכיבים השמורים שמתאימים לחיפוש, עם המזהים בכתובת שלהם. בכל אחד מהם נמצאים `estimated_credits`, `per_minute_credits` ו-`per_item_credits`, ושדות ה-`max_` המתאימים, באותה משמעות כמו ב-`list_apps`. בשורה שיש בה אומדן של קריאה ל-LLM שמחויבת לפי שימוש מופיע `estimated_credits_is_estimate: true`, כמו ב-`list_apps`.

## `get_component_inputs`
מחזיר את הקלטים של רכיב שמור. קראו לכלי לפני `run_component` כדי לגלות את המפתחות של הקלטים.

**הרשאה:** `workflows:read`. **קרדיטים:** חינם.

| פרמטר | סוג | הערות |
| --- | --- | --- |
| `component_id` | string | **נדרש.** המזהה בכתובת של הרכיב השמור. |

**מה חוזר:** פריט אחד לכל קלט, עם ה-`key`, ה-`label` וה-`type` שלו, וציון אם הוא `required`.

## `run_component`
מריץ רכיב שמור שפורסם.

**הרשאה:** `workflows:execute`. **קרדיטים:** הקרדיטים של הרכיבים שרצים בתוך הרכיב השמור.

| פרמטר | סוג | הערות |
| --- | --- | --- |
| `component_id` | string | **נדרש.** המזהה בכתובת של הרכיב השמור. |
| `inputs` | object | אובייקט שטוח שהמפתחות שלו הם המפתחות של הקלטים מ-`get_component_inputs`. השמיטו אותו כדי להשתמש בערכי ברירת המחדל. |
| `client_request_id` | string | אסימון ניסיון חוזר: בין 8 ל-128 תווים של אותיות, ספרות ו-`_ - . :`. אם אתם מנסים שוב אחרי פסק זמן, שלחו את אותו ערך. |

**מה חוזר:** מזהה משימה. כשהמשימה מסתיימת, הפלטים של הרכיב השמור נמצאים ב-`output_data` שלה. בלקוחות עם MCP Apps, כרטיס המשימה מציג את הפלטים אחד מתחת לשני.

## שאלות נפוצות

### מה ההבדל בין אפליקציה לרכיב שמור?

אפליקציה היא תהליך שפורסם ורץ בעצמו מטופס פשוט. רכיב שמור הוא אבן בניין שפורסמה, ותהליכים אחרים משתמשים בה שוב. כשאין לבקשה כלי ישיר, עוזרי AI מחפשים קודם אפליקציה.

### מי משלם על הרצת אפליקציה שעוזר AI התחיל?

אתם משלמים על הרצת אפליקציה שעוזר AI התחיל. הכלים run_app ו-run_component מוציאים קרדיטים מהחשבון שלכם, במחירים של הרכיבים שבתוך האפליקציה או הרכיב השמור.

### האם עוזר AI יכול לשנות הגדרות מוסתרות של אפליקציה?

רק חלק מהן. הפרמטר inputOverrides יכול לקבוע שדות גולמיים של רכיבים, כמו הטקסט שמתווסף לפני פרומפט, אבל הוא לא יכול לשנות לאן פלט נשלח, כמו כתובת Webhook או חשבון ברשת חברתית. הרצות כאלה נדחות.

### איך עוזר AI מנסה שוב הרצת אפליקציה שנכשלה?

העוזר קורא לכלי retry_app_run עם המזהה בכתובת של האפליקציה ועם מזהה ההרצה. הקריאה הראשונה רק מחזירה את השלבים ואת אומדן המחיר. אחרי שאתם מאשרים, העוזר קורא שוב עם confirm true, ורק השלבים שההרצה לא השלימה רצים, ורק עליהם משלמים.

### איך מוחקים הרצת אפליקציה דרך העוזר?

קראו לכלי delete_app_run עם המזהה בכתובת של האפליקציה ועם מזהה ההרצה. ההרצה עוברת לארכיון שלכם, ושם אפשר לשחזר אותה או למחוק אותה לצמיתות.