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 |
mime_type を「application/json」に設定して、JSON 文字列から Blob インスタンスを作成するクラス メソッド。 |
サンプル:
# 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] |
設計時に定義された変数または実行時に挿入された変数の Key-Value ペアを含むディクショナリ。これは、コールバック実行時の変数の現在の状態です。 |
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]] |
1 つのメッセージを構成するパーツのリスト。パーツごとに異なる 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 |
イベントに参加したユーザーまたはエージェントの名前。 |
timestamp: int |
イベントのタイムスタンプ。 |
content: Content |
このイベントに関連付けられているコンテンツ。 |
actions: EventActions |
エージェントが実行したアクション。 |
long_running_tool_ids: set[str] |
長時間実行関数呼び出しの ID のセット。 |
partial: bool |
LLM ストリーミング レスポンスの不完全なチャンクの場合は True。 |
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 |
イベントの作成者が「user」の場合は 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]] |
ツール レスポンスによってリクエストされた認証構成。 このフィールドは、ツール リクエストの認証情報を示すツール レスポンス イベントによってのみ設定されます。 キー: 関数呼び出し ID。1 つの関数レスポンス イベントに、複数の関数呼び出しに対応する複数の関数レスポンスが含まれる可能性があるためです。関数呼び出しごとに異なる認証構成をリクエストできます。この識別子は、関数呼び出しの識別に使用されます。 値: リクエストされた認証構成。 |
end_invocation: bool |
エージェント ループが中断されます。 |
ExternalResponse
ツール呼び出しや HTTP リクエストなど、Python 環境外からのレスポンスを表します。
属性:
| 属性 | 説明 |
|---|---|
text: str |
文字列としてのレスポンス本文。 |
status_code: int |
HTTP ステータス コード。 |
reason: str |
エラーがスローされる理由。エラーがない場合は空になります。 |
ok: bool |
status_code が 400 より小さい場合は True、それ以外の場合は False。 |
メソッド:
| メソッド | 説明 |
|---|---|
json() -> Any |
テキスト属性 JSON を解析し、結果を返します。解析に失敗すると、エラーがスローされます。 |
raise_for_status() |
レスポンスが OK でない場合（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 内のフィールドは 1 つだけ設定する必要があります。これは、伝達されるコンテンツの特定のタイプを表します。同じ 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 |
カスタマイズされた動作（ベアゲージインの無効化、DTMF 入力の有効化など）でレスポンス用の Part を作成するクラスメソッド。 |
サンプル:
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 |
実行中の現在のツール呼び出しの関数呼び出し ID。 |
Tools
ツールを同期的に呼び出すためのエイリアス クラス。詳しくは、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
この関数は、セッション状態から Key-Value ペアを削除します。これは 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 リクエスト モジュールと同様の構文で 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 オブジェクトは相互に置き換え可能です。state オブジェクトは ADK コードとの互換性のためにサポートされていますが、新しいコードでは variables オブジェクトを使用する必要があります。