コンテンツにスキップ

エージェント コンテキスト

ADKでサポートPython v0.1.0TypeScript v0.2.0Go v0.1.0Java v0.1.0Kotlin v0.1.0

Agent Development Kit (ADK) において、コンテキストとは、エージェントとそのツールが特定の操作中に利用できる重要な情報の集合体を指します。現在のタスクや会話のターンを効果的に処理するために必要な背景知識やリソースだと考えてください。

エージェントがうまく機能するためには、多くの場合、最新のユーザーメッセージ以上の情報が必要です。コンテキストは以下を可能にするため、不可欠です。

  1. 状態の維持: 会話の複数のステップにわたる詳細(例:ユーザーの好み、以前の計算結果、ショッピングカートのアイテム)を記憶します。これは主にセッション状態(session state)を通じて管理されます。
  2. データの受け渡し: あるステップ(LLMの呼び出しやツールの実行など)で発見または生成された情報を、後続のステップと共有します。ここでもセッション状態が鍵となります。
  3. サービスへのアクセス: 以下のようなフレームワークの機能と対話します。
    • アーティファクトストレージ: セッションに関連付けられたファイルやデータのかたまり(PDF、画像、設定ファイルなど)を保存または読み込みます。
    • メモリ: ユーザーに関連する過去の対話や外部の知識ソースから関連情報を検索します。
    • 認証: ツールが外部APIに安全にアクセスするために必要な認証情報を要求および取得します。
  4. IDと追跡: 現在どのエージェントが実行されているか(agent.name)を把握し、ロギングとデバッグのために現在のリクエスト-レスポンスサイクル(invocation_id)を一意に識別します。
  5. ツール固有のアクション: 現在の対話の詳細へのアクセスを必要とする、認証要求やメモリ検索など、ツール内での特化した操作を有効にします。

単一の完全なユーザーリクエストから最終レスポンスまでのサイクル(呼び出し (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:は、現在の呼び出し内でのみ関連するデータを示すために使用できます。

アーティファクトの操作

セッションに関連付けられたファイルや大きなデータのかたまりを扱うには、アーティファクトを使用します。一般的なユースケース:アップロードされたドキュメントの処理。

  • ドキュメント要約器のフロー例:

    1. 参照の取り込み(例:セットアップツールやコールバック内): ドキュメントのコンテンツ全体ではなく、パスや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")
      
    2. 要約ツール: アーティファクトをロードしてパス/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)
    }
    

ツール認証の処理

ADKでサポートPython v0.1.0TypeScript v0.2.0Java v0.2.0

ツールに必要な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は、要求と応答をリンクするためにフレームワークによって暗黙的に使用されます。

メモリの活用

ADKでサポートPython v0.1.0TypeScript v0.2.0Java v0.2.0Kotlin v0.1.0

過去や外部ソースから関連情報にアクセスします。

# 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 ウィジェットのレンダリング

ADKでサポートPython v1.27.0

エージェントのレスポンスとともにリッチな 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 の使用

ADKでサポートPython v0.1.0TypeScript v0.2.0Java v0.2.0Kotlin v0.1.0

ほとんどのやり取りは 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でより洗練され、ステートフルで、有能なエージェントを構築することができます。