כשמגדירים תסריט הפעלה, אפשר לספק בלוקים של קוד, שהם קוד Python מוטבע שאפשר להשתמש בו כדי לשלוט טוב יותר בהתנהגות של הסוכן. הקוד הזה מורכב מפונקציות עם מעצבים מיוחדים ומפונקציות עזר שנדרשות לכם.
כשכותבים את הקוד, אפשר להשתמש בספריית המערכת של בלוק הקוד כדי לשלוט בהתנהגות של הסוכן.
מגבלות
ההגבלות הבאות חלות:
- בלוקים של קוד לא יכולים להכיל אובייקטים ששומרים נתונים. עם זאת, אפשר להשתמש בכלים כדי לשמור את הנתונים ולשמור על המצב.
- בלוקים של קוד לא יכולים לבצע שיחות מרחוק באופן ישיר. לדוגמה, אי אפשר להשתמש בספריית הבקשות של Python. עם זאת, אפשר להשתמש בכלים כדי לבצע שיחות מרחוק באופן עקיף.
- שמות משאבים שמומרים לשמות ב-Python חייבים להיות שמות תקינים ב-Python.
- אי אפשר לכתוב פרמטרים של סשן בבלוקים של קוד, אלא אם מתבצע מעבר בין רכיבים בתהליך.
פעולות ישירות
פעולות ישירות דומות לפעולות בכלי. יש להם סכימת קלט ופלט מוגדרת, שנקבעת על ידי חתימת פונקציית Python, כולל הערות על סוגים ומחרוזת docstring. בדומה לקריאות לכלים, מודל ה-LLM לא מודע לקוד שמיישם את הפעולה.
דוגמה:
@Action
def is_prime(n: int) -> bool:
"""Returns true if n is prime."""
if not isinstance(n, int) or n < 2:
return False
for i in range(2, int(n ** 0.5) + 1):
if n % i == 0:
return False
return True
בפונקציה הזו, מודל ה-LLM יקבל מידע על הפעולה, הקלט והפלט שלה.
כדי להתייחס לפעולה מוטמעת בהוראות של ספר ההפעלה, פשוט מציינים את שם הפעולה במירכאות הפוכות ומתארים איך צריך להשתמש בה.
דוגמה לפעולה מוטמעת place_order:
Take the customer's order, then call the `place_order` action when the order is ready.
כדי ליצור דוגמאות שמשתמשות בפעולות מוטבעות, צריך להשתמש בסוג הכלי inline-action בקטע Input & Output (קלט ופלט).
מידע נוסף מופיע במאמרי העזרה בנושא @Action.
פונקציות טריגר
פונקציות טריגר משמשות להגדרת פעולות מותנות בקוד.
מצהירים על פונקציות של טריגר באמצעות דקורטורים. אפשר להשתמש בפונקציות הבאות של מעצבי טריגר:
| Decorator | פרמטרים של Decorator | תיאור |
|---|---|---|
| @EventTrigger | event: str, condition: str, כש-condition הוא אופציונלי |
מופעל על ידי אירוע |
| @BeforeModelTrigger | condition: str, כש-condition הוא אופציונלי |
מופעל בכל פעם לפני שמודל ה-LLM חוזה את הפעולה הבאה. |
| @BeforeActionTrigger | condition: str, כש-condition הוא אופציונלי |
מופעל בכל פעם לפני שמודל ה-LLM מבצע פעולה. |
| @BeforePlaybookTrigger | condition: str, כש-condition הוא אופציונלי |
מופעל בפעם הראשונה שמפעילים תוכנית פעולה. |
לדוגמה, הפונקציות האלה מראות איך להשתמש במעצבים ובפרמטרים של מעצבים, וגם איך להשתמש בפונקציה respond של ספריית המערכת של בלוק הקוד.
# No decorator parameter
@PlaybookStartTrigger
def my_playbook_conditional_action():
respond("How can I help?")
# With a condition decorator parameter
@BeforeActionTrigger('$next-action.name = "search"')
def my_before_action_conditional_action():
respond("One moment please")
# Event
@EventTrigger(event="welcome")
def my_welcome_event():
respond("hi")
# Event with a condition:
@EventTrigger(event="welcome",
condition="$sys.func.NOW().hours < 10")
def my_good_morning_event():
respond("Good morning ☕")
הפניות לזרימות, לתוכניות פעולה ולכלים
בבלוק הקוד, אפשר להפנות לזרימות, לתוכניות פעולה ולכלים ספציפיים באמצעות המשתנים הגלובליים flows, playbooks ו-tools.
לכל אחד מהאובייקטים האלה יש חברים שתואמים לשמות של המשאבים המתאימים. השמות האלה צריכים להיות שמות חוקיים ב-Python.
דוגמה:
add_override(playbooks.troubleshooting, {})
add_override(flows.billing)
add_override(tools.weather_api.get_weather, {"location": "San Francisco"})
כשמפנים לזרימות ולספרי הדרכה בבלוק קוד, צריך להפנות אליהם גם בהוראות של ספר ההדרכה באמצעות התחביר הבא:
${RESOURCE_TYPE: my_resource_name}
לדוגמה,
אם בלוק הקוד מכיל את התווים flows.myflow ו-playbooks.myplaybook,
ההוראות ב-playbook צריכות לכלול:
${FLOW: myflow}
${PLAYBOOK: myplaybook}
שינוי ברירת המחדל של פעולות
אפשר להשתמש בבלוקים של קוד כדי ליצור תור של פעולות שיבוצעו לפני פעולות נוספות שנקבעו על ידי ה-LLM, ואולי גם לבטל אותן. כדי ליצור שינויים בפעולות, משתמשים בפונקציה הגלובלית add_override.
כל פעולות ההחלפה שמועברות לתור יבוצעו ברצף, והפלט של הפעולה יהיה זמין ל-LLM. אחרי שהתור מתרוקן, הפעולה חוזרת ל-LLM כדי לבחור פעולה וקלט, אלא אם פעולת ביטול מסיימת את התור עם respond או עם פונקציה אחרת שמשלימה את התור.
ארגומנטים של פונקציות:
- action: הפעולה שתתבצע.
כדי להוסיף פעולה מוטמעת, משתמשים ב-
my_function_name. כדי לבצע פעולה בכלי, משתמשים ב-tools.my_tool_name.my_tool_action. לפעולת Flow, משתמשים ב-flows.my_flow_name. - inputs: נתונים אופציונליים לפעולה.
לדוגמה:
{"location": "Omaha"}.
דוגמאות:
# Assuming remote tool named "dmv" with operationId "search_offices"
# remote tool with only requestBody
add_override(tools.dmv.search_offices,{"address": "95030"})
# remote tool with only parameters
add_override(tools.pets.get_pet, {"id": "123"})
# remote tool with requestBody + parameters:
add_override(tools.pets.create_pet, {"requestBody": {"arg1":"foo"}, "param1": "bar"})
# datastore. Assumes existing datastore tool named "Menu".
add_override(tools.menu.Menu, {"query": "what is the menu"})
# code block action. Assumes another code block @Action my_action.
add_override(my_action)
שינויים בתשובה מברירת המחדל
בדומה לביטול פעולות, אבל במיוחד לתשובות של הסוכן, אתם יכולים להשתמש בפונקציה הגלובלית respond כדי לחייב את הסוכן להשיב למשתמש עם תוכן ספציפי.
דוגמה:
respond("Hello")
כלים לשיחות
בפונקציות של בלוק הקוד, אפשר להפעיל את הכלים שהוגדרו לסוכן. בניגוד למצב שבו מבטלים פעולה של כלי, כשמפעילים כלי ישירות, תוצאות ההפעלה של הכלי לא זמינות ל-LLM.
דוגמאות:
# Assumes existing tool named "DMV" with operationId "search_offices"
# remote tool with only request body.
offices = tools.dmv.search_offices({"address": "95030"})
# remote tool with parameters and request body
offices = tools.dmv.search_offices({"requestBody": {"address":"95030"}, "param1":"foo"})
# datastore actions. Assumes existing datastore tool named "Menu".
data = tools.menu.Menu({"query": "get the menu"})["snippets"]
התאמה לכוונת הרכישה
אפשר להשתמש בפונקציה Flow.match_intent כדי להתאים באופן פרוגרמטי כוונת משתמש לזרימה נתונה.
דוגמה:
matches = flows.flow1.match_intent(history.last_user_utterance).matches
if matches and matches[0].intent == "some_intent":
to_country = matches[0].parameters.get("to_country")
if to_country:
respond(f"To confirm, you're going to {to_country}, right?")
קריאת פרמטרים של סשן
בלוקים של קוד יכולים לקרוא פרמטרים שזמינים בזמן ההפעלה.
דוגמה:
state["$session.params.my-param"]
state["$request.session-id"]
ניפוי באגים
אתם יכולים להשתמש בסימולטור כדי לדבג את הפונקציות של בלוק הקוד. הפונקציות האלה יוצגו כפעולות בסימולטור, ויספקו את הפרטים שלנו לפי הצורך.
שליטה נוספת
במדריך הזה מוסבר על כמה שימושים נפוצים בספריית המערכת של בלוקי קוד. לסוגים נוספים של אמצעי בקרה, אפשר לעיין במסמכי התיעוד של הספרייה.