您可以在 Python 工具和回调中使用 Python 代码。此参考文档介绍了 Python 运行时、导入选项和类、全局变量以及您可以在代码中使用的函数。
Python 环境
Python 工具和回调在安全的沙盒环境中运行。 此环境正在运行 Python 3.12。
导入
您只能导入以下模块：
类
AsyncTools
用于异步调用工具的别名类。
如需了解详情，请参阅async_tools 全局变量。
Blob
内嵌字节数据。
属性：
| 属性 | 说明 |
|---|---|
display_name: Optional[str] |
Blob 的显示名称。用于提供标签或文件名以区分 Blob。 |
data: Optional[bytes] |
Base64 编码的字节。 |
raw_data: Optional[bytes] |
原始解码字节。 |
mime_type: Optional[str] |
来源数据的 IANA 标准 MIME 类型。 |
方法：
| 方法 | 说明 |
|---|---|
transcript() -> Optional[str] |
返回 Blob 数据的缓存转写内容（如有）。这仅适用于音频 blob。 |
from_json(data: str) -> Blob |
一种用于从 JSON 字符串创建 Blob 实例的类方法，其中 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] |
会话事件。 |
方法：
| 方法 | 说明 |
|---|---|
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]] |
构成单条消息的各个部分的列表。每个部分的 IANA MIME 类型可能各不相同。 |
role: Optional[str] |
内容作者的角色。'user' 或 'agent'。 |
方法：
| 方法 | 说明 |
|---|---|
is_user() -> bool |
如果角色为 'user'，则返回 True。 |
is_model() -> bool |
如果角色为 'model'，则返回 True。 |
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 流式响应的不完整 chunk。 |
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 |
事件的基础元数据。 |
方法：
| 方法 | 说明 |
|---|---|
is_user() -> bool |
如果活动的作者是“用户”，则为 True。 |
is_agent(agent_name: Optional[str] = None) -> bool |
如果活动的作者是代理，则为 True。如果提供了 agent_name，则检查作者是否与该特定代理匹配。 |
has_error() -> bool |
如果事件具有关联的错误代码，则为 True。 |
parts() -> list[Part] |
一种便捷方法，用于从事件的 content 中获取 Part 对象的列表。如果没有内容或部分，则返回空列表。 |
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 |
如果 status_code 小于 400，则为 True；否则为 False。 |
方法：
| 方法 | 说明 |
|---|---|
json() -> Any |
解析文本属性 JSON 并返回结果。如果解析失败，则会抛出错误。 |
raise_for_status() |
如果响应不正常 (ok == False)，则引发 StatusError。 |
FunctionCall
表示函数调用。
属性：
| 属性 | 说明 |
|---|---|
id: Optional[str] |
函数调用的唯一标识符。 |
args: Optional[dict[str,Any]] |
以 JSON 对象格式表示的函数参数和值。 |
name: Optional[str] |
函数名称。 |
FunctionDeclaration
从模型返回的预测 FunctionCall，其中包含表示 FunctionDeclaration name 属性的字符串以及参数及其值。
属性：
| 属性 | 说明 |
|---|---|
name: Optional[str] |
函数名称。 |
FunctionResponse
FunctionCall 的结果，其中包含表示 FunctionDeclaration name 属性的字符串，以及包含函数调用的任何输出的结构化 JSON 对象。它用作模型的上下文。
属性：
| 属性 | 说明 |
|---|---|
id: Optional[str] |
相应函数调用的标识符。 |
name: Optional[str] |
函数名称。 |
response: Optional[dict[str,Any]] |
以 JSON 对象格式表示的函数响应。使用“output”键指定函数输出，使用“error”键指定错误详情（如有）。如果未指定“output”和“error”键，则整个“response”会被视为函数输出。 |
GenerateContentConfig
可选的模型配置参数。
属性：
| 属性 | 说明 |
|---|---|
system_instruction: Optional[Content] |
有关引导模型获得更好性能的说明。例如，“回答尽可能简明扼要”或“请勿在回答中使用技术词汇”。 |
tools: Optional[list[ToolDeclaration]] |
模型可执行的可用工具列表。 |
excluded_tools: Optional[list[str]] |
模型将忽略的工具名称列表。这会替换 tools。 |
方法：
| 方法 | 说明 |
|---|---|
hide_tool(tool_name: str) |
将 tool_name 添加到 excluded_tools 列表。 |
HttpMethod
表示 HTTP 方法的字符串枚举。 可能的值包括：
GETPOSTPUTDELETEPATCHHEADOPTIONS
LlmRequest
用于表示 LLM 请求的数据模型。
属性：
| 属性 | 说明 |
|---|---|
model: Optional[str] |
模型名称 |
contents: List[Content] |
发送给模型的内容列表。 |
config: Optional[GeneralContentConfig] |
模型配置参数。 |
LlmResponse
用于表示 LLM 回答的数据模型。
属性：
| 属性 | 说明 |
|---|---|
content: Content |
模型响应的第一个 Content。 |
partial: Optional[bool] |
表示内容是否代表不完整的模型回答。代理会在发出部分响应后继续处理。 |
方法：
| 方法 | 说明 |
|---|---|
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] |
内嵌字节数据。 |
方法：
| 方法 | 说明 |
|---|---|
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 的类方法（例如，停用裸机启动、启用 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 允许您使用与热门 Python requests 模块类似的语法进行 HTTP 调用。
样本：
# 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 对象可以互换。
为了与 ADK 代码兼容，系统支持 state 对象，但新代码应使用 variables 对象。