חסימות קוד

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

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

מגבלות

המגבלות הבאות חלות:

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

פעולות בתוך השורה

פעולות מוטמעות פועלות באופן דומה לפעולות שקשורות לכלים. יש להם סכימת קלט ופלט מוגדרת, שנקבעת לפי החתימה של פונקציית Python, כולל הערות מסוג type ו-docstring. בדומה לקריאות API לכלי, מודל ה-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, and then call the `place_order` action when the
order is ready.

כדי ליצור דוגמאות שמשתמשות בפעולות מוטמעות, משתמשים בסוג הכלי inline-action בקטע Input & Output.

למידע נוסף, קראו את מאמרי העזרה של ‎@Action.

פונקציות טריגר

פונקציות טריגר משמשות להגדרת פעולות מותנות בקוד.

כדי להצהיר על פונקציות טריגר, משתמשים במעצבים (decorators).

אפשר להשתמש במעצבי הפונקציות הבאים של טריגרים:

מעצב	פרמטרים של מעצבים	תיאור
@EventTrigger	‫event: str, condition: str, כשהתנאי הוא אופציונלי	מופעל על ידי אירוע
@BeforeModelTrigger	‫condition: str, כשהתנאי הוא אופציונלי	מופעל בכל פעם לפני שה-LLM חוזה את הפעולה הבאה.
@BeforeActionTrigger	‫condition: str, כשהתנאי הוא אופציונלי	מופעל בכל פעם לפני שה-LLM מבצע פעולה.
‎@BeforePlaybookTrigger	‫condition: str, כשהתנאי הוא אופציונלי	מופעל בפעם הראשונה שמתחילים פלייבוק.

לדוגמה, הפונקציות האלה מראות איך להשתמש במעצבים ובפרמטרים של מעצבים, וגם איך להשתמש בפונקציה 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"})

כשמפנים לתהליכים ול-Playbook בבלוק קוד, צריך להפנות אליהם גם בהוראות של ה-Playbook באמצעות התחביר הבא:

${RESOURCE_TYPE: my_resource_name}

לדוגמה, אם בלוק הקוד מכיל את flows.myflow ו-playbooks.myplaybook, ההוראות בפלייבוק צריכות לכלול:

${FLOW: myflow}
${PLAYBOOK: myplaybook}

שינוי פעולות

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

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

ארגומנטים של פונקציות:

• פעולה: מציינים את הפעולה שרוצים לבצע. לפעולה בשורה, משתמשים ב-my_function_name. לפעולה של כלי, משתמשים ב-tools.my_tool_name.my_tool_action. לפעולת זרימה, משתמשים ב-flows.my_flow_name.
• קלט: מציינים קלט אופציונלי לפעולה, כמו {"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"]

התאמה לכוונת המשתמש

בלוקים של קוד יכולים להתאים באופן פרוגרמטי ל-Intent בתהליך נתון באמצעות הפונקציה 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"]

ניפוי באגים

אתם יכולים להשתמש בסימולטור כדי לנפות באגים בפונקציות של בלוק הקוד. הפונקציות האלה מופיעות כפעולות בסימולטור ומספקות פרטים על ניפוי באגים לפי הצורך.

אמצעי בקרה נוסף

במאמר הזה מוסבר על כמה שימושים נפוצים בספריית המערכת של בלוקים של קוד. לסוגים נוספים של אמצעי בקרה, עיינו במסמכי התיעוד של הספרייה.