サーバー API

ADK-Rust サーバーは、エージェントの実行、セッションの管理、アーティファクトへのアクセスを行うための REST API を提供します。Launcher をサーバーモードで使用してエージェントをデプロイすると、これらのエンドポイントと Web UI が公開されます。

概要

このサーバーは Axum を基盤として構築され、以下を提供します。

• REST API: エージェントの実行とセッション管理のための HTTP エンドポイント
• Server-Sent Events（SSE）: エージェントの応答をリアルタイムでストリーミング
• Web UI: ブラウザベースの対話型インターフェース
• CORS サポート: クロスオリジンリクエストを有効化
• テレメトリ: tracing による組み込みの可観測性

ServerConfig は、長時間実行されるデプロイメント向けに、runner レベルのパススルーも公開します。

let config = ServerConfig::new(agent_loader, session_service)
    .with_compaction(compaction_config)
    .with_context_cache(context_cache_config, cache_capable_model);

サーバーの起動

Launcher を使用してサーバーを起動します。

use adk_rust::prelude::*;
use adk_rust::Launcher;
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<()> {
    let api_key = std::env::var("GOOGLE_API_KEY")?;
    let model = Arc::new(GeminiModel::new(&api_key, "gemini-3.7-flash")?);
    
    let agent = LlmAgentBuilder::new("my_agent")
        .description("A helpful assistant")
        .instruction("You are a helpful assistant.")
        .model(model)
        .build()?;
    
    Launcher::new(Arc::new(agent)).run().await
}

検証済みの API scaffold から開始します。

cargo adk new my-api --template api
cd my-api
cargo run

REST API エンドポイント

ヘルスチェック

サーバーが実行中かどうかを確認します。

GET /api/health

レスポンス:

OK

ストリーミングによるエージェントの実行

Server-Sent Events を使用してエージェントを実行し、応答をストリーミングします。

POST /api/run_sse

リクエストボディ:

{
  "appName": "my_agent",
  "userId": "user123",
  "sessionId": "session456",
  "newMessage": {
    "role": "user",
    "parts": [
      {
        "text": "What is the capital of France?"
      }
    ]
  },
  "streaming": true
}

レスポンス:

• Content-Type: text/event-stream
• イベントを JSON オブジェクトとしてストリーミング

イベント形式:

{
  "id": "evt_123",
  "timestamp": 1234567890,
  "author": "my_agent",
  "content": {
    "role": "model",
    "parts": [
      {
        "text": "The capital of France is Paris."
      }
    ]
  },
  "actions": {},
  "llm_response": {
    "content": {
      "role": "model",
      "parts": [
        {
          "text": "The capital of France is Paris."
        }
      ]
    }
  }
}

エージェントの実行（ストリーミングなし）

エージェントを完了まで実行し、すべてのイベントを単一の JSON レスポンスで受け取ります。

POST /api/run

リクエストボディ: POST /api/run_sse と同じ形式（streaming フィールドは無視されます）。

{
  "appName": "my_agent",
  "userId": "user123",
  "sessionId": "session456",
  "newMessage": {
    "role": "user",
    "parts": [
      {
        "text": "What is the capital of France?"
      }
    ]
  }
}

レスポンス:

• Content-Type: application/json
• 実行によって生成されたすべてのイベントを順番に含む JSON 配列。イベント形式は /api/run_sse と同じです

このエンドポイントは、Google ADK の api_server ストリーミングなし /run ルートをミラーリングします。

セッション管理

セッションの作成

新しいセッションを作成：

POST /api/sessions

リクエスト本文：

{
  "appName": "my_agent",
  "userId": "user123",
  "sessionId": "session456"
}

レスポンス：

{
  "id": "session456",
  "appName": "my_agent",
  "userId": "user123",
  "lastUpdateTime": 1234567890,
  "events": [],
  "state": {}
}

セッションを取得

セッションの詳細を取得：

GET /api/sessions/:app_name/:user_id/:session_id

レスポンス：

{
  "id": "session456",
  "appName": "my_agent",
  "userId": "user123",
  "lastUpdateTime": 1234567890,
  "events": [],
  "state": {}
}

セッションを削除

セッションを削除：

DELETE /api/sessions/:app_name/:user_id/:session_id

レスポンス：

• ステータス：204 No Content

セッション一覧

ユーザーのすべてのセッションを一覧表示：

GET /api/apps/:app_name/users/:user_id/sessions

レスポンス：

[
  {
    "id": "session456",
    "appName": "my_agent",
    "userId": "user123",
    "lastUpdateTime": 1234567890,
    "events": [],
    "state": {}
  }
]

