ランタイム¶

ランタイムとは？¶

ADKランタイムは、ユーザーとの対話中にエージェントアプリケーションを動かす基盤となるエンジンです。あなたが定義したエージェント、ツール、コールバックを受け取り、ユーザーの入力に応じてそれらの実行を調整し、情報の流れ、状態の変更、LLMやストレージのような外部サービスとの対話を管理するシステムです。

ランタイムは、あなたのエージェントアプリケーションの「エンジン」だと考えてください。あなたが部品（エージェント、ツール）を定義し、ランタイムがユーザーのリクエストを満たすためにそれらがどのように接続され、一緒に実行されるかを処理します。

中核的なアイデア：イベントループ¶

ADKランタイムの中心は、イベントループで動作します。このループは、Runnerコンポーネントと、あなたが定義した「実行ロジック」（エージェント、それらが呼び出すLLM、コールバック、ツールを含む）との間の双方向の通信を促進します。

簡単に言うと：

Runnerはユーザーのクエリを受け取り、メインのAgentに処理を開始するよう依頼します。
Agent（および関連ロジック）は、報告すべき何か（応答、ツールの使用リクエスト、状態変更など）があるまで実行され、その後Eventをyield（生成）またはemit（送出）します。
RunnerはこのEventを受け取り、関連するアクション（Servicesを介した状態変更の保存など）を処理し、イベントを前方（例：ユーザーインターフェース）に転送します。
Runnerがイベントを処理した後にのみ、Agentのロジックは一時停止したところから再開し、今度はRunnerによってコミットされた変更の影響を見ることができます。
このサイクルは、エージェントが現在のユーザーのクエリに対して生成すべきイベントがなくなるまで繰り返されます。

このイベント駆動のループが、ADKがあなたのエージェントコードを実行する基本的なパターンです。

心臓部：イベントループの内部動作¶

イベントループは、Runnerとあなたのカスタムコード（エージェント、ツール、コールバック、これらをまとめて「実行ロジック」または設計ドキュメントでは「ロジックコンポーネント」と呼びます）との間の相互作用を定義する中心的な運用パターンです。これにより、責任の分担が明確になります：

Note

具体的なメソッド名やパラメータ名は、SDKの言語によって若干異なる場合があります（例：Javaではagent_to_run.runAsync(...)、Pythonではagent_to_run.run_async(...)）。詳細は各言語のAPIドキュメントを参照してください。

Runnerの役割（オーケストレーター）¶

Runnerは、単一のユーザー呼び出しに対する中心的な調整役として機能します。ループ内でのその責任は次のとおりです：

開始： エンドユーザーのクエリ（new_message）を受け取り、通常はSessionServiceを介してセッション履歴に追加します。
キックオフ： メインエージェントの実行メソッド（例：agent_to_run.run_async(...)）を呼び出して、イベント生成プロセスを開始します。
受信と処理： エージェントロジックがEventをyieldまたはemitするのを待ちます。イベントを受信すると、Runnerはそれを速やかに処理します。これには以下が含まれます：
- 設定されたServices（SessionService、ArtifactService、MemoryService）を使用して、event.actionsで示された変更（state_delta、artifact_deltaなど）をコミットします。
- その他の内部的な管理業務を実行します。
上流へのyield： 処理されたイベントを前方（例：呼び出し元のアプリケーションやUIのレンダリングのため）に転送します。
反復： エージェントロジックに対し、yieldされたイベントの処理が完了したことを通知し、ロジックが再開して次のイベントを生成できるようにします。

概念的なRunnerのループ：

PythonJava

# Runnerのメインループのロジックの簡略化されたビュー
def run(new_query, ...) -> Generator[Event, None, None]:
    # 1. new_queryをセッションのイベント履歴に追加（SessionService経由）
    session_service.append_event(session, Event(author='user', content=new_query))

    # 2. エージェントを呼び出してイベントループを開始
    agent_event_generator = agent_to_run.run_async(context)

    async for event in agent_event_generator:
        # 3. 生成されたイベントを処理し、変更をコミット
        session_service.append_event(session, event) # state/artifactの差分などをコミット
        # memory_service.update_memory(...) # 該当する場合
        # artifact_serviceはエージェント実行中にcontext経由で既に呼び出されている可能性がある

        # 4. 上流の処理（例：UIレンダリング）のためにイベントをyieldする
        yield event
        # Runnerはyield後にエージェントジェネレータが続行できることを暗黙的に示す

