מסמך עזר של זמן הריצה של Python

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

סביבת Python

הכלים וההחזרות (callbacks) של Python פועלים בסביבת ארגז חול מאובטחת. בסביבה הזו פועלת Python 3.12.

ייבוא

היכולת לייבא מודולים מוגבלת לאפשרויות הבאות:

כיתות

AsyncTools

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

Blob

נתוני בייטים מוטמעים.

מאפיינים:

מאפיין תיאור
display_name: Optional[str] השם המוצג של Blob. משמש כדי לספק תווית או שם קובץ להבחנה בין ה-blobs.
data: Optional[bytes] בייטים בקידוד Base64.
raw_data: Optional[bytes] בייטים גולמיים מפוענחים.
mime_type: Optional[str] סוג ה-MIME התקני של IANA של נתוני המקור.

שיטות:

‏Method תיאור
transcript() -> Optional[str] הפונקציה מחזירה תמליל שמאוחסן במטמון של נתוני Blob, אם הוא זמין. ההגדרה הזו רלוונטית רק ל-blob של אודיו.
from_json(data: str) -> Blob שיטה של מחלקה ליצירת מופע Blob ממחרוזת JSON, כאשר mime_type מוגדר כ-'application/json'.

דוגמאות:

# Create a blob from raw bytes
blob = Blob(mime_type='text/plain')
blob.raw_data = b'hello world'

# Create a blob from a JSON string
Blob.from_json(data='{"key": "value"}')

CallbackContext

פרטי הסשן שזמינים במהלך שיחת החזרה.

מאפיינים:

מאפיין תיאור
user_content: Optional[Content] הקלט האחרון מהמשתמש.
invocation_id: str מזהה ייחודי של הפעלת הקריאה החוזרת הספציפית, שימושי לניפוי באגים.
agent_name: str השם לתצוגה של הנציג שמשויך לשיחה החוזרת הנוכחית.
session_id: str מזהה סשן ייחודי של הסשן הנוכחי שמתנהל.
variables: dict[str, Any] מילון שמכיל צמדי מפתח/ערך של משתנים שהוגדרו בזמן העיצוב או שהוזרקו במהלך זמן הריצה. זהו המצב הנוכחי של המשתנים ברגע הביצוע של הקריאה החוזרת.
state: dict[str, Any] בדיוק כמו בנכס variables.
events: list[Event] אירועים ברמת הסשן.

שיטות:

‏Method תיאור
get_variable(key: str, default: Any) -> Any מקבל משתנה מהמצב. אם המשתנה לא קיים, מחזירים את ברירת המחדל.
set_variable(key: str, value: Any) -> None מגדיר משתנה במצב.
remove_variable(key: str) -> None הסרת משתנה מהמצב.
get_last_user_input() -> list[Part] מקבל רשימה של כל החלקים בחלק האחרון של אירועי המשתמשים.
get_last_agent_output() -> list[Part] מקבל רשימה של כל החלקים בחלק האחרון של אירועי הסוכן.
parts() -> list[Part] רשימה של כל החלקים שתועדו בהיסטוריית הפעילות.

Content

תוכן ההודעה מהמשתמש או מהסוכן.

מאפיינים:

מאפיין תיאור
parts: Optional[list[Part]] רשימה של חלקים שמרכיבים הודעה אחת. לכל חלק יכול להיות סוג MIME שונה של IANA.
role: Optional[str] התפקיד של יוצר התוכן. 'user' או 'agent'.

שיטות:

‏Method תיאור
is_user() -> bool הפונקציה מחזירה True אם התפקיד הוא 'user'.
is_model() -> bool הפונקציה מחזירה True אם התפקיד הוא 'model'.

Event

ייצוג של אירוע בסשן.

מאפיינים:

מאפיין תיאור
id: str מזהה האירוע.
invocation_id: str מזהה הפעלת האירוע.
author: str 'user' או שם הסוכן, שמציין מי השתתף באירוע בסשן.
timestamp: int חותמת הזמן של האירוע.
content: Content התוכן שמשויך לאירוע הזה.
actions: EventActions הפעולות שהסוכן ביצע.
long_running_tool_ids: set[str] קבוצת מזהים של קריאות לפונקציות ממושכות.
partial: bool ‫True לחלקים לא שלמים מהתשובה של מודל שפה גדול (LLM) שמוצגת באופן שוטף.
turn_complete: bool ‫True אם התור הנוכחי הסתיים.
error_code: str קוד שגיאה.
error_message: str הודעת שגיאה.
interrupted: bool True אם התור להשתתפות בשיחה הופסק.
branch: str הענף של האירוע.