アーティファクト管理

アーティファクト一覧

セッションのすべてのアーティファクトを一覧表示：

GET /api/sessions/:app_name/:user_id/:session_id/artifacts

レスポンス：

[
  "image1.png",
  "document.pdf",
  "data.json"
]

アーティファクトを取得

アーティファクトをダウンロード：

GET /api/sessions/:app_name/:user_id/:session_id/artifacts/:artifact_name

レスポンス：

• Content-Type：ファイル拡張子によって決定
• 本文：バイナリまたはテキストコンテンツ

アプリケーション管理

アプリケーション一覧

利用可能なすべての agent を一覧表示：

GET /api/apps
GET /api/list-apps  (legacy compatibility)

レスポンス：

{
  "apps": [
    {
      "name": "my_agent",
      "description": "A helpful assistant"
    }
  ]
}

Web UI

サーバーには、次の場所からアクセスできる組み込み Web UI が含まれています：

http://localhost:8080/ui/

5 分間のクイックスタートでは、OpenAI を基盤とするサーバーを 雛形生成し、4 つのコマンドでこのインターフェースを開きます。録画ではチームを使用して、 アクティブなトポロジーエッジを見えるようにしています。リーフ agent、ツール、グラフ、 ワークフロー、リアルタイム agent、リモート agent は、同じインターフェースを使用します。

機能

• インタラクティブ実行: メッセージと添付ファイルを送信し、安全にレンダリングされた Markdown、ストリーミングテキスト、ツール呼び出し、失敗、ハンドオフを確認
• セッション管理: セッションを作成、表示、切り替え
• ポータブルなチームトポロジー: 正確な委譲と復帰のエッジを制御のハンドオフから区別し、アクティブなメンバーと受信エッジに対して Studio Next スタイルのアニメーションを表示
• ランタイムインスペクター: 順序付けられたイベント、専用のテレメトリースパン、共有状態／セッション状態、構成済みランタイムサービス、A2A の検出、UI／MCP Apps プロトコルのサポートを確認
• リアルタイム再生: リアルタイムエージェントを認識し、トランスクリプトの差分をマージして、完了した PCM 出力を WAV オーディオとして再生
• アーティファクトビューアー: セッションアーティファクトを表示およびダウンロード
• レスポンシブテーマ: 外部アセットを使用しない、キーボードでアクセス可能なシステム、ライト、ダークの各レイアウト

UI ルート