// JavaにおけるRunnerのメインループのロジックの簡略化された概念的ビュー
public Flowable<Event> runConceptual(
    Session session,                  
    InvocationContext invocationContext, 
    Content newQuery                
    ) {

    // 1. new_queryをセッションのイベント履歴に追加（SessionService経由）
    // ...
    sessionService.appendEvent(session, userEvent).blockingGet();

    // 2. エージェントを呼び出してイベントストリームを開始
    Flowable<Event> agentEventStream = agentToRun.runAsync(invocationContext);

    // 3. 生成された各イベントを処理し、変更をコミットし、「yield」または「emit」する
    return agentEventStream.map(event -> {
        // これはセッションオブジェクトを変更する（イベントを追加し、stateDeltaを適用する）。
        // appendEventの戻り値（Single<Event>）は、概念的には処理後のイベントそのものである。
        sessionService.appendEvent(session, event).blockingGet(); // 簡略化されたブロッキング呼び出し

        // memory_service.update_memory(...) # 該当する場合 - 概念的
        // artifact_serviceはエージェント実行中にcontext経由で既に呼び出されている可能性がある

        // 4. 上流の処理のためにイベントを「yield」する
        //    RxJavaでは、mapでイベントを返すことは、事実上、次のオペレータやサブスクライバにそれをyieldすることになる。
        return event;
    });
}

実行ロジックの役割（エージェント、ツール、コールバック）¶

エージェント、ツール、コールバック内のあなたのコードは、実際の計算と意思決定を担当します。ループとの相互作用には以下が含まれます：

実行： 現在のInvocationContextに基づいてロジックを実行します。これには、実行が再開された時点でのセッション状態が含まれます。
Yield： ロジックが通信する必要がある場合（メッセージの送信、ツールの呼び出し、状態変更の報告）、関連するコンテンツとアクションを含むEventを構築し、このイベントをRunnerにyieldします。
一時停止： 重要なことに、エージェントロジックの実行はyield文（またはRxJavaではreturn）の直後で一時停止します。Runnerがステップ3（処理とコミット）を完了するのを待ちます。
再開： Runnerがyieldされたイベントを処理した後にのみ、エージェントロジックはyieldの直後の文から実行を再開します。
更新された状態の確認： 再開すると、エージェントロジックは、以前にyieldされたイベントからRunnerによってコミットされた変更を反映したセッション状態（ctx.session.state）に確実にアクセスできます。

概念的な実行ロジック：

PythonJava

# Agent.run_async、コールバック、またはツール内のロジックの簡略化されたビュー

# ... 以前のコードが現在の状態に基づいて実行される ...

# 1. 変更や出力が必要であると判断し、イベントを構築する
# 例：状態の更新
update_data = {'field_1': 'value_2'}
event_with_state_change = Event(
    author=self.name,
    actions=EventActions(state_delta=update_data),
    content=types.Content(parts=[types.Part(text="状態が更新されました。")])
    # ... 他のイベントフィールド ...
)

# 2. 処理とコミットのためにイベントをRunnerにyieldする
yield event_with_state_change
# <<<<<<<<<<<< ここで実行が一時停止 >>>>>>>>>>>>

# <<<<<<<<<<<< RUNNERがイベントを処理・コミット >>>>>>>>>>>>

# 3. Runnerが上記のイベントの処理を終えた後にのみ実行を再開する。
# これで、Runnerによってコミットされた状態が確実に反映される。
# 後続のコードは、yieldされたイベントからの変更が発生したと安全に仮定できる。
val = ctx.session.state['field_1']
# ここで `val` は "value_2" であることが保証される（Runnerが正常にコミットしたと仮定）
print(f"実行再開。field_1の値は現在：{val}")