הפורמט הוא כמו agent_1.agent_2.agent_3, כאשר agent_1 הוא ההורה של agent_2, ו-agent_2 הוא ההורה של agent_3.

הענף משמש כשלא רוצים שמספר סוכני משנה יראו את היסטוריית השיחות של הסוכנים העמיתים שלהם.
grounding_metadata: Any מטא-נתונים של ביסוס האירוע.

שיטות:

‏Method תיאור
is_user() -> bool ‫True אם מחבר האירוע הוא 'משתמש'.
is_agent(agent_name: Optional[str] = None) -> bool ‫True אם מחבר האירוע הוא סוכן. אם מצוין agent_name, המערכת בודקת אם המחבר תואם לסוכן הספציפי הזה.
has_error() -> bool ‫True אם לאירוע יש קוד שגיאה משויך.
parts() -> list[Part] שיטה נוחה לקבלת רשימת אובייקטים של Part מה-content של האירוע. מחזירה רשימה ריקה אם אין תוכן או חלקים.

EventActions

פעולות שמתרחשות באירועים.

מאפיינים:

מאפיין תיאור
skip_summarization: bool אם הערך הוא True, המודל לא מופעל כדי לסכם את תשובת הפונקציה. השדה הזה משמש רק לאירוע function_response.
state_delta: dict[str,Any] השינויים במשתנים שנגרמו על ידי האירוע הזה.
artifact_delta: dict[str,Any] השינויים שבוצעו בארטיפקטים על ידי האירוע הזה. המפתח הוא שם הקובץ, והערך הוא הגרסה.
transfer_to_agent: str אם מוגדר, האירוע מועבר לסוכן שצוין.
escalate: bool הסוכן מעביר את השיחה לסוכן ברמה גבוהה יותר.
requested_auth_configs: dict[str,dict[str,Any]] הגדרות אימות שנדרשות בתגובות של כלים.

השדה הזה מוגדר רק על ידי אירוע תגובה של כלי שמציין פרטי אימות של בקשת כלי.

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

ערכים: הגדרת האימות המבוקשת.
end_invocation: bool הלולאה של הסוכן נקטעת.

ExternalResponse

מייצג תגובה מחוץ לסביבת Python, כמו קריאה לכלי או בקשת HTTP.

מאפיינים:

מאפיין תיאור
text: str תוכן התשובה כמחרוזת.
status_code: int קוד הסטטוס של HTTP.
reason: str הסיבה להצגת השגיאה. אם אין שגיאה, השדה ריק.
ok: bool ‫True אם status_code קטן מ-400, אחרת False.

שיטות:

‏Method תיאור
json() -> Any הפונקציה מנתחת את ה-JSON של מאפיין הטקסט ומחזירה את התוצאה. אם הניתוח ייכשל, תופעל שגיאה.
raise_for_status() מועלית שגיאה StatusError אם התשובה לא תקינה (ok == False).

FunctionCall

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

מאפיינים:

מאפיין תיאור
id: Optional[str] המזהה הייחודי של הקריאה לפונקציה.
args: Optional[dict[str,Any]] הפרמטרים והערכים של הפונקציה בפורמט אובייקט JSON.
name: Optional[str] שם הפונקציה.

FunctionDeclaration

FunctionCall חזוי שמוחזר מהמודל, שמכיל מחרוזת שמייצגת את מאפיין name FunctionDeclaration עם הפרמטרים והערכים שלהם.

מאפיינים:

מאפיין תיאור
name: Optional[str] שם הפונקציה.

FunctionResponse

התוצאה של FunctionCall שמכילה מחרוזת שמייצגת את מאפיין FunctionDeclaration name ואובייקט JSON מובנה שמכיל את הפלט של הקריאה לפונקציה. הוא משמש כהקשר למודל.

מאפיינים:

מאפיין תיאור
id: Optional[str] המזהה של קריאת הפונקציה התואמת.
name: Optional[str] שם הפונקציה.
response: Optional[dict[str,Any]] התגובה של הפונקציה בפורמט אובייקט JSON. משתמשים במפתח 'פלט' כדי לציין את פלט הפונקציה ובמפתח 'שגיאה' כדי לציין את פרטי השגיאה (אם יש). אם לא מציינים את המפתחות output ו-error, המערכת מתייחסת לכל התגובה כפלט של הפונקציה.