• / - /ui/ にリダイレクト
• /ui/ - メインチャットインターフェース
• /ui/assets/* - 静的アセット（CSS、JS、画像）
• /ui/assets/config/runtime-config.json - ランタイム構成
• /api/ui/agents/{name} - エージェントの機能、階層、ポータブルトポロジーメタデータ

インターフェースは adk-server/webui で管理され、その本番ビルドは サーバークレートに組み込まれているため、生成されたプロジェクトとデプロイメントでは、 別個のフロントエンドサービスなしで同じランタイム UI が使用されます。

実行可能なランタイムUIショーケースには、ツール呼び出しエージェント、決定論的なグラフワークフロー、ポータブルなハンドオフチーム向けに、OpenAIを基盤とする個別のウォークスルーとスクリーンショットが含まれています。高度なエージェントギャラリーには、アンビエントスケジュール、OpenAI Realtime音声再生、A2Aディスカバリー、SEP-2663タスクを使用したMCP 2026-07-28ディスカバリー、さらにテレメトリ、アーティファクト、メモリサービスを1つのサーバーに構成した例が追加されています。ADK Runtimeブランドのリンクは、新しいタブでadk-rust.comを開きます。

クライアントの例

JavaScript/TypeScript

Fetch APIとSSEを使用する場合:

async function runAgent(message) {
  const response = await fetch('http://localhost:8080/api/run_sse', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      appName: 'my_agent',
      userId: 'user123',
      sessionId: 'session456',
      newMessage: {
        role: 'user',
        parts: [{ text: message }]
      },
      streaming: true
    })
  });

  const reader = response.body.getReader();
  const decoder = new TextDecoder();

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    
    const chunk = decoder.decode(value);
    const lines = chunk.split('\n');
    
    for (const line of lines) {
      if (line.startsWith('data: ')) {
        const event = JSON.parse(line.slice(6));
        console.log('Event:', event);
      }
    }
  }
}

Python

requestsライブラリを使用する場合:

import requests
import json

def run_agent(message):
    url = 'http://localhost:8080/api/run_sse'
    payload = {
        'appName': 'my_agent',
        'userId': 'user123',
        'sessionId': 'session456',
        'newMessage': {
            'role': 'user',
            'parts': [{'text': message}]
        },
        'streaming': True
    }
    
    response = requests.post(url, json=payload, stream=True)
    
    for line in response.iter_lines():
        if line:
            line_str = line.decode('utf-8')
            if line_str.startswith('data: '):
                event = json.loads(line_str[6:])
                print('Event:', event)

run_agent('What is the capital of France?')

cURL

# Create session
curl -X POST http://localhost:8080/api/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "appName": "my_agent",
    "userId": "user123",
    "sessionId": "session456"
  }'

# Run agent with streaming
curl -X POST http://localhost:8080/api/run_sse \
  -H "Content-Type: application/json" \
  -d '{
    "appName": "my_agent",
    "userId": "user123",
    "sessionId": "session456",
    "newMessage": {
      "role": "user",
      "parts": [{"text": "What is the capital of France?"}]
    },
    "streaming": true
  }'

サーバー構成

カスタムポート

カスタムポートを使用するには、生成されたサーバーを起動する前にPORTを設定します。

PORT=3000 cargo run

カスタムアーティファクトサービス

独自のアーティファクトサービスを指定します。

use adk_artifact::InMemoryArtifactService;

let artifact_service = Arc::new(InMemoryArtifactService::new());

Launcher::new(Arc::new(agent))
    .with_artifact_service(artifact_service)
    .run()
    .await

カスタムセッションサービス

本番環境へのデプロイでは、永続的なセッションサービスを使用します。

use adk_session::SqliteSessionService;

// Note: This requires implementing a custom server setup
// The Launcher uses InMemorySessionService by default

エラー処理

APIは、エラーカテゴリから導出されたHTTPステータスコードを使用する構造化エラーレスポンスを返します。

エラーレスポンス形式（問題 JSON）：

{
  "error": {
    "code": "model.openai.rate_limited",
    "message": "OpenAI rate limit exceeded",
    "component": "model",
    "category": "rate_limited",
    "requestId": "req-abc123",
    "retryAfter": 5000,
    "upstreamStatusCode": 429
  }
}

フィールド requestId、retryAfter、および upstreamStatusCode は、利用可能な場合に含まれます（それ以外の場合は null）。

CORS 設定

サーバーはデフォルトで許容的な CORS を有効にし、任意のオリジンからのリクエストを許可します。これは開発には適していますが、本番環境では制限する必要があります。

テレメトリ

サーバーは起動時にテレメトリを自動的に初期化します。ログは構造化形式で標準出力に出力されます。

ログレベル：

• ERROR：重大なエラー
• WARN：警告
• INFO：一般情報（デフォルト）
• DEBUG：詳細なデバッグ情報
• TRACE：非常に詳細なトレース情報

RUST_LOG 環境変数でログレベルを設定します：

RUST_LOG=debug cargo run

ベストプラクティス

1. セッション管理：エージェントを実行する前に、必ずセッションを作成する
2. エラーハンドリング：HTTP ステータスコードを確認し、適切にエラーを処理する
3. ストリーミング：リアルタイムレスポンスには SSE を使用し、イベントを1行ずつ解析する
4. セキュリティ：本番環境では、認証を実装し、CORS を制限する
5. 永続化：本番デプロイメントには SqliteSessionService または PostgresSessionService を使用する
6. モニタリング：テレメトリを有効にし、問題がないかログを監視する

フルスタックの例

完全に動作するサーバーのスキャフォールドには、検証済みの cargo-adk API テンプレートを使用します。以下を実証します：

• フロントエンド：リアルタイムストリーミングに対応した HTML/JavaScript クライアント
• バックエンド：カスタムリサーチおよび PDF 生成ツールを備えた ADK エージェント
• 統合：SSE ストリーミングを使用した完全な REST API
• アーティファクト：PDF の生成とダウンロード
• セッション管理：セッションの自動作成と処理

この例では、ADK-Rustを使用してAI搭載ウェブアプリケーションを構築する、本番環境対応のパターンを示します。

クイックスタート:

cargo adk new my-api --template api
cd my-api
cargo run

ファイル:

• バックエンド: adk-rust-guide/examples/deployment/full_stack_research.rs
• フロントエンド: examples/research_paper/frontend.html
• ドキュメント: examples/research_paper/README.md
• アーキテクチャ: examples/research_paper/architecture.md

関連項目

• ランチャー - サーバーの起動
• セッション - セッション管理
• アーティファクト - アーティファクトの保存
• 可観測性 - テレメトリとロギング

---

前へ: ← ランチャー | 次へ: A2A プロトコル →