# ... 後続のコードが続く ...
# 後で別のイベントをyieldするかもしれない...

// Agent.runAsync、コールバック、またはツール内のロジックの簡略化されたビュー
// ... 以前のコードが現在の状態に基づいて実行される ...

// 1. 変更や出力が必要であると判断し、イベントを構築する
// 例：状態の更新
ConcurrentMap<String, Object> updateData = new ConcurrentHashMap<>();
updateData.put("field_1", "value_2");

EventActions actions = EventActions.builder().stateDelta(updateData).build();
Content eventContent = Content.builder().parts(Part.fromText("状態が更新されました。")).build();

Event eventWithStateChange = Event.builder()
    .author(self.name())
    .actions(actions)
    .content(Optional.of(eventContent))
    // ... 他のイベントフィールド ...
    .build();

// 2. イベントを「yield」する。RxJavaでは、これはストリームにそれを送出することを意味する。
//    Runner（または上流のコンシューマ）がこのFlowableを購読する。
//    Runnerがこのイベントを受け取ると、それを処理する（例：sessionService.appendEventを呼び出す）。
//    Java ADKの 'appendEvent' は 'ctx'（InvocationContext）内の 'Session' オブジェクトを変更する。

// <<<<<<<<<<<< 概念的な一時停止ポイント >>>>>>>>>>>>
// RxJavaでは、'eventWithStateChange'の送出が発生し、その後ストリームは
// Runnerがこのイベントを処理した*後*のロジックを表す 'flatMap' や 'concatMap' オペレータで
// 続くかもしれない。

// 「Runnerが処理を終えた後にのみ実行を再開する」をモデル化するには：
// Runnerの`appendEvent`は通常、それ自体が非同期操作である（Single<Event>を返す）。
// エージェントのフローは、コミットされた状態に依存する後続のロジックが、
// その`appendEvent`が完了した*後*に実行されるように構成する必要がある。

// これはRunnerが通常それを調整する方法である：
// Runner:
//   agent.runAsync(ctx)
//     .concatMapEager(eventFromAgent ->
//         sessionService.appendEvent(ctx.session(), eventFromAgent) // これがctx.session().state()を更新する
//             .toFlowable() // 処理後にイベントを送出する
//     )
//     .subscribe(processedEvent -> { /* UIがprocessedEventをレンダリング */ });

// したがって、エージェント自身のロジック内で、それがyieldしたイベントが処理され、
// その状態変更がctx.session().state()に反映された*後*に何かをする必要がある場合、
// その後続のロジックは通常、そのリアクティブチェーンの別のステップにある。

// この概念的な例では、イベントを送出し、その後「再開」をFlowableチェーンの後続の操作としてシミュレートする。

return Flowable.just(eventWithStateChange) // ステップ2：イベントをyieldする
    .concatMap(yieldedEvent -> {
        // <<<<<<<<<<<< RUNNERが概念的にイベントを処理・コミット >>>>>>>>>>>>
        // この時点で、実際のrunnerでは、ctx.session().appendEvent(yieldedEvent)が
        // Runnerによって呼び出され、ctx.session().state()が更新されているだろう。
        // 我々はこれをモデル化しようとするエージェントの概念的なロジックの*内部*にいるので、
        // Runnerのアクションが暗黙的に我々の'ctx.session()'を更新したと仮定する。

        // 3. 実行を再開する。
        // これで、Runnerによってコミットされた状態（sessionService.appendEvent経由で）が
        // ctx.session().state()に確実に反映される。
        Object val = ctx.session().state().get("field_1");
        // ここで `val` は "value_2" であることが保証される。なぜなら、Runnerによって呼び出された
        // `sessionService.appendEvent`が`ctx`オブジェクト内のセッション状態を更新したからである。

        System.out.println("実行再開。field_1の値は現在：" + val);

        // ... 後続のコードが続く ...
        // この後続のコードが別のイベントをyieldする必要がある場合、ここでそれを行う。

Runnerとあなたの実行ロジックとの間のこの協力的なyield/pause/resumeサイクルは、Eventオブジェクトを介して行われ、ADKランタイムの中核を形成します。