GenerateContentConfig

פרמטרים אופציונליים להגדרת המודל.

מאפיינים:

מאפיין תיאור
system_instruction: Optional[Content] הוראות למודל כדי לשפר את הביצועים. לדוגמה, "תענה בצורה תמציתית ככל האפשר" או "אל תשתמש במונחים טכניים בתשובה שלך".
tools: Optional[list[ToolDeclaration]] רשימה של כלים זמינים שהמודל יכול להשתמש בהם.
excluded_tools: Optional[list[str]] רשימה של שמות כלים שהמודל יתעלם מהם. ההגדרה הזו מבטלת את tools.

שיטות:

‏Method תיאור
hide_tool(tool_name: str) ‫tool_name נוסף לרשימה excluded_tools.

HttpMethod

סוג enum של מחרוזת שמייצג שיטת HTTP. הערכים האפשריים הם:

  • GET
  • POST
  • PUT
  • DELETE
  • PATCH
  • HEAD
  • OPTIONS

LlmRequest

מודלים של נתונים לייצוג בקשות ל-LLM.

מאפיינים:

מאפיין תיאור
model: Optional[str] שם הדגם
contents: List[Content] רשימת התוכן שנשלח למודל.
config: Optional[GeneralContentConfig] פרמטרים להגדרת המודל.

LlmResponse

מודלים של נתונים לייצוג תשובות מ-LLM.

מאפיינים:

מאפיין תיאור
content: Content התשובה הראשונה של המודל.Content
partial: Optional[bool] מציין אם התוכן מייצג תגובה חלקית של מודל. הסוכן ימשיך את העיבוד אחרי שיפלוט את התגובה החלקית.

שיטות:

‏Method תיאור
from_parts(parts: list[Part]) -> LlmResponse שיטת מחלקה שמחזירה LlmResponse מהמודל.

דוגמאות:

response = LlmResponse.from_parts(
  parts=[
    Part.from_text(text="hello world")
  ]
)

Part

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

מאפיינים:

מאפיין תיאור
function_call: Optional[FunctionCall] תחזית FunctionCall שמוחזרת מהמודל ומכילה מחרוזת שמייצגת את שם הפונקציה ואובייקט JSON מובנה שמכיל את הפרמטרים והערכים שלהם.
function_response: Optional[FunctionResponse] פלט התוצאה של FunctionCall שמכיל מחרוזת שמייצגת את שם הפונקציה ואובייקט JSON מובנה שמכיל את הפלט של הקריאה לפונקציה. הוא משמש כהקשר למודל.
text: Optional[str] טקסט ההודעה.
inline_data: Optional[Blob] נתוני בייטים מוטמעים.

שיטות:

