サーバーAPI

ADK-Rustサーバーは、agentの実行、sessionの管理、および成果物へのアクセスを可能にするREST APIを提供します。server modeでLauncherを使用してagentをデプロイすると、これらのエンドポイントがWeb UIとともに公開されます。

概要

サーバーはAxum上に構築されており、以下を提供します。

REST API: agentの実行とsession管理のためのHTTPエンドポイント
Server-Sent Events (SSE): agentの応答のリアルタイムストリーミング
Web UI: インタラクティブなブラウザベースのインターフェース
CORS Support: クロスオリジンリクエストが有効
Telemetry: tracingによる組み込みの可観測性

サーバーの起動

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-2.5-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
}

サーバーを起動します。

cargo run -- serve --port 8080

REST API エンドポイント

ヘルスチェック

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

GET /api/health

レスポンス:

OK

ストリーミングによるAgentの実行

Agentを実行し、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."
        }
      ]
    }
  }
}

Session管理

セッションの作成

新しいSessionを作成します。

POST /api/sessions

リクエストボディ:

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

レスポンス:

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

セッションの取得

Sessionの詳細を取得します。

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

レスポンス:

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

セッションの削除

Sessionを削除します。

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

レスポンス:

ステータス: 204 No Content

セッションの一覧表示

ユーザーのすべてのSessionを一覧表示します。

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

レスポンス:

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

アーティファクト管理

アーティファクトの一覧表示

Sessionのすべてのアーティファクトを一覧表示します。

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/

機能

インタラクティブチャット: メッセージを送信し、ストリーミングレスポンスを受信します
セッション管理: Sessionを作成、表示、切り替えます
マルチエージェントサポート: Agentの転送と階層を視覚化します
アーティファクトビューア: Sessionのアーティファクトを表示およびダウンロードします
リアルタイム更新: 即時レスポンスのための SSE ベースのストリーミング

UI ルート

/ - /ui/ にリダイレクトします
/ui/ - メインチャットインターフェース
/ui/assets/* - 静的アセット (CSS, JS, 画像)
/ui/assets/config/runtime-config.json - ランタイム設定

クライアントの例

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
  }'

サーバー設定

カスタムポート

カスタムポートを指定します：

cargo run -- serve --port 3000

カスタムArtifact Service

独自のartifact serviceを提供します：

use adk_artifact::InMemoryArtifactService;

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

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

カスタムSession Service

本番環境のデプロイでは、永続的なsession serviceを使用します：

use adk_session::DatabaseSessionService;

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

エラー処理

API は標準的なHTTPステータスコードを使用します：

ステータスコード	意味
200	成功
204	成功 (コンテンツなし)
400	不正なリクエスト
404	見つかりません
500	サーバー内部エラー

エラーレスポンス形式：

{
  "error": "Error message description"
}

CORS設定

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

Telemetry

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

ログレベル：

ERROR: 致命的なエラー
WARN: 警告
INFO: 一般的な情報 (デフォルト)
DEBUG: 詳細なデバッグ情報
TRACE: 非常に詳細なトレース

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

RUST_LOG=debug cargo run -- serve

ベストプラクティス

Session Management: Agentを実行する前に、常にSessionを作成してください
Error Handling: HTTPステータスコードを確認し、適切にエラーを処理してください
Streaming: リアルタイム応答にはSSEを使用し、イベントを1行ずつパースしてください
Security: 本番環境では、認証を実装し、CORSを制限してください
Persistence: 本番デプロイにはDatabaseSessionServiceを使用してください
Monitoring: telemetryを有効にし、問題がないかログを監視してください

フルスタックの例

ADKバックエンドと連携するフロントエンドアプリケーションの完全な動作例については、「Research Paper Generator」の例を参照してください。これは以下を示しています:

Frontend: リアルタイムストリーミングを備えたHTML/JavaScriptクライアント
Backend: カスタムリサーチおよびPDF生成FunctionToolを備えたADK agent
Integration: SSEストリーミングを伴う完全なREST APIの使用法
Artifacts: PDFの生成とダウンロード
Session Management: Sessionの自動作成と処理

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

クイックスタート:

# Start the server
cargo run --example full_stack_research -p adk-rust-guide -- serve --port 8080

# Open the frontend
open examples/research_paper/frontend.html

ファイル:

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

サーバーAPI

概要

サーバーの起動

REST API エンドポイント

ヘルスチェック

ストリーミングによるAgentの実行

Session管理

セッションの作成

セッションの取得

セッションの削除

セッションの一覧表示

アーティファクト管理

アーティファクトの一覧表示

アーティファクトの取得

アプリケーション管理

アプリケーションの一覧表示

Web UI

機能

UI ルート

クライアントの例

JavaScript/TypeScript

Python

cURL

サーバー設定

カスタムポート

カスタムArtifact Service

カスタムSession Service

エラー処理

CORS設定

Telemetry

ベストプラクティス

フルスタックの例

関連