エージェント コンテキスト¶
Agent Development Kit (ADK) において、コンテキストとは、エージェントとそのツールが特定の操作中に利用できる重要な情報の集合体を指します。現在のタスクや会話のターンを効果的に処理するために必要な背景知識やリソースだと考えてください。
エージェントがうまく機能するためには、多くの場合、最新のユーザーメッセージ以上の情報が必要です。コンテキストは以下を可能にするため、不可欠です。
- 状態の維持: 会話の複数のステップにわたる詳細(例:ユーザーの好み、以前の計算結果、ショッピングカートのアイテム)を記憶します。これは主にセッション状態(session state)を通じて管理されます。
- データの受け渡し: あるステップ(LLMの呼び出しやツールの実行など)で発見または生成された情報を、後続のステップと共有します。ここでもセッション状態が鍵となります。
- サービスへのアクセス: 以下のようなフレームワークの機能と対話します。
- アーティファクトストレージ: セッションに関連付けられたファイルやデータのかたまり(PDF、画像、設定ファイルなど)を保存または読み込みます。
- メモリ: ユーザーに関連する過去の対話や外部の知識ソースから関連情報を検索します。
- 認証: ツールが外部APIに安全にアクセスするために必要な認証情報を要求および取得します。
- IDと追跡: 現在どのエージェントが実行されているか(
agent.name)を把握し、ロギングとデバッグのために現在のリクエスト-レスポンスサイクル(invocation_id)を一意に識別します。 - ツール固有のアクション: 現在の対話の詳細へのアクセスを必要とする、認証要求やメモリ検索など、ツール内での特化した操作を有効にします。
単一の完全なユーザーリクエストから最終レスポンスまでのサイクル(呼び出し (invocation))に関するこれらすべての情報をまとめる中心的な要素がInvocationContextです。しかし、通常、このオブジェクトを直接作成したり管理したりすることはありません。ADKフレームワークは、呼び出しが開始されるとき(例:runner.run_async経由で)にこれを作成し、関連するコンテキスト情報をエージェントコード、コールバック、ツールに暗黙的に渡します。
# How the framework provides context
from google.adk import Runner
# 1. You initialize a Runner with your agent and services
runner = Runner(
app_name="my_app",
agent=my_root_agent,
session_service=my_session_service,
artifact_service=my_artifact_service,
)
# 2. You call run_async with the user input
# Note: run_async is an asynchronous generator yielding Events.
# The framework internally creates an InvocationContext and passes it
# implicitly to your agent code, callbacks, and tools.
async for event in runner.run_async(
user_id="user123",
session_id="session456",
new_message=user_message
):
print(event.stringify_content())
# As a developer, you work with the context objects provided in method arguments.
/* Conceptual Pseudocode: How the framework provides context (Internal Logic) */
const runner = new InMemoryRunner({ agent: myRootAgent });
const session = await runner.sessionService.createSession({ ... });
const userMessage = createUserContent(...);
// --- Inside runner.runAsync(...) ---
// 1. Framework creates the main context for this specific run
const invocationContext = new InvocationContext({
invocationId: "unique-id-for-this-run",
session: session,
userContent: userMessage,
agent: myRootAgent, // The starting agent
sessionService: runner.sessionService,
pluginManager: runner.pluginManager,
// ... other necessary fields ...
});
//
// 2. Framework calls the agent's run method, passing the context implicitly
await myRootAgent.runAsync(invocationContext);
// --- End Internal Logic ---
// As a developer, you work with the context objects provided in method arguments.
/* Conceptual Pseudocode: How the framework provides context (Internal Logic) */
sessionService := session.InMemoryService()
r, err := runner.New(runner.Config{
AppName: appName,
Agent: myAgent,
SessionService: sessionService,
})
if err != nil {
log.Fatalf("Failed to create runner: %v", err)
}
s, err := sessionService.Create(ctx, &session.CreateRequest{
AppName: appName,
UserID: userID,
})
if err != nil {
log.Fatalf("FATAL: Failed to create session: %v", err)
}
scanner := bufio.NewScanner(os.Stdin)
for {
fmt.Print("\nYou > ")
if !scanner.Scan() {
break
}
userInput := scanner.Text()
if strings.EqualFold(userInput, "quit") {
break
}
userMsg := genai.NewContentFromText(userInput, genai.RoleUser)
events := r.Run(ctx, s.Session.UserID(), s.Session.ID(), userMsg, agent.RunConfig{
StreamingMode: agent.StreamingModeNone,
})
fmt.Print("\nAgent > ")
for event, err := range events {
if err != nil {
log.Printf("ERROR during agent execution: %v", err)
break
}
if event != nil && event.Content != nil && len(event.Content.Parts) > 0 {
fmt.Print(event.Content.Parts[0].Text)
}
}
}
/* How the framework provides context */
InMemoryRunner runner = new InMemoryRunner(agent);
Session session = runner
.sessionService()
.createSession(runner.appName(), USER_ID, initialState, SESSION_ID )
.blockingGet();
try (Scanner scanner = new Scanner(System.in, StandardCharsets.UTF_8)) {
while (true) {
System.out.print("\nYou > ");
String userInput = scanner.nextLine();
if ("quit".equalsIgnoreCase(userInput)) {
break;
}
Content userMsg = Content.fromParts(Part.fromText(userInput));
Flowable<Event> events = runner.runAsync(session.userId(), session.id(), userMsg);
System.out.print("\nAgent > ");
events.blockingForEach(event -> System.out.print(event.stringifyContent()));
}
}
import com.google.adk.kt.runners.InMemoryRunner
// How the framework provides context
// 1. You initialize a Runner with your agent and services
val runner =
InMemoryRunner(
agent = myRootAgent,
appName = "my_app",
sessionService = mySessionService,
artifactService = myArtifactService,
)
// 2. You call runAsync with the user input
// Note: runAsync returns a Flow of Events.
// The framework internally creates an InvocationContext and passes it
// implicitly to your agent code, callbacks, and tools.
runner
.runAsync(
userId = "user123",
sessionId = "session456",
newMessage = userMessage,
).collect { event ->
println(event.contentText())
}
// As a developer, you work with the context objects provided in method arguments.
コンテキストのタイプ¶
ADK は、エージェントの環境、状態、およびリソースを管理するための中心的なメカニズムとして Context クラスを使用します。Context はすべてのエージェントの相互作用の基礎として機能しますが、エージェントの実行フローのどこで使用されるかに応じて、機能と権限の適切なバランスを提供するように設計された、いくつかの特殊な「フレーバー」として現れます。
これらの特定のコンテキストタイプを使用することで、ADK はメモリ、セッション状態、認証情報などの必要な情報に、必要な時に必要な場所でエージェントが正確にアクセスできるようにします。
遭遇する主なコンテキストフレーバーは次のとおりです。
-
InvocationContext: サービスの参照やライフサイクル管理など、呼び出し全体の包括的なビューを提供するために、エージェントのコア実行時(_run_async_impl、_run_live_impl)に使用されます。 -
ReadonlyContext: インストラクションプロバイダー内など、変更が許可されないシナリオで使用される、基本的なコンテキスト詳細の軽量で制限されたビュー。 -
Context: エージェントのライフサイクルおよびモデルのコールバックで使用されます。セッション状態の読み書き、アーティファクトの管理、メモリサービスへのデータ挿入のための堅牢な機能セットを提供します。 -
ToolContext: ツールの実行およびツール関連のコールバック用に調整されています。Context の機能に加えて、認証フロー、メモリ検索、アーティファクト検出のための特殊なメソッドが含まれています。
Note
互換性について: Python と TypeScript では、CallbackContext と ToolContext は Context タイプに置き換えられました。CallbackContext クラスは、後方互換性を確保するための Context のエイリアスとして維持されます。既存のコードベースで CallbackContext に遭遇することがあるかもしれませんが、統合された完全な機能セットを利用するために、新規開発では Context クラスを使用することをお勧めします。
InvocationContext¶
- 使用場所: エージェントのコア実装メソッド(
_run_async_impl、_run_live_impl)内でctx引数として直接受け取ります。 - 目的: 現在の呼び出しの全体の状態へのアクセスを提供します。これは最も包括的なコンテキストオブジェクトです。
- 主な内容:
session(stateとeventsを含む)、現在のagentインスタンス、invocation_id、初期のuser_content、設定されたサービス(artifact_service、memory_service、session_service)への参照、およびライブ/ストリーミングモードに関連するフィールドへの直接アクセス。 -
ユースケース: 主にエージェントのコアロジックがセッション全体やサービスに直接アクセスする必要がある場合に使用されますが、状態やアーティファクトの操作は、独自のコンテキストを使用するコールバック/ツールに委譲されることが多いです。また、呼び出し自体を制御するためにも使用されます(例:
ctx.end_invocation = Trueの設定)。# Agent implementation receiving InvocationContext from google.adk.agents import BaseAgent from google.adk.agents.invocation_context import InvocationContext from google.adk.events import Event from typing import AsyncGenerator class MyAgent(BaseAgent): async def _run_async_impl(self, ctx: InvocationContext) -> AsyncGenerator[Event, None]: # Direct access example agent_name = ctx.agent.name session_id = ctx.session.id print(f"Agent {agent_name} running in session {session_id} for invocation {ctx.invocation_id}") # ... agent logic using ctx ... yield # ... event ...// Pseudocode: Agent implementation receiving InvocationContext import { BaseAgent, InvocationContext, Event } from '@google/adk'; class MyAgent extends BaseAgent { async *runAsyncImpl(ctx: InvocationContext): AsyncGenerator<Event, void, undefined> { // Direct access example const agentName = ctx.agent.name; const sessionId = ctx.session.id; console.log(`Agent ${agentName} running in session ${sessionId} for invocation ${ctx.invocationId}`); // ... agent logic using ctx ... yield; // ... event ... } }import ( "fmt" "google.golang.org/adk/v2/agent" "google.golang.org/adk/v2/session" ) // Pseudocode: Agent implementation receiving InvocationContext type MyAgent struct { } func (a *MyAgent) Run(ctx agent.InvocationContext) iter.Seq2[*session.Event, error] { return func(yield func(*session.Event, error) bool) { // Direct access example agentName := ctx.Agent().Name() sessionID := ctx.Session().ID() fmt.Printf("Agent %s running in session %s for invocation %s\n", agentName, sessionID, ctx.InvocationID()) // ... agent logic using ctx ... yield(&session.Event{Author: agentName}, nil) } }// Example: Agent implementation receiving InvocationContext import com.google.adk.agents.BaseAgent; import com.google.adk.agents.InvocationContext; import com.google.adk.events.Event; import io.reactivex.rxjava3.core.Flowable; public class MyAgent extends BaseAgent { @Override protected Flowable<Event> runAsyncImpl(InvocationContext invocationContext) { // Direct access example String agentName = invocationContext.agent().name(); String sessionId = invocationContext.session().id(); String invocationId = invocationContext.invocationId(); System.out.println("Agent " + agentName + " running in session " + sessionId + " for invocation " + invocationId); // ... agent logic using invocationContext ... return Flowable.empty(); } }import com.google.adk.kt.agents.BaseAgent import com.google.adk.kt.agents.InvocationContext import com.google.adk.kt.events.Event import kotlinx.coroutines.flow.Flow import kotlinx.coroutines.flow.flow // Agent implementation receiving InvocationContext class MyAgent( name: String, ) : BaseAgent(name = name) { override fun runAsyncImpl(context: InvocationContext): Flow<Event> = flow { // Direct access example val agentName = context.agent.name val sessionId = context.session.key.id println( "Agent $agentName running in session $sessionId " + "for invocation ${context.invocationId}", ) // ... agent logic using context ... // emit(...) // ... event ... } }
ReadonlyContext¶
- 使用場所: 基本情報への読み取りアクセスのみが必要で、変更が許可されていないシナリオ(例:
InstructionProvider関数)で提供されます。他のコンテキストのベースクラスでもあります。 - 目的: 基本的なコンテキスト詳細の安全な読み取り専用ビューを提供します。
-
主な内容:
invocation_id、agent_name、および現在のstateの読み取り専用ビュー。# Example: Instruction provider receiving ReadonlyContext from google.adk.agents.readonly_context import ReadonlyContext def my_instruction_provider(context: ReadonlyContext) -> str: # Read-only access example # The state property provides a read-only MappingProxyType view of the state user_tier = context.state.get("user_tier", "standard") # context.state['new_key'] = 'value' # TypeError: 'mappingproxy' object does not support item assignment return f"Process the request for a {user_tier} user."// Pseudocode: Instruction provider receiving ReadonlyContext import { ReadonlyContext } from '@google/adk'; function myInstructionProvider(context: ReadonlyContext): string { // Read-only access example // The state object is read-only const userTier = context.state.get('user_tier') ?? 'standard'; // context.state.set('new_key', 'value'); // This would fail or throw an error return `Process the request for a ${userTier} user.`; }import ( "fmt" "google.golang.org/adk/v2/agent" ) // Pseudocode: Instruction provider receiving ReadonlyContext func myInstructionProvider(ctx agent.ReadonlyContext) (string, error) { // Read-only access example userTier, err := ctx.ReadonlyState().Get("user_tier") if err != nil { userTier = "standard" // Default value } // ctx.ReadonlyState() has no Set method since State() is read-only. return fmt.Sprintf("Process the request for a %v user.", userTier), nil }// Example: Instruction provider receiving ReadonlyContext import com.google.adk.agents.ReadonlyContext; public String myInstructionProvider(ReadonlyContext context) { // Read-only access example // state() returns an unmodifiable view of the session state String userTier = (String) context.state().getOrDefault("user_tier", "standard"); // context.state().put("new_key", "value"); // UnsupportedOperationException return "Process the request for a " + userTier + " user."; }import com.google.adk.kt.agents.ReadonlyContext import com.google.adk.kt.types.Content import com.google.adk.kt.types.Part // Example: Instruction provider receiving ReadonlyContext fun myInstructionProvider(context: ReadonlyContext): Content { // Read-only access example // The state property is a read-only Map snapshot of the session state val userTier = context.state["user_tier"] as? String ?: "standard" // context.state["new_key"] = "value" // Does not compile: Map has no set operator return Content(parts = listOf(Part(text = "Process the request for a $userTier user."))) }
CallbackContext と Context¶
- 使用場所: エージェントのライフサイクルコールバック(
before_agent_callback、after_agent_callback)およびモデルインタラクションコールバック(before_model_callback、after_model_callback)にcallback_contextとして渡されます。 - 目的: 特にコールバック内で、状態の検査と変更、アーティファクトとの対話、および呼び出し詳細へのアクセスを容易にします。
- 主な機能(
ReadonlyContextに追加):- 変更可能な
stateプロパティ: セッション状態の読み取りと書き込みを許可します。ここで行われた変更(callback_context.state['key'] = value)は追跡され、コールバック後にフレームワークによって生成されるイベントに関連付けられます。 - アーティファクトメソッド: 設定された
artifact_serviceと対話するためのload_artifact(filename)およびsave_artifact(filename, part)メソッド。 - 直接の
user_contentアクセス。
- 変更可能な
Note
Python と TypeScript では、CallbackContext と ToolContext は Context タイプに置き換えられました。
# Example: Callback receiving Context (CallbackContext is unified into Context)
from google.adk.agents.context import Context
from google.adk.models import LlmRequest
from google.genai import types
from typing import Optional
def my_before_model_cb(context: Context, request: LlmRequest) -> Optional[types.Content]:
# Read/Write state example
call_count = context.state.get("model_calls", 0)
context.state["model_calls"] = call_count + 1 # Modify state (tracks delta)
# Optionally load an artifact
# config_part = context.load_artifact("model_config.json")
print(f"Preparing model call #{call_count + 1} for invocation {context.invocation_id}")
return None # Allow model call to proceed
// Pseudocode: Callback receiving Context
import { Context, LlmRequest } from '@google/adk';
import { Content } from '@google/genai';
function myBeforeModelCb(context: Context, request: LlmRequest): Content | undefined {
// Read/Write state example
const callCount = (context.state.get('model_calls') as number) || 0;
context.state.set('model_calls', callCount + 1); // Modify state
// Optionally load an artifact
// const configPart = await context.loadArtifact('model_config.json');
console.log(`Preparing model call #${callCount + 1} for invocation ${context.invocationId}`);
return undefined; // Allow model call to proceed
}
import (
"fmt"
"google.golang.org/adk/v2/agent"
"google.golang.org/adk/v2/model"
)
// Pseudocode: Callback receiving CallbackContext
func myBeforeModelCb(ctx agent.Context, req *model.LLMRequest) (*model.LLMResponse, error) {
// Read/Write state example
callCount, err := ctx.State().Get("model_calls")
if err != nil {
callCount = 0 // Default value
}
newCount := callCount.(int) + 1
if err := ctx.State().Set("model_calls", newCount); err != nil {
return nil, err
}
// Optionally load an artifact
// configPart, err := ctx.Artifacts().Load("model_config.json")
fmt.Printf("Preparing model call #%d for invocation %s\n", newCount, ctx.InvocationID())
return nil, nil // Allow model call to proceed
}
// Example: Callback receiving CallbackContext
import com.google.adk.agents.CallbackContext;
import com.google.adk.models.LlmRequest;
import com.google.adk.models.LlmResponse;
import io.reactivex.rxjava3.core.Maybe;
public Maybe<LlmResponse> myBeforeModelCb(CallbackContext callbackContext, LlmRequest request) {
// Read/Write state example
int callCount = (int) callbackContext.state().getOrDefault("model_calls", 0);
callbackContext.state().put("model_calls", callCount + 1); // Modify state (tracks delta)
// Optionally load an artifact
// Maybe<Part> configPart = callbackContext.loadArtifact("model_config.json");
System.out.println("Preparing model call " + (callCount + 1) + " for invocation " + callbackContext.invocationId());
return Maybe.empty(); // Allow model call to proceed
}
import com.google.adk.kt.agents.CallbackContext
import com.google.adk.kt.callbacks.CallbackChoice
import com.google.adk.kt.models.LlmRequest
import com.google.adk.kt.models.LlmResponse
// Example: Callback receiving CallbackContext
suspend fun myBeforeModelCb(
context: CallbackContext,
request: LlmRequest,
): CallbackChoice<LlmRequest, LlmResponse> {
// Read/Write state example
val callCount = context.state["model_calls"] as? Int ?: 0
context.updateState("model_calls", callCount + 1) // Modify state (tracks delta)
// Optionally load an artifact
// val configPart = context.loadArtifact("model_config.json")
println("Preparing model call #${callCount + 1} for invocation ${context.invocationId}")
return CallbackChoice.Continue(request) // Allow model call to proceed
}
ToolContext¶
- 使用場所:
FunctionToolを支える関数や、ツールの実行コールバック(before_tool_callback、after_tool_callback)にtool_contextとして渡されます。 - 目的:
CallbackContextが提供するすべてに加えて、認証の処理、メモリの検索、アーティファクトの一覧表示など、ツールの実行に不可欠な特化したメソッドを提供します。 -
主な機能(
CallbackContextに追加):- 認証メソッド: 認証フローをトリガーする
request_credential(auth_config)と、ユーザー/システムによって提供された認証情報を取得するget_auth_response(auth_config)。 - アーティファクトの一覧表示: セッションで利用可能なアーティファクトを発見する
list_artifacts()。 - メモリ検索: 設定された
memory_serviceにクエリを実行するsearch_memory(query)。 function_call_idプロパティ: このツールの実行をトリガーしたLLMからの特定の関数呼び出しを識別し、認証要求や応答を正しくリンクするために重要です。actionsプロパティ: このステップのEventActionsオブジェクトに直接アクセスし、ツールが状態の変更、認証要求などを通知できるようにします。
# Example: Tool function receiving ToolContext from google.adk.tools import ToolContext from typing import Dict, Any # Assume this function is wrapped by a FunctionTool def search_external_api(query: str, tool_context: ToolContext) -> Dict[str, Any]: api_key = tool_context.state.get("api_key") if not api_key: # Define required auth config # auth_config = AuthConfig(...) # tool_context.request_credential(auth_config) # Request credentials # Use the 'actions' property to signal the auth request has been made # tool_context.actions.requested_auth_configs[tool_context.function_call_id] = auth_config return {"status": "Auth Required"} # Use the API key... print(f"Tool executing for query '{query}' using API key. Invocation: {tool_context.invocation_id}") # Optionally search memory or list artifacts # relevant_docs = tool_context.search_memory(f"info related to {query}") # available_files = tool_context.list_artifacts() return {"result": f"Data for {query} fetched."}// Pseudocode: Tool function receiving Context import { Context } from '@google/adk'; // __Assume this function is wrapped by a FunctionTool__ function searchExternalApi(query: string, context: Context): { [key: string]: string } { const apiKey = context.state.get('api_key') as string; if (!apiKey) { // Define required auth config // const authConfig = new AuthConfig(...); // context.requestCredential(authConfig); // Request credentials // The 'actions' property is now automatically updated by requestCredential return { status: 'Auth Required' }; } // Use the API key... console.log(`Tool executing for query '${query}' using API key. Invocation: ${context.invocationId}`); // Optionally search memory or list artifacts // Note: accessing services like memory/artifacts is typically async in TS, // so you would need to mark this function 'async' if you reused them. // context.searchMemory(`info related to ${query}`).then(...) // context.listArtifacts().then(...) return { result: `Data for ${query} fetched.` }; }import "google.golang.org/adk/v2/tool" // Pseudocode: Tool function receiving ToolContext type searchExternalAPIArgs struct { Query string `json:"query" jsonschema:"The query to search for."` } func searchExternalAPI(tc agent.Context, input searchExternalAPIArgs) (string, error) { apiKey, err := tc.State().Get("api_key") if err != nil || apiKey == "" { // In a real scenario, you would define and request credentials here. // This is a conceptual placeholder. return "", fmt.Errorf("auth required") } // Use the API key... fmt.Printf("Tool executing for query '%s' using API key. Invocation: %s\n", input.Query, tc.InvocationID()) // Optionally search memory or list artifacts // relevantDocs, _ := tc.SearchMemory(tc, "info related to %s", input.Query)) // availableFiles, _ := tc.Artifacts().List() return fmt.Sprintf("Data for %s fetched.", input.Query), nil }// Example: Tool function receiving ToolContext import com.google.adk.tools.ToolContext; import java.util.Map; // Assume this function is wrapped by a FunctionTool public Map<String, Object> searchExternalApi(String query, ToolContext toolContext) { String apiKey = (String) toolContext.state().getOrDefault("api_key", ""); if (apiKey.isEmpty()) { // Define required auth config // authConfig = AuthConfig(...); // toolContext.requestCredential(authConfig); // Request credentials // Use the 'actions' property to signal the auth request has been made return Map.of("status", "Auth Required"); } // Use the API key... System.out.println("Tool executing for query " + query + " using API key."); // Optionally list artifacts // Single<List<String>> availableFiles = toolContext.listArtifacts(); return Map.of("result", "Data for " + query + " fetched"); }import com.google.adk.kt.tools.ToolContext // Example: Tool function receiving ToolContext // Assume this function is wrapped by a FunctionTool fun searchExternalApi( query: String, toolContext: ToolContext, ): Map<String, Any> { val apiKey = toolContext.state["api_key"] as? String if (apiKey.isNullOrEmpty()) { return mapOf("status" to "Auth Required") } // Use the API key... println( "Tool executing for query '$query' using API key. " + "Invocation: ${toolContext.invocationId}", ) // Optionally search memory or list artifacts // val relevantDocs = toolContext.memoryService?.searchMemory( // toolContext.session.key.appName, toolContext.userId, "info related to $query") // val availableFiles = toolContext.listArtifacts() return mapOf("result" to "Data for $query fetched.") } - 認証メソッド: 認証フローをトリガーする
これらの異なるコンテキストオブジェクトと、それらをいつ使用するかを理解することは、ADKアプリケーションの状態を効果的に管理し、サービスにアクセスし、フローを制御するための鍵となります。
コンテキストを使用した一般的なタスク¶
様々なコンテキストオブジェクトについて理解したところで、エージェントやツールを構築する際に、それらを使って一般的なタスクを実行する方法に焦点を当てましょう。
情報へのアクセス¶
コンテキスト内に保存された情報を読み取る必要が頻繁にあります。
-
セッション状態の読み取り: 以前のステップで保存されたデータや、ユーザー/アプリレベルの設定にアクセスします。
stateプロパティに対して辞書のようにアクセスします。# Example: In a Tool function from google.adk.tools import ToolContext def my_tool(tool_context: ToolContext, **kwargs): user_pref = tool_context.state.get("user_display_preference", "default_mode") api_endpoint = tool_context.state.get("app:api_endpoint") # Read app-level state if user_pref == "dark_mode": # ... apply dark mode logic ... pass print(f"Using API endpoint: {api_endpoint}") # ... rest of tool logic ... # Example: In a Callback function from google.adk.agents.context import Context def my_callback(context: Context, **kwargs): last_tool_result = context.state.get("temp:last_api_result") # Read temporary state if last_tool_result: print(f"Found temporary result from last tool: {last_tool_result}") # ... callback logic ...// Pseudocode: In a Tool function import { Context } from '@google/adk'; async function myTool(context: Context) { const userPref = context.state.get('user_display_preference', 'default_mode'); const apiEndpoint = context.state.get('app:api_endpoint'); // Read app-level state if (userPref === 'dark_mode') { // ... apply dark mode logic ... } console.log(`Using API endpoint: ${apiEndpoint}`); // ... rest of tool logic ... } // Pseudocode: In a Callback function import { Context } from '@google/adk'; function myCallback(context: Context) { const lastToolResult = context.state.get('temp:last_api_result'); // Read temporary state if (lastToolResult) { console.log(`Found temporary result from last tool: ${lastToolResult}`); } // ... callback logic ... }import ( "google.golang.org/adk/v2/agent" "google.golang.org/adk/v2/session" "google.golang.org/adk/v2/tool" "google.golang.org/genai" ) // Pseudocode: In a Tool function type toolArgs struct { // Define tool-specific arguments here } type toolResults struct { // Define tool-specific results here } // Example tool function demonstrating state access func myTool(tc agent.Context, input toolArgs) (toolResults, error) { userPref, err := tc.State().Get("user_display_preference") if err != nil { userPref = "default_mode" } apiEndpoint, _ := tc.State().Get("app:api_endpoint") // Read app-level state if userPref == "dark_mode" { // ... apply dark mode logic ... } fmt.Printf("Using API endpoint: %v\n", apiEndpoint) // ... rest of tool logic ... return toolResults{}, nil } // Pseudocode: In a Callback function func myCallback(ctx agent.Context) (*genai.Content, error) { lastToolResult, err := ctx.State().Get("temp:last_api_result") // Read temporary state if err == nil { fmt.Printf("Found temporary result from last tool: %v\n", lastToolResult) } else { fmt.Println("No temporary result found.") } // ... callback logic ... return nil, nil }import com.google.adk.agents.CallbackContext; import com.google.adk.tools.ToolContext; // Example: In a Tool function public void myTool(ToolContext toolContext) { String userPref = (String) toolContext.state().getOrDefault("user_display_preference", "default_mode"); String apiEndpoint = (String) toolContext.state().get("app:api_endpoint"); // Read app-level state if ("dark_mode".equals(userPref)) { // ... apply dark mode logic ... } System.out.println("Using API endpoint: " + apiEndpoint); // ... rest of tool logic ... } // Example: In a Callback function public void myCallback(CallbackContext callbackContext) { String lastToolResult = (String) callbackContext.state().get("temp:last_api_result"); // Read temporary state if (lastToolResult != null && !lastToolResult.isEmpty()) { System.out.println("Found temporary result from last tool: " + lastToolResult); } // ... callback logic ... }import com.google.adk.kt.agents.CallbackContext import com.google.adk.kt.tools.ToolContext // Example: In a Tool function fun myTool(toolContext: ToolContext) { val userPref = toolContext.state["user_display_preference"] as? String ?: "default_mode" val apiEndpoint = toolContext.state["app:api_endpoint"] // Read app-level state if (userPref == "dark_mode") { // ... apply dark mode logic ... } println("Using API endpoint: $apiEndpoint") // ... rest of tool logic ... } // Example: In a Callback function fun myCallback(context: CallbackContext) { val lastToolResult = context.state["temp:last_api_result"] // Read temporary state if (lastToolResult != null) { println("Found temporary result from last tool: $lastToolResult") } // ... callback logic ... } -
現在の識別子の取得: ロギングや、現在の操作に基づいたカスタムロジックに便利です。
# Example: In any context (ToolContext shown) from google.adk.tools import ToolContext def log_tool_usage(tool_context: ToolContext, **kwargs): agent_name = tool_context.agent_name inv_id = tool_context.invocation_id func_call_id = getattr(tool_context, 'function_call_id', 'N/A') # Specific to ToolContext print(f"Log: Invocation={inv_id}, Agent={agent_name}, FunctionCallID={func_call_id} - Tool Executed.")// Pseudocode: In any context import { Context } from '@google/adk'; function logToolUsage(context: Context) { const agentName = context.agentName; const invId = context.invocationId; const functionCallId = context.functionCallId ?? 'N/A'; // Available when executing a tool console.log(`Log: Invocation=${invId}, Agent=${agentName}, FunctionCallID=${functionCallId} - Tool Executed.`); }import "google.golang.org/adk/v2/tool" // Pseudocode: In any context (ToolContext shown) type logToolUsageArgs struct{} type logToolUsageResult struct { Status string `json:"status"` } func logToolUsage(tc agent.Context, args logToolUsageArgs) (logToolUsageResult, error) { agentName := tc.AgentName() invID := tc.InvocationID() funcCallID := tc.FunctionCallID() fmt.Printf("Log: Invocation=%s, Agent=%s, FunctionCallID=%s - Tool Executed.\n", invID, agentName, funcCallID) return logToolUsageResult{Status: "Logged successfully"}, nil }// Example: In any context (ToolContext shown) import com.google.adk.tools.ToolContext; public void logToolUsage(ToolContext toolContext) { String agentName = toolContext.agentName(); String invId = toolContext.invocationId(); String functionCallId = toolContext.functionCallId().orElse("N/A"); // Specific to ToolContext System.out.println("Log: Invocation= " + invId + " Agent= " + agentName + " FunctionCallID= " + functionCallId); }import com.google.adk.kt.tools.ToolContext // Example: In any context (ToolContext shown) fun logToolUsage(toolContext: ToolContext) { val agentName = toolContext.agentName val invId = toolContext.invocationId val funcCallId = toolContext.functionCallId ?: "N/A" // Set only during a tool call println("Log: Invocation=$invId, Agent=$agentName, FunctionCallID=$funcCallId - Tool Executed.") } -
最初のユーザー入力へのアクセス: 現在の呼び出しを開始したメッセージを再参照します。
# Example: In a Callback from google.adk.agents.context import Context def check_initial_intent(context: Context, **kwargs): initial_text = "N/A" if context.user_content and context.user_content.parts: initial_text = context.user_content.parts[0].text or "Non-text input" print(f"This invocation started with user input: '{initial_text}'") # Example: In an Agent's _run_async_impl # async def _run_async_impl(self, ctx: InvocationContext) -> AsyncGenerator[Event, None]: # if ctx.user_content and ctx.user_content.parts: # initial_text = ctx.user_content.parts[0].text # print(f"Agent logic remembering initial query: {initial_text}") # ...// Pseudocode: In a Callback import { Context } from '@google/adk'; function checkInitialIntent(context: Context) { let initialText = 'N/A'; const userContent = context.userContent; if (userContent?.parts?.length) { initialText = userContent.parts[0].text ?? 'Non-text input'; } console.log(`This invocation started with user input: '${initialText}'`); }import ( "fmt" "google.golang.org/adk/v2/agent" "google.golang.org/genai" ) // Pseudocode: In a Callback func logInitialUserInput(ctx agent.Context) (*genai.Content, error) { userContent := ctx.UserContent() if userContent != nil && len(userContent.Parts) > 0 { if text := userContent.Parts[0].Text; text != "" { fmt.Printf("User's initial input for this turn: '%s'\n", text) } } return nil, nil // No modification }// Example: In a Callback import com.google.adk.agents.CallbackContext; import com.google.genai.types.Content; public void checkInitialIntent(CallbackContext callbackContext) { String initialText = "N/A"; if (callbackContext.userContent().isPresent() && callbackContext.userContent().get().parts() != null && !callbackContext.userContent().get().parts().get().isEmpty()) { initialText = callbackContext.userContent().get().parts().get().get(0).text().orElse("Non-text input"); // ... System.out.println("This invocation started with user input: " + initialText); } }import com.google.adk.kt.agents.CallbackContext // Example: In a Callback fun checkInitialIntent(context: CallbackContext) { var initialText = "N/A" val parts = context.userContent?.parts if (!parts.isNullOrEmpty()) { initialText = parts[0].text ?: "Non-text input" } println("This invocation started with user input: '$initialText'") } // Example: In an Agent's runAsyncImpl // override fun runAsyncImpl(context: InvocationContext): Flow<Event> = flow { // val initialText = context.userContent?.parts?.firstOrNull()?.text // if (initialText != null) { // println("Agent logic remembering initial query: $initialText") // } // ... // }
状態管理¶
状態は、メモリとデータフローにとって非常に重要です。CallbackContextやToolContextを使って状態を変更すると、その変更はフレームワークによって自動的に追跡され、永続化されます。
-
仕組み:
callback_context.state['my_key'] = my_valueやtool_context.state['my_key'] = my_valueに書き込むと、この変更が現在のステップのイベントに関連付けられたEventActions.state_deltaに追加されます。そして、SessionServiceがイベントを永続化する際にこれらのデルタを適用します。 -
ツール間でのデータ受け渡し
# Example: Tool 1 - Fetches user ID from google.adk.tools import ToolContext import uuid def get_user_profile(tool_context: ToolContext) -> dict: user_id = str(uuid.uuid4()) # Simulate fetching ID # Save the ID to state for the next tool tool_context.state["temp:current_user_id"] = user_id return {"profile_status": "ID generated"} # Example: Tool 2 - Uses user ID from state def get_user_orders(tool_context: ToolContext) -> dict: user_id = tool_context.state.get("temp:current_user_id") if not user_id: return {"error": "User ID not found in state"} print(f"Fetching orders for user ID: {user_id}") # ... logic to fetch orders using user_id ... return {"orders": ["order123", "order456"]}// Pseudocode: Tool 1 - Fetches user ID import { Context } from '@google/adk'; import { v4 as uuidv4 } from 'uuid'; function getUserProfile(context: Context): Record<string, string> { const userId = uuidv4(); // Simulate fetching ID // Save the ID to state for the next tool context.state.set('temp:current_user_id', userId); return { profile_status: 'ID generated' }; } // Pseudocode: Tool 2 - Uses user ID from state function getUserOrders(context: Context): Record<string, string | string[]> { const userId = context.state.get('temp:current_user_id'); if (!userId) { return { error: 'User ID not found in state' }; } console.log(`Fetching orders for user ID: ${userId}`); // ... logic to fetch orders using user_id ... return { orders: ['order123', 'order456'] }; }import "google.golang.org/adk/v2/tool" // Pseudocode: Tool 1 - Fetches user ID type GetUserProfileArgs struct { } func getUserProfile(tc agent.Context, input GetUserProfileArgs) (string, error) { // A random user ID for demonstration purposes userID := "random_user_456" // Save the ID to state for the next tool if err := tc.State().Set("temp:current_user_id", userID); err != nil { return "", fmt.Errorf("failed to set user ID in state: %w", err) } return "ID generated", nil } // Pseudocode: Tool 2 - Uses user ID from state type GetUserOrdersArgs struct { } type getUserOrdersResult struct { Orders []string `json:"orders"` } func getUserOrders(tc agent.Context, input GetUserOrdersArgs) (*getUserOrdersResult, error) { userID, err := tc.State().Get("temp:current_user_id") if err != nil { return &getUserOrdersResult{}, fmt.Errorf("user ID not found in state") } fmt.Printf("Fetching orders for user ID: %v\n", userID) // ... logic to fetch orders using user_id ... return &getUserOrdersResult{Orders: []string{"order123", "order456"}}, nil }// Example: Tool 1 - Fetches user ID import com.google.adk.tools.ToolContext; import java.util.Map; import java.util.UUID; public Map<String, String> getUserProfile(ToolContext toolContext) { String userId = UUID.randomUUID().toString(); // Save the ID to state for the next tool toolContext.state().put("temp:current_user_id", userId); return Map.of("profile_status", "ID generated"); } // Example: Tool 2 - Uses user ID from state public Map<String, String> getUserOrders(ToolContext toolContext) { String userId = (String) toolContext.state().get("temp:current_user_id"); if (userId == null || userId.isEmpty()) { return Map.of("error", "User ID not found in state"); } System.out.println("Fetching orders for user id: " + userId); // ... logic to fetch orders using userId ... return Map.of("orders", "order123"); }import com.google.adk.kt.tools.ToolContext import java.util.UUID // Example: Tool 1 - Fetches user ID fun getUserProfile(toolContext: ToolContext): Map<String, Any> { val userId = UUID.randomUUID().toString() // Simulate fetching ID // Save the ID to state for the next tool toolContext.updateState("temp:current_user_id", userId) return mapOf("profile_status" to "ID generated") } // Example: Tool 2 - Uses user ID from state fun getUserOrders(toolContext: ToolContext): Map<String, Any> { val userId = toolContext.state["temp:current_user_id"] as? String ?: return mapOf("error" to "User ID not found in state") println("Fetching orders for user ID: $userId") // ... logic to fetch orders using userId ... return mapOf("orders" to listOf("order123", "order456")) } -
ユーザー設定の更新:
# Example: Tool or Callback identifies a preference from google.adk.tools import ToolContext # Or Context def set_user_preference(tool_context: ToolContext, preference: str, value: str) -> dict: # Use 'user:' prefix for user-level state (if using a persistent SessionService) state_key = f"user:{preference}" tool_context.state[state_key] = value print(f"Set user preference '{preference}' to '{value}'") return {"status": "Preference updated"}// Pseudocode: Tool or Callback identifies a preference import { Context } from '@google/adk'; function setUserPreference(context: Context, preference: string, value: string): Record<string, string> { // Use 'user:' prefix for user-level state (if using a persistent SessionService) const stateKey = `user:${preference}`; context.state.set(stateKey, value); console.log(`Set user preference '${preference}' to '${value}'`); return { status: 'Preference updated' }; }import "google.golang.org/adk/v2/tool" // Pseudocode: Tool or Callback identifies a preference type setUserPreferenceArgs struct { Preference string `json:"preference" jsonschema:"The name of the preference to set."` Value string `json:"value" jsonschema:"The value to set for the preference."` } type setUserPreferenceResult struct { Status string `json:"status"` } func setUserPreference(tc agent.Context, args setUserPreferenceArgs) (setUserPreferenceResult, error) { // Use 'user:' prefix for user-level state (if using a persistent SessionService) stateKey := fmt.Sprintf("user:%s", args.Preference) if err := tc.State().Set(stateKey, args.Value); err != nil { return setUserPreferenceResult{}, fmt.Errorf("failed to set preference in state: %w", err) } fmt.Printf("Set user preference '%s' to '%s'\n", args.Preference, args.Value) return setUserPreferenceResult{Status: "Preference updated"}, nil }// Example: Tool or Callback identifies a preference import com.google.adk.tools.ToolContext; // Or CallbackContext public Map<String, String> setUserPreference(ToolContext toolContext, String preference, String value) { // Use 'user:' prefix for user-level state (if using a persistent SessionService) String stateKey = "user:" + preference; toolContext.state().put(stateKey, value); System.out.println("Set user preference '" + preference + "' to '" + value + "'"); return Map.of("status", "Preference updated"); }import com.google.adk.kt.tools.ToolContext // Example: Tool or Callback identifies a preference fun setUserPreference( // Or CallbackContext toolContext: ToolContext, preference: String, value: String, ): Map<String, Any> { // Use 'user:' prefix for user-level state (if using a persistent SessionService) val stateKey = "user:$preference" toolContext.updateState(stateKey, value) println("Set user preference '$preference' to '$value'") return mapOf("status" to "Preference updated") } -
状態のプレフィックス: 基本的な状態はセッション固有ですが、
app:やuser:のようなプレフィックスは、永続的なSessionService実装(DatabaseSessionServiceやVertexAiSessionServiceなど)と共に使用して、より広いスコープ(アプリ全体またはセッションをまたいだユーザー全体)を示すことができます。temp:は、現在の呼び出し内でのみ関連するデータを示すために使用できます。
アーティファクトの操作¶
セッションに関連付けられたファイルや大きなデータのかたまりを扱うには、アーティファクトを使用します。一般的なユースケース:アップロードされたドキュメントの処理。
-
ドキュメント要約器のフロー例:
-
参照の取り込み(例:セットアップツールやコールバック内): ドキュメントのコンテンツ全体ではなく、パスやURIをアーティファクトとして保存します。
# Example: In a callback or initial tool from google.adk.agents.context import Context # Or ToolContext from google.genai import types async def save_document_reference(context: Context, file_path: str) -> None: # Assume file_path is something like "gs://my-bucket/docs/report.pdf" or "/local/path/to/report.pdf" try: # Create a Part containing the path/URI text artifact_part = types.Part.from_text(text=file_path) version = await context.save_artifact("document_to_summarize.txt", artifact_part) print(f"Saved document reference '{file_path}' as artifact version {version}") # Store the filename in state if needed by other tools context.state["temp:doc_artifact_name"] = "document_to_summarize.txt" except ValueError as e: print(f"Error saving artifact: {e}") # E.g., Artifact service not configured except Exception as e: print(f"Unexpected error saving artifact reference: {e}") # Example usage: # save_document_reference(context, "gs://my-bucket/docs/report.pdf")// Pseudocode: In a callback or initial tool import { Context } from '@google/adk'; import type { Part } from '@google/genai'; async function saveDocumentReference(context: Context, filePath: string) { // Assume filePath is something like "gs://my-bucket/docs/report.pdf" or "/local/path/to/report.pdf" try { // Create a Part containing the path/URI text const artifactPart: Part = { text: filePath }; const version = await context.saveArtifact('document_to_summarize.txt', artifactPart); console.log(`Saved document reference '${filePath}' as artifact version ${version}`); // Store the filename in state if needed by other tools context.state.set('temp:doc_artifact_name', 'document_to_summarize.txt'); } catch (e) { console.error(`Unexpected error saving artifact reference: ${e}`); } } // Example usage: // saveDocumentReference(context, "gs://my-bucket/docs/report.pdf");import ( "google.golang.org/adk/v2/tool" "google.golang.org/genai" ) // Adapt the saveDocumentReference callback into a tool for this example. type saveDocRefArgs struct { FilePath string `json:"file_path" jsonschema:"The path to the file to save."` } type saveDocRefResult struct { Status string `json:"status"` } func saveDocRef(tc agent.Context, args saveDocRefArgs) (saveDocRefResult, error) { artifactPart := genai.NewPartFromText(args.FilePath) _, err := tc.Artifacts().Save(tc, "document_to_summarize.txt", artifactPart) if err != nil { return saveDocRefResult{}, err } fmt.Printf("Saved document reference '%s' as artifact\n", args.FilePath) if err := tc.State().Set("temp:doc_artifact_name", "document_to_summarize.txt"); err != nil { return saveDocRefResult{}, fmt.Errorf("failed to set artifact name in state") } return saveDocRefResult{"Reference saved"}, nil }// Example: In a callback or initial tool import com.google.adk.agents.CallbackContext; import com.google.genai.types.Content; import com.google.genai.types.Part; import java.util.Optional; public void saveDocumentReference(CallbackContext context, String filePath) { // Assume file_path is something like "gs://my-bucket/docs/report.pdf" or "/local/path/to/report.pdf" try { // Create a Part containing the path/URI text Part artifactPart = Part.fromText(filePath); Optional<Integer> version = context.saveArtifact("document_to_summarize.txt", artifactPart); System.out.println("Saved document reference" + filePath + " as artifact version " + version.orElse(-1)); // Store the filename in state if needed by other tools context.state().put("temp:doc_artifact_name", "document_to_summarize.txt"); } catch (Exception e) { System.out.println("Unexpected error saving artifact reference: " + e); } } // Example usage: // saveDocumentReference(context, "gs://my-bucket/docs/report.pdf")import com.google.adk.kt.agents.CallbackContext import com.google.adk.kt.types.Part // Example: In a callback or initial tool suspend fun saveDocumentReference( // Or ToolContext context: CallbackContext, filePath: String, ) { // Assume filePath is something like "gs://my-bucket/docs/report.pdf" or "/local/path/to/report.pdf" try { // Create a Part containing the path/URI text val artifactPart = Part(text = filePath) val version = context.saveArtifact("document_to_summarize.txt", artifactPart) println("Saved document reference '$filePath' as artifact version $version") // Store the filename in state if needed by other tools context.updateState("temp:doc_artifact_name", "document_to_summarize.txt") } catch (e: IllegalStateException) { println("Error saving artifact: ${e.message}") // E.g., Artifact service not configured } catch (e: Exception) { println("Unexpected error saving artifact reference: $e") } } // Example usage: // saveDocumentReference(context, "gs://my-bucket/docs/report.pdf") -
要約ツール: アーティファクトをロードしてパス/URIを取得し、適切なライブラリを使用して実際のドキュメントコンテンツを読み取り、要約して結果を返します。
# Example: In the Summarizer tool function from google.adk.tools import ToolContext from google.genai import types # Assume libraries like google.cloud.storage or built-in open are available # Assume a 'summarize_text' function exists # from my_summarizer_lib import summarize_text async def summarize_document_tool(tool_context: ToolContext) -> dict: artifact_name = tool_context.state.get("temp:doc_artifact_name") if not artifact_name: return {"error": "Document artifact name not found in state."} try: # 1. Load the artifact part containing the path/URI artifact_part = await tool_context.load_artifact(artifact_name) if not artifact_part or not artifact_part.text: return {"error": f"Could not load artifact or artifact has no text path: {artifact_name}"} file_path = artifact_part.text print(f"Loaded document reference: {file_path}") # 2. Read the actual document content (outside ADK context) document_content = "" if file_path.startswith("gs://"): # Example: Use GCS client library to download/read pass # Replace with actual GCS reading logic elif file_path.startswith("/"): # Example: Use local file system with open(file_path, 'r', encoding='utf-8') as f: document_content = f.read() else: return {"error": f"Unsupported file path scheme: {file_path}"} # 3. Summarize the content if not document_content: return {"error": "Failed to read document content."} # summary = summarize_text(document_content) # Call your summarization logic summary = f"Summary of content from {file_path}" # Placeholder return {"summary": summary} except ValueError as e: return {"error": f"Artifact service error: {e}"} except FileNotFoundError: return {"error": f"Local file not found: {file_path}"}// Pseudocode: In the Summarizer tool function import { Context } from '@google/adk'; async function summarizeDocumentTool(context: Context): Promise<Record<string, string>> { const artifactName = context.state.get('temp:doc_artifact_name') as string; if (!artifactName) { return { error: 'Document artifact name not found in state.' }; } try { // 1. Load the artifact part containing the path/URI const artifactPart = await context.loadArtifact(artifactName); if (!artifactPart?.text) { return { error: `Could not load artifact or artifact has no text path: ${artifactName}` }; } const filePath = artifactPart.text; console.log(`Loaded document reference: ${filePath}`); // 2. Read the actual document content (outside ADK context) let documentContent = ''; if (filePath.startsWith('gs://')) { // Example: Use GCS client library to download/read // const storage = new Storage(); // const bucket = storage.bucket('my-bucket'); // const file = bucket.file(filePath.replace('gs://my-bucket/', '')); // const [contents] = await file.download(); // documentContent = contents.toString(); } else if (filePath.startsWith('/')) { // Example: Use local file system // import { readFile } from 'fs/promises'; // documentContent = await readFile(filePath, 'utf8'); } else { return { error: `Unsupported file path scheme: ${filePath}` }; } // 3. Summarize the content if (!documentContent) { return { error: 'Failed to read document content.' }; } // const summary = summarizeText(documentContent); // Call your summarization logic const summary = `Summary of content from ${filePath}`; // Placeholder return { summary }; } catch (e) { return { error: `Error processing artifact: ${e}` }; } }import "google.golang.org/adk/v2/tool" // Pseudocode: In the Summarizer tool function type summarizeDocumentArgs struct{} type summarizeDocumentResult struct { Summary string `json:"summary"` } func summarizeDocumentTool(tc agent.Context, input summarizeDocumentArgs) (summarizeDocumentResult, error) { artifactName, err := tc.State().Get("temp:doc_artifact_name") if err != nil { return summarizeDocumentResult{}, fmt.Errorf("No document artifact name found in state") } // 1. Load the artifact part containing the path/URI artifactPart, err := tc.Artifacts().Load(tc, artifactName.(string)) if err != nil { return summarizeDocumentResult{}, err } if artifactPart.Part.Text == "" { return summarizeDocumentResult{}, fmt.Errorf("Could not load artifact or artifact has no text path.") } filePath := artifactPart.Part.Text fmt.Printf("Loaded document reference: %s\n", filePath) // 2. Read the actual document content (outside ADK context) // In a real implementation, you would use a GCS client or local file reader. documentContent := "This is the fake content of the document at " + filePath _ = documentContent // Avoid unused variable error. // 3. Summarize the content summary := "Summary of content from " + filePath // Placeholder return summarizeDocumentResult{Summary: summary}, nil }// Example: In the Summarizer tool function import com.google.adk.tools.ToolContext; import com.google.genai.types.Content; import com.google.genai.types.Part; import java.util.Map; import java.util.Optional; import java.io.FileNotFoundException; public Map<String, String> summarizeDocumentTool(ToolContext toolContext) { String artifactName = (String) toolContext.state().get("temp:doc_artifact_name"); if (artifactName == null || artifactName.isEmpty()) { return Map.of("error", "Document artifact name not found in state."); } try { // 1. Load the artifact part containing the path/URI Optional<Part> artifactPart = toolContext.loadArtifact(artifactName); if (!artifactPart.isPresent() || !artifactPart.get().text().isPresent() || artifactPart.get().text().get().isEmpty()) { return Map.of("error", "Could not load artifact or artifact has no text path: " + artifactName); } String filePath = artifactPart.get().text().get(); System.out.println("Loaded document reference: " + filePath); // 2. Read the actual document content (outside ADK context) String documentContent = ""; if (filePath.startsWith("gs://")) { // Example: Use GCS client library to download/read into documentContent // Replace with actual GCS reading logic } else if (filePath.startsWith("/")) { // Example: Use local file system to download/read into documentContent } else { return Map.of("error", "Unsupported file path scheme: " + filePath); } // 3. Summarize the content if (documentContent.isEmpty()) { return Map.of("error", "Failed to read document content."); } // summary = summarizeText(documentContent) // Call your summarization logic String summary = "Summary of content from " + filePath; // Placeholder return Map.of("summary", summary); } catch (IllegalArgumentException e) { return Map.of("error", "Artifact service error " + e); } catch (Exception e) { return Map.of("error", "Error reading document " + e); } }import com.google.adk.kt.tools.ToolContext import java.io.File import java.io.FileNotFoundException // Example: In the Summarizer tool function // Assume a GCS client library is available // Assume a summarizeText function exists suspend fun summarizeDocumentTool(toolContext: ToolContext): Map<String, Any> { val artifactName = toolContext.state["temp:doc_artifact_name"] as? String ?: return mapOf("error" to "Document artifact name not found in state.") // 1. Load the artifact part containing the path/URI // Returns null if no artifact service is configured or the artifact is not found val artifactPart = toolContext.loadArtifact(artifactName) val filePath = artifactPart?.text ?: return mapOf( "error" to "Could not load artifact or artifact has no text path: $artifactName", ) println("Loaded document reference: $filePath") try { // 2. Read the actual document content (outside ADK context) var documentContent = "" if (filePath.startsWith("gs://")) { // Example: Use GCS client library to download/read // Replace with actual GCS reading logic } else if (filePath.startsWith("/")) { // Example: Use local file system documentContent = File(filePath).readText(Charsets.UTF_8) } else { return mapOf("error" to "Unsupported file path scheme: $filePath") } // 3. Summarize the content if (documentContent.isEmpty()) { return mapOf("error" to "Failed to read document content.") } // val summary = summarizeText(documentContent) // Call your summarization logic val summary = "Summary of content from $filePath" // Placeholder return mapOf("summary" to summary) } catch (e: FileNotFoundException) { return mapOf("error" to "Local file not found: $filePath") } }
-
-
アーティファクトの一覧表示: 利用可能なファイルを確認します。
# Example: In a tool function from google.adk.tools import ToolContext async def check_available_docs(tool_context: ToolContext) -> dict: try: artifact_keys = await tool_context.list_artifacts() print(f"Available artifacts: {artifact_keys}") return {"available_docs": artifact_keys} except ValueError as e: return {"error": f"Artifact service error: {e}"}// Pseudocode: In a tool function import { Context } from '@google/adk'; async function checkAvailableDocs(context: Context): Promise<Record<string, string[] | string>> { try { const artifactKeys = await context.listArtifacts(); console.log(`Available artifacts: ${artifactKeys}`); return { available_docs: artifactKeys }; } catch (e) { return { error: `Artifact service error: ${e}` }; } }import "google.golang.org/adk/v2/tool" // Pseudocode: In a tool function type checkAvailableDocsArgs struct{} type checkAvailableDocsResult struct { AvailableDocs []string `json:"available_docs"` } func checkAvailableDocs(tc agent.Context, args checkAvailableDocsArgs) (checkAvailableDocsResult, error) { artifactKeys, err := tc.Artifacts().List(tc) if err != nil { return checkAvailableDocsResult{}, err } fmt.Printf("Available artifacts: %v\n", artifactKeys) return checkAvailableDocsResult{AvailableDocs: artifactKeys.FileNames}, nil }// Example: In a tool function import com.google.adk.tools.ToolContext; import io.reactivex.rxjava3.core.Single; import java.util.List; import java.util.Map; public Map<String, Object> checkAvailableDocs(ToolContext toolContext) { try { Single<List<String>> artifactKeys = toolContext.listArtifacts(); System.out.println("Available artifacts: " + artifactKeys.blockingGet().toString()); return Map.of("availableDocs", artifactKeys.blockingGet()); } catch (IllegalArgumentException e) { return Map.of("error", "Artifact service error: " + e); } }import com.google.adk.kt.tools.ToolContext // Example: In a tool function suspend fun checkAvailableDocs(toolContext: ToolContext): Map<String, Any> { // Returns an empty list if no artifact service is configured val artifactKeys = toolContext.listArtifacts() println("Available artifacts: $artifactKeys") return mapOf("available_docs" to artifactKeys) }
ツール認証の処理¶
ツールに必要なAPIキーやその他の認証情報を安全に管理します。
# Example: Tool requiring auth
from google.adk.tools import ToolContext
from google.adk.auth import AuthConfig # Assume appropriate AuthConfig is defined
# Define your required auth configuration (e.g., OAuth, API Key)
MY_API_AUTH_CONFIG = AuthConfig(...)
AUTH_STATE_KEY = "user:my_api_credential" # Key to store retrieved credential
def call_secure_api(tool_context: ToolContext, request_data: str) -> dict:
# 1. Check if credential already exists in state
credential = tool_context.state.get(AUTH_STATE_KEY)
if not credential:
# 2. If not, request it
print("Credential not found, requesting...")
try:
tool_context.request_credential(MY_API_AUTH_CONFIG)
# The framework handles yielding the event. The tool execution stops here for this turn.
return {"status": "Authentication required. Please provide credentials."}
except ValueError as e:
return {"error": f"Auth error: {e}"} # e.g., function_call_id missing
except Exception as e:
return {"error": f"Failed to request credential: {e}"}
# 3. If credential exists (might be from a previous turn after request)
# or if this is a subsequent call after auth flow completed externally
try:
# Optionally, re-validate/retrieve if needed, or use directly
# This might retrieve the credential if the external flow just completed
auth_credential_obj = tool_context.get_auth_response(MY_API_AUTH_CONFIG)
api_key = auth_credential_obj.api_key # Or access_token, etc.
# Store it back in state for future calls within the session
tool_context.state[AUTH_STATE_KEY] = auth_credential_obj.model_dump() # Persist retrieved credential
print(f"Using retrieved credential to call API with data: {request_data}")
# ... Make the actual API call using api_key ...
api_result = f"API result for {request_data}"
return {"result": api_result}
except Exception as e:
# Handle errors retrieving/using the credential
print(f"Error using credential: {e}")
# Maybe clear the state key if credential is invalid?
# tool_context.state[AUTH_STATE_KEY] = None
return {"error": "Failed to use credential"}
// Pseudocode: Tool requiring auth
import { Context } from '@google/adk'; // AuthConfig from ADK or custom
// Define a local AuthConfig interface as it's not publicly exported by ADK
interface AuthConfig {
credentialKey: string;
authScheme: { type: string }; // Minimal representation for the example
// Add other properties if they become relevant for the example
}
// Define your required auth configuration (e.g., OAuth, API Key)
const MY_API_AUTH_CONFIG: AuthConfig = {
credentialKey: 'my-api-key', // Example key
authScheme: { type: 'api-key' }, // Example scheme type
};
const AUTH_STATE_KEY = 'user:my_api_credential'; // Key to store retrieved credential
async function callSecureApi(context: Context, requestData: string): Promise<Record<string, string>> {
// 1. Check if credential already exists in state
const credential = context.state.get(AUTH_STATE_KEY);
if (!credential) {
// 2. If not, request it
console.log('Credential not found, requesting...');
try {
context.requestCredential(MY_API_AUTH_CONFIG);
// The framework handles yielding the event. The tool execution stops here for this turn.
return { status: 'Authentication required. Please provide credentials.' };
} catch (e) {
return { error: `Auth or credential request error: ${e}` };
}
}
// 3. If credential exists (might be from a previous turn after request)
// or if this is a subsequent call after auth flow completed externally
try {
// Optionally, re-validate/retrieve if needed, or use directly
// This might retrieve the credential if the external flow just completed
const authCredentialObj = context.getAuthResponse(MY_API_AUTH_CONFIG);
const apiKey = authCredentialObj?.apiKey; // Or accessToken, etc.
// Store it back in state for future calls within the session
// Note: In strict TS, might need to cast or serialize authCredentialObj
context.state.set(AUTH_STATE_KEY, JSON.stringify(authCredentialObj));
console.log(`Using retrieved credential to call API with data: ${requestData}`);
// ... Make the actual API call using apiKey ...
const apiResult = `API result for ${requestData}`;
return { result: apiResult };
} catch (e) {
// Handle errors retrieving/using the credential
console.error(`Error using credential: ${e}`);
// Maybe clear the state key if credential is invalid?
// toolContext.state.set(AUTH_STATE_KEY, null);
return { error: 'Failed to use credential' };
}
}
// Example: Tool requiring auth
import com.google.adk.tools.ToolContext;
import java.util.Map;
// Note: AuthConfig, requestCredential, and getAuthResponse are not yet
// fully implemented in the Java ADK public API.
// This example relies on external auth population into the session state.
public class SecureApiTool {
private static final String AUTH_STATE_KEY = "user:my_api_credential";
public Map<String, String> callSecureApi(ToolContext context, String requestData) {
// 1. Check if credential already exists in state
Object credential = context.state().get(AUTH_STATE_KEY);
if (credential == null) {
// 2. If not, request it
System.out.println("Credential not found, requesting...");
try {
// context.requestCredential(MY_API_AUTH_CONFIG); // Not yet implemented in Java ADK
// The framework handles yielding the event. The tool execution stops here for this turn.
return Map.of("status", "Authentication required. Please provide credentials.");
} catch (Exception e) {
return Map.of("error", "Auth or credential request error: " + e.getMessage());
}
}
// 3. If credential exists (might be from a previous turn after request)
// or if this is a subsequent call after auth flow completed externally
try {
// Optionally, re-validate/retrieve if needed, or use directly
// String apiKey = context.getAuthResponse(MY_API_AUTH_CONFIG).getApiKey();
String apiKey = credential.toString(); // Simplified for example
// Store it back in state for future calls within the session
context.state().put(AUTH_STATE_KEY, apiKey);
System.out.println("Using retrieved credential to call API with data: " + requestData);
// ... Make the actual API call using apiKey ...
String apiResult = "API result for " + requestData;
return Map.of("result", apiResult);
} catch (Exception e) {
// Handle errors retrieving/using the credential
System.err.println("Error using credential: " + e.getMessage());
return Map.of("error", "Failed to use credential");
}
}
}
注意:request_credentialはツールを一時停止し、認証の必要性を通知します。ユーザー/システムが認証情報を提供すると、後続の呼び出しでget_auth_response(または状態の再確認)によってツールが続行できるようになります。 tool_context.function_call_idは、要求と応答をリンクするためにフレームワークによって暗黙的に使用されます。
メモリの活用¶
過去や外部ソースから関連情報にアクセスします。
# Example: Tool using memory search
from google.adk.tools import ToolContext
async def find_related_info(tool_context: ToolContext, topic: str) -> dict:
try:
search_results = await tool_context.search_memory(f"Information about {topic}")
if search_results.memories:
print(f"Found {len(search_results.memories)} memory results for '{topic}'")
# Process search_results.memories (which are MemoryEntry objects)
top_entry = search_results.memories[0]
top_result_text = next(
(part.text for part in (top_entry.content.parts or []) if part.text),
"",
)
return {"memory_snippet": top_result_text}
else:
return {"message": "No relevant memories found."}
except ValueError as e:
return {"error": f"Memory service error: {e}"} # e.g., Service not configured
except Exception as e:
return {"error": f"Unexpected error searching memory: {e}"}
// Pseudocode: Tool using memory search
import { Context } from '@google/adk';
async function findRelatedInfo(context: Context, topic: string): Promise<Record<string, string>> {
try {
const searchResults = await context.searchMemory(`Information about ${topic}`);
if (searchResults.memories.length) {
console.log(`Found ${searchResults.memories.length} memory results for '${topic}'`);
// Process searchResults.memories
const topResultText =
searchResults.memories[0].content.parts?.[0]?.text ?? '';
return { memory_snippet: topResultText };
} else {
return { message: 'No relevant memories found.' };
}
} catch (e) {
return { error: `Memory service error: ${e}` }; // e.g., Service not configured
}
}
// Example: Tool using memory search
import com.google.adk.tools.ToolContext;
import com.google.adk.memory.SearchMemoryResponse;
import io.reactivex.rxjava3.core.Single;
import java.util.Map;
public class MemorySearchTool {
public Single<Map<String, String>> findRelatedInfo(ToolContext context, String topic) {
return context.searchMemory("Information about " + topic)
.map(searchResults -> {
if (searchResults != null && !searchResults.memories().isEmpty()) {
System.out.println("Found " + searchResults.memories().size() + " memory results for '" + topic + "'");
// Process searchResults.memories
String topResultText =
searchResults.memories().get(0).content().text();
return Map.of("memory_snippet", topResultText);
} else {
return Map.of("message", "No relevant memories found.");
}
})
.onErrorReturnItem(Map.of("error", "Memory service error"));
}
}
import com.google.adk.kt.tools.ToolContext
// Example: Tool using memory search
suspend fun findRelatedInfo(
toolContext: ToolContext,
topic: String,
): Map<String, String> {
val memoryService =
toolContext.memoryService
?: return mapOf("error" to "Memory service error: not configured")
return try {
val searchResults =
memoryService.searchMemory(
appName = toolContext.session.key.appName,
userId = toolContext.userId,
query = "Information about $topic",
)
if (searchResults.memories.isNotEmpty()) {
println("Found ${searchResults.memories.size} memory results for '$topic'")
// Process searchResults.memories (which are MemoryEntry objects)
val topEntry = searchResults.memories[0]
val topResultText = topEntry.content.parts.firstNotNullOfOrNull { it.text } ?: ""
mapOf("memory_snippet" to topResultText)
} else {
mapOf("message" to "No relevant memories found.")
}
} catch (e: Exception) {
mapOf("error" to "Unexpected error searching memory: $e")
}
}
UI ウィジェットのレンダリング¶
エージェントのレスポンスとともにリッチな UI コンポーネント(MCP アプリの iframe など)をクライアントに送信するには、context.render_ui_widget() を使用します。
from google.adk.events.ui_widget import UiWidget
from google.adk.tools import ToolContext
def render_styled_widget(color: str, context: ToolContext) -> str:
"""Render a UI widget utilizing the user-specified color."""
widget = UiWidget(
id="my_status_dashboard",
provider="mcp",
payload={
"resource_uri": "ui://analytics/status",
"tool": {"name": "get_system_status"},
"tool_args": {"theme_color": color} # Dynamically passed from user interaction
}
)
context.render_ui_widget(widget)
return f"Widget successfully rendered with color: {color}"
高度な使用方法: 直接的な InvocationContext の使用¶
ほとんどのやり取りは CallbackContext または ToolContext を介して行われますが、エージェントのコアロジック(Python の _run_async_impl や _run_live_impl、または TypeScript、Java、Kotlin の runAsyncImpl など)で直接アクセスが必要になる場合があります。
# Example: Inside agent's _run_async_impl
from google.adk.agents import BaseAgent
from google.adk.agents.invocation_context import InvocationContext
from google.adk.events import Event
from google.genai import types
from typing import AsyncGenerator
class MyControllingAgent(BaseAgent):
async def _run_async_impl(self, ctx: InvocationContext) -> AsyncGenerator[Event, None]:
# Example: Check if a specific service is available
if not ctx.memory_service:
print("Memory service is not available for this invocation.")
# Potentially change agent behavior
# Example: Early termination based on some condition
if ctx.session.state.get("critical_error_flag"):
print("Critical error detected, ending invocation.")
ctx.end_invocation = True # Signal framework to stop processing
yield Event(
author=self.name,
invocation_id=ctx.invocation_id,
content=types.Content(
role="model",
parts=[types.Part(text="Stopping due to critical error.")],
),
)
return # Stop this agent's execution
# ... Normal agent processing ...
yield # ... event ...
// Pseudocode: Inside agent's runAsyncImpl
import { BaseAgent, InvocationContext } from '@google/adk';
import type { Event } from '@google/adk';
class MyControllingAgent extends BaseAgent {
async *runAsyncImpl(ctx: InvocationContext): AsyncGenerator<Event, void, undefined> {
// Example: Check if a specific service is available
if (!ctx.memoryService) {
console.log('Memory service is not available for this invocation.');
// Potentially change agent behavior
}
// Example: Early termination based on some condition
// Direct access to state via ctx.session.state or through ctx.session.state property if wrapped
if ((ctx.session.state as { 'critical_error_flag': boolean })['critical_error_flag']) {
console.log('Critical error detected, ending invocation.');
ctx.endInvocation = true; // Signal framework to stop processing
yield {
author: this.name,
invocationId: ctx.invocationId,
content: { parts: [{ text: 'Stopping due to critical error.' }] }
} as Event;
return; // Stop this agent's execution
}
// ... Normal agent processing ...
yield; // ... event ...
}
}
// Example: Inside agent's runAsyncImpl
import com.google.adk.agents.BaseAgent;
import com.google.adk.agents.InvocationContext;
import com.google.adk.events.Event;
import com.google.genai.types.Content;
import com.google.genai.types.Part;
import io.reactivex.rxjava3.core.Flowable;
import java.util.List;
public class MyControllingAgent extends BaseAgent {
@Override
protected Flowable<Event> runAsyncImpl(InvocationContext ctx) {
// Example: Check if a specific service is available
if (ctx.memoryService() == null) {
System.out.println("Memory service is not available for this invocation.");
// Potentially change agent behavior
}
// Example: Early termination based on some condition
Boolean criticalError = (Boolean) ctx.session().state().getOrDefault("critical_error_flag", false);
if (criticalError != null && criticalError) {
System.out.println("Critical error detected, ending invocation.");
ctx.setEndInvocation(true); // Signal framework to stop processing
Event errorEvent = Event.builder()
.author(name())
.invocationId(ctx.invocationId())
.content(Content.builder().parts(List.of(Part.builder().text("Stopping due to critical error.").build())).build())
.build();
return Flowable.just(errorEvent); // Stop this agent's execution
}
// ... Normal agent processing ...
// return Flowable.just(normalEvent);
return Flowable.empty();
}
}
import com.google.adk.kt.agents.BaseAgent
import com.google.adk.kt.agents.InvocationContext
import com.google.adk.kt.events.Event
import com.google.adk.kt.types.Content
import com.google.adk.kt.types.Part
import com.google.adk.kt.types.Role
import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.flow
// Example: Inside agent's runAsyncImpl
class MyControllingAgent(
name: String,
) : BaseAgent(name = name) {
override fun runAsyncImpl(context: InvocationContext): Flow<Event> =
flow {
// Example: Check if a specific service is available
if (context.memoryService == null) {
println("Memory service is not available for this invocation.")
// Potentially change agent behavior
}
// Example: Early termination based on some condition
if (context.session.state["critical_error_flag"] == true) {
println("Critical error detected, ending invocation.")
context.isEndOfInvocation = true // Signal framework to stop processing
emit(
Event(
author = name,
invocationId = context.invocationId,
content =
Content(
role = Role.MODEL,
parts = listOf(Part(text = "Stopping due to critical error.")),
),
),
)
return@flow // Stop this agent's execution
}
// ... Normal agent processing ...
// emit(...) // ... event ...
}
}
呼び出し終了フラグを True に設定することは、エージェントまたはそのコールバックやツールの内部から(基盤となる InvocationContext のフラグを変更する権限も持つそれぞれのコンテキストオブジェクトを介して)リクエストとレスポンスのサイクル全体を正常に停止する方法です。具体的には、Python では ctx.end_invocation = True、TypeScript では ctx.endInvocation = true、Java では ctx.setEndInvocation(true)、Kotlin では context.isEndOfInvocation = true または context.endInvocation() を使用します。
要点とベストプラクティス¶
- 適切なコンテキストを使用する: 常に提供される最も具体的なコンテキストオブジェクトを使用してください(ツール/ツールコールバックでは
ToolContext、エージェント/モデルコールバックではCallbackContext、該当する場合はReadonlyContext)。完全なInvocationContext(ctx)は、必要な場合にのみ_run_async_impl/_run_live_implで直接使用してください。 - データフローのための状態:
context.stateは、呼び出し内でデータを共有し、好みを記憶し、会話メモリを管理するための主要な方法です。永続ストレージを使用する場合は、プレフィックス(app:、user:、temp:)を慎重に使用してください。 - ファイルのためのアーティファクト: ファイル参照(パスやURIなど)や大きなデータのかたまりを管理するには、
context.save_artifactとcontext.load_artifactを使用してください。参照を保存し、必要に応じてコンテンツをロードします。 - 追跡される変更: コンテキストメソッドを介して状態やアーティファクトに行われた変更は、現在のステップの
EventActionsに自動的にリンクされ、SessionServiceによって処理されます。 - UI のレンダリング:
context.render_ui_widget(widget)を使用して、リッチな UI コンポーネント(MCP アプリの iframe など)をクライアントに送信します。 - シンプルに始める: まずは
stateと基本的なアーティファクトの使用に焦点を当ててください。ニーズがより複雑になるにつれて、認証、メモリ、および高度なInvocationContextのフィールド(ライブストリーミング用のものなど)を探求してください。
これらのコンテキストオブジェクトを理解し効果的に使用することで、ADKでより洗練され、ステートフルで、有能なエージェントを構築することができます。