‏Method תיאור
text_or_transcript() -> Optional[str] הפונקציה מחזירה את הטקסט אם הוא זמין, אחרת היא מחזירה את התמליל של הנתונים בתוך התג.
has_function_call(name) -> bool הפונקציה מחזירה True אם החלק מכיל קריאה לפונקציה ספציפית.
has_function_response(name) -> bool הפונקציה מחזירה True אם החלק מכיל תגובה ספציפית של פונקציה.
from_text(text: str) -> Part שיטת מחלקה שיוצרת טקסט Part.
from_function_call(name: str, args: dict[str, Any]) -> Part שיטת כיתה שיוצרת קריאה לפונקציה Part.
from_function_response(name: str, response: dict[str, Any]) -> Part שיטת מחלקה שיוצרת תשובה של פונקציה Part.
from_inline_data(data: bytes, mime_type: str) -> Part שיטה של מחלקה שיוצרת נתונים מוטבעים Part.
from_json(data: str) -> Part שיטה של מחלקה שיוצרת נתונים מוטבעים ב-JSON‏ Part.
from_agent_transfer(agent: str) -> Part שיטת מחלקה שיוצרת Part להעברה לנציג אחר.
from_end_session(*, reason: str, escalated: bool = False) -> Part שיטת מחלקה שיוצרת Part לסיום הסשן.
from_customized_response(*, content: str, disable_barge_in: bool = False, enable_dtmf: bool = False, dtmf_finish_digit = str: '#', dtmf_endpointing_timeout: int = 3) -> Part שיטה של מחלקה שיוצרת Part לתגובה עם התנהגות מותאמת אישית (לדוגמה, השבתה של barege-in, הפעלה של קלט DTMF וכו').

דוגמאות:

text_part = ces_public.Part.from_text(text="Hello from the user!")

tool_part = ces_public.Part.from_function_call(
  name="get_weather",
  args={"location": "Mountain View"}
)

Requests

מחלקת כינוי ליצירת בקשות HTTP. מידע נוסף זמין במאמר בנושא ces_requests משתנה גלובלי.

שיטות:

  • get(url, params=None, **kwargs)
  • post(url, data=None, json=None, **kwargs)
  • put(url, data=None, json=None, **kwargs)
  • delete(url, **kwargs)
  • patch(url, data=None, json=None, **kwargs)
  • head(url, **kwargs)
  • options(url, **kwargs)

StatusError

משמש לשגיאות שמועלות עם קוד סטטוס.

מאפיינים:

מאפיין תיאור
status_code: int קוד הסטטוס של HTTP שמשויך לשגיאה הזו.
reason: str הסיבה להצגת השגיאה.

Tool

מייצג כלי עם שם ותיאור.

מאפיינים:

מאפיין תיאור
name: str שם הכלי.
description: str תיאור של מה שהכלי עושה.

ToolContext

הנתונים נגזרים מ-CallbackContext. פרטי הסשן שזמינים כשמריצים כלי.

מאפיינים:

מאפיין תיאור
function_call_id: str מזהה קריאת הפונקציה של קריאת הכלי הנוכחית שמופעלת.

Tools

מחלקת כינוי לקריאה סינכרונית של כלי שיחות. מידע נוסף זמין במאמר בנושא משתנה גלובלי של כלים.

ToolDeclaration

סכימת כלי שאפשר להציג למודל.

מאפיינים:

מאפיין תיאור
function_declarations: Optional[list[FunctionDeclaration]] רשימה של הצהרות פונקציות שהכלי תומך בהן.

פונקציות

get_variable

הפונקציה הזו מאחזרת ערך ממצב הסשן באמצעות המפתח שצוין. הוא משמש כקיצור דרך ל-context.state.get(key) או ל-context.variables.get(key).

קוד לדוגמה:

def get_a_value() -> int:
  # Retrieve the value of 'my_key' from the state
  my_value = get_variable('my_key')
  return my_value + 5

remove_variable

הפונקציה הזו מסירה צמד מפתח/ערך ממצב הסשן. זהו קיצור דרך לdel context.state[key].

קוד לדוגמה:

def remove_a_value() -> None:
  # Delete 'my_key' from the state
  remove_variable('my_key')

set_variable

הפונקציה הזו מגדירה ערך למפתח נתון מסוים במצב הסשן. אם המפתח כבר קיים, הערך שלו יעודכן. זה קיצור דרך ל-context.state[key] = value.

קוד לדוגמה:

def set_a_value() -> None:
  # Set the value of 'my_key' to 10
  set_variable('my_key', 10)

משתנים גלובליים

async_tools

מופע של AsyncTools, שמאפשר לבצע קריאות אסינכרוניות לכלים.

דוגמאות:

response_future = async_tools.<TOOL_DISPLAY_NAME>(<ARGS_AS_DICT>)
# ... misc work
response = response_future() # poll for response

# Check if the tool call was successful
try:
  response.raise_for_status()
except StatusError:
  print(f"Request failed with status {response.status_code}")

# Convert the response to json
data = response.json()

ces_requests

מופע של Requests. ‫Requests מאפשרת לבצע קריאות HTTP עם תחביר דומה לזה של מודול הבקשות הפופולרי של Python.

דוגמאות:

# Make a GET request
response = ces_requests.get('https://api.example.com/data')

# Check if the request was successful
try:
  response.raise_for_status()
except StatusError:
  print(f"Request failed with status {response.status_code}")

# Convert the response to json
data = response.json()

tools

מופע של Tools, שמאפשר לבצע קריאות סינכרוניות לכלים.

דוגמאות:

response = tools.<TOOL_DISPLAY_NAME>(<ARGS_AS_DICT>)

# Check if the tool call was successful
try:
  response.raise_for_status()
except StatusError:
  print(f"Request failed with status {response.status_code}")

# Convert the response to json
data = response.json()

context

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

האובייקטים context.state ו-context.variables ניתנים להחלפה. האובייקט state נתמך לצורך תאימות לקוד ADK, אבל בקוד חדש צריך להשתמש באובייקט variables.