AG-UI を使用したフロントエンドツールのレンダリング

このチュートリアルでは、フロントエンド関数ツールを AG-UI クライアントに追加する方法について説明します。フロントエンドツールは、クライアント側で実行される関数であり、AI エージェントがユーザーのローカル環境と対話したり、クライアント固有のデータにアクセスしたり、UI 操作を実行したりできます。サーバーはこれらのツールを呼び出すタイミングを調整しますが、実行は完全にクライアントで行われます。

[前提条件]

開始する前に、作業の開始に関するチュートリアルを完了し、次のことを行っていることを確認します。

.NET 8.0 以降
Microsoft.Agents.AI.AGUI パッケージがインストールされている
Microsoft.Agents.AI パッケージがインストールされている
AG-UI クライアントセットアップの基本的な理解

フロントエンドツールとは

フロントエンドツールは、次の機能ツールです。

クライアントで定義および登録されている
(サーバーではなく) クライアントの環境で実行する
AI エージェントがクライアント固有のリソースと対話できるようにする
応答にエージェントを組み込むための結果をサーバーに返す
パーソナライズされたコンテキスト対応エクスペリエンスを有効にする

一般的なユースケース:

ローカルセンサーデータ (GPS、温度など) の読み取り
クライアント側のストレージまたはユーザー設定へのアクセス
UI 操作の実行 (テーマの変更、通知の表示)
デバイス固有の機能 (カメラ、マイク) との対話

クライアントでのフロントエンドツールの登録

作業の開始チュートリアルとの主な違いは、ツールをクライアントエージェントに登録することです。変更点を次に示します。

// Define a frontend function tool
[Description("Get the user's current location from GPS.")]
static string GetUserLocation()
{
    // Access client-side GPS
    return "Amsterdam, Netherlands (52.37°N, 4.90°E)";
}

// Create frontend tools
AITool[] frontendTools = [AIFunctionFactory.Create(GetUserLocation)];

// Pass tools when creating the agent
AIAgent agent = chatClient.AsAIAgent(
    name: "agui-client",
    description: "AG-UI Client Agent",
    tools: frontendTools);

クライアントコードの残りの部分は、作業の開始に関するチュートリアルに示されているように変わりません。

ツールをサーバーに送信する方法

ツールを AsAIAgent()に登録すると、AGUIChatClient が自動で実行されます。

ツール定義 (名前、説明、パラメータースキーマ) をキャプチャします。
各リクエストと共にツールをサーバーエージェントに送信し、それらをマップします。 ChatAgentRunOptions.ChatOptions.Tools

サーバーはクライアントツールの宣言を受け取り、AI モデルはそれらを呼び出すタイミングを決定できます。

ミドルウェアを使用したツールの検査と変更

エージェントミドルウェアを使用して、ツールへのアクセスを含め、エージェントの実行を検査または変更できます。

// Create agent with middleware that inspects tools
AIAgent inspectableAgent = baseAgent
    .AsBuilder()
    .Use(runFunc: null, runStreamingFunc: InspectToolsMiddleware)
    .Build();

static async IAsyncEnumerable<AgentResponseUpdate> InspectToolsMiddleware(
    IEnumerable<ChatMessage> messages,
    AgentSession? session,
    AgentRunOptions? options,
    AIAgent innerAgent,
    CancellationToken cancellationToken)
{
    // Access the tools from ChatClientAgentRunOptions
    if (options is ChatClientAgentRunOptions chatOptions)
    {
        IList<AITool>? tools = chatOptions.ChatOptions?.Tools;
        if (tools != null)
        {
            Console.WriteLine($"Tools available for this run: {tools.Count}");
            foreach (AITool tool in tools)
            {
                if (tool is AIFunction function)
                {
                    Console.WriteLine($"  - {function.Metadata.Name}: {function.Metadata.Description}");
                }
            }
        }
    }

    await foreach (AgentResponseUpdate update in innerAgent.RunStreamingAsync(messages, session, options, cancellationToken))
    {
        yield return update;
    }
}

このミドルウェアパターンを使用すると、次のことができます。

実行前にツール定義を検証する

主要概念

フロントエンドツールの新しい概念を次に示します。

クライアント側の登録: ツールは、を使用してクライアントに登録され、AIFunctionFactory.Create() に渡されます。
自動キャプチャ: ツールは自動的にキャプチャされ、次の方法で送信されます。 ChatAgentRunOptions.ChatOptions.Tools

フロントエンドツールのしくみ

サーバーサイドフロー

サーバーは、フロントエンドツールの実装の詳細を認識しません。それだけを知っています。

ツール名と説明 (クライアント登録から)
パラメータースキーマ
ツールの実行を要求するタイミング

AI エージェントがフロントエンドツールを呼び出す場合:

サーバーが SSE 経由でツール呼び出し要求をクライアントに送信する
サーバーは、クライアントがツールを実行して結果を返すのを待機します
サーバーがエージェントのコンテキストに結果を組み込む
エージェントがツールの結果を使用して処理を続行する

クライアントサイドフロー

クライアントはフロントエンドツールの実行を処理します。

ツール呼び出し要求を示す FunctionCallContent をサーバーから受信します
ツール名をローカルに登録された関数と一致させる
要求からパラメーターを逆シリアル化します
関数をローカルで実行する
結果をシリアル化します。
FunctionResultContentをサーバーに送り返す
エージェントの応答の受信を続行する

フロントエンドツールを使用した予想される出力

エージェントがフロントエンドツールを呼び出すと、ツール呼び出しが表示され、ストリーミング出力が生成されます。

User (:q or quit to exit): Where am I located?

[Client Tool Call - Name: GetUserLocation]
[Client Tool Result: Amsterdam, Netherlands (52.37°N, 4.90°E)]

You are currently in Amsterdam, Netherlands, at coordinates 52.37°N, 4.90°E.

フロントエンドツールのサーバーセットアップ

サーバーは、フロントエンドツールをサポートするために特別な構成を必要としません。使い始めのチュートリアルにある標準の AG-UI サーバーを使用します。これにより、操作が自動的に進行します。

クライアント接続中にフロントエンドツールの宣言を受け取ります
AI エージェントが必要なときにツールの実行を要求する
クライアントからの結果を待機します
エージェントの意思決定に結果を組み込む

次のステップ

フロントエンドツールを理解したら、次のことができます。

バックエンドツールとの組み合わせ: フロントエンドツールとバックエンドツールの両方を一緒に使用する

その他のリソース

このチュートリアルでは、フロントエンド関数ツールを AG-UI クライアントに追加する方法について説明します。フロントエンドツールは、クライアント側で実行される関数であり、AI エージェントがユーザーのローカル環境と対話したり、クライアント固有のデータにアクセスしたり、UI 操作を実行したりできます。

[前提条件]

開始する前に、作業の開始に関するチュートリアルを完了し、次のことを行っていることを確認します。

Python 3.10 以降
httpx HTTP クライアント機能用にインストール済み
AG-UI クライアントセットアップの基本的な理解
構成された Azure OpenAI サービス

フロントエンドツールとは

フロントエンドツールは、次の機能ツールです。

クライアントで定義および登録されている
(サーバーではなく) クライアントの環境で実行する
AI エージェントがクライアント固有のリソースと対話できるようにする
応答にエージェントを組み込むための結果をサーバーに返す

一般的なユースケース:

ローカルセンサーデータの読み取り
クライアント側のストレージまたはユーザー設定へのアクセス
UI 操作の実行
デバイス固有の機能とのインタラクション

フロントエンドツールの作成

Python のフロントエンドツールはバックエンドツールと同様に定義されますが、クライアントに登録されます。

from typing import Annotated
from pydantic import BaseModel, Field


class SensorReading(BaseModel):
    """Sensor reading from client device."""
    temperature: float
    humidity: float
    air_quality_index: int


def read_climate_sensors(
    include_temperature: Annotated[bool, Field(description="Include temperature reading")] = True,
    include_humidity: Annotated[bool, Field(description="Include humidity reading")] = True,
) -> SensorReading:
    """Read climate sensor data from the client device."""
    # Simulate reading from local sensors
    return SensorReading(
        temperature=22.5 if include_temperature else 0.0,
        humidity=45.0 if include_humidity else 0.0,
        air_quality_index=75,
    )


def change_background_color(color: Annotated[str, Field(description="Color name")] = "blue") -> str:
    """Change the console background color."""
    # Simulate UI change
    print(f"\n🎨 Background color changed to {color}")
    return f"Background changed to {color}"

フロントエンドツールを使用した AG-UI クライアントの作成

フロントエンドツールを使用した完全なクライアント実装を次に示します。

"""AG-UI client with frontend tools."""

import asyncio
import json
import os
from typing import Annotated, AsyncIterator

import httpx
from pydantic import BaseModel, Field


class SensorReading(BaseModel):
    """Sensor reading from client device."""
    temperature: float
    humidity: float
    air_quality_index: int


# Define frontend tools
def read_climate_sensors(
    include_temperature: Annotated[bool, Field(description="Include temperature")] = True,
    include_humidity: Annotated[bool, Field(description="Include humidity")] = True,
) -> SensorReading:
    """Read climate sensor data from the client device."""
    return SensorReading(
        temperature=22.5 if include_temperature else 0.0,
        humidity=45.0 if include_humidity else 0.0,
        air_quality_index=75,
    )


def get_user_location() -> dict:
    """Get the user's current GPS location."""
    # Simulate GPS reading
    return {
        "latitude": 52.3676,
        "longitude": 4.9041,
        "accuracy": 10.0,
        "city": "Amsterdam",
    }


# Tool registry maps tool names to functions
FRONTEND_TOOLS = {
    "read_climate_sensors": read_climate_sensors,
    "get_user_location": get_user_location,
}


class AGUIClientWithTools:
    """AG-UI client with frontend tool support."""

    def __init__(self, server_url: str, tools: dict):
        self.server_url = server_url
        self.tools = tools
        self.thread_id: str | None = None

    async def send_message(self, message: str) -> AsyncIterator[dict]:
        """Send a message and handle streaming response with tool execution."""
        # Prepare tool declarations for the server
        tool_declarations = []
        for name, func in self.tools.items():
            tool_declarations.append({
                "name": name,
                "description": func.__doc__ or "",
                # Add parameter schema from function signature
            })

        request_data = {
            "messages": [
                {"role": "system", "content": "You are a helpful assistant with access to client tools."},
                {"role": "user", "content": message},
            ],
            "tools": tool_declarations,  # Send tool declarations to server
        }

        if self.thread_id:
            request_data["thread_id"] = self.thread_id

        async with httpx.AsyncClient(timeout=60.0) as client:
            async with client.stream(
                "POST",
                self.server_url,
                json=request_data,
                headers={"Accept": "text/event-stream"},
            ) as response:
                response.raise_for_status()

                async for line in response.aiter_lines():
                    if line.startswith("data: "):
                        data = line[6:]
                        try:
                            event = json.loads(data)

                            # Handle tool call requests from server
                            if event.get("type") == "TOOL_CALL_REQUEST":
                                await self._handle_tool_call(event, client)
                            else:
                                yield event

                            # Capture thread_id
                            if event.get("type") == "RUN_STARTED" and not self.thread_id:
                                self.thread_id = event.get("threadId")

                        except json.JSONDecodeError:
                            continue

    async def _handle_tool_call(self, event: dict, client: httpx.AsyncClient):
        """Execute frontend tool and send result back to server."""
        tool_name = event.get("toolName")
        tool_call_id = event.get("toolCallId")
        arguments = event.get("arguments", {})

        print(f"\n\033[95m[Client Tool Call: {tool_name}]\033[0m")
        print(f"  Arguments: {arguments}")

        try:
            # Execute the tool
            tool_func = self.tools.get(tool_name)
            if not tool_func:
                raise ValueError(f"Unknown tool: {tool_name}")

            result = tool_func(**arguments)

            # Convert Pydantic models to dict
            if hasattr(result, "model_dump"):
                result = result.model_dump()

            print(f"\033[94m[Client Tool Result: {result}]\033[0m")

            # Send result back to server
            await client.post(
                f"{self.server_url}/tool_result",
                json={
                    "tool_call_id": tool_call_id,
                    "result": result,
                },
            )

        except Exception as e:
            print(f"\033[91m[Tool Error: {e}]\033[0m")
            # Send error back to server
            await client.post(
                f"{self.server_url}/tool_result",
                json={
                    "tool_call_id": tool_call_id,
                    "error": str(e),
                },
            )


async def main():
    """Main client loop with frontend tools."""
    server_url = os.environ.get("AGUI_SERVER_URL", "http://127.0.0.1:8888/")
    print(f"Connecting to AG-UI server at: {server_url}\n")

    client = AGUIClientWithTools(server_url, FRONTEND_TOOLS)

    try:
        while True:
            message = input("\nUser (:q or quit to exit): ")
            if not message.strip():
                continue

            if message.lower() in (":q", "quit"):
                break

            print()
            async for event in client.send_message(message):
                event_type = event.get("type", "")

                if event_type == "RUN_STARTED":
                    print(f"\033[93m[Run Started]\033[0m")

                elif event_type == "TEXT_MESSAGE_CONTENT":
                    print(f"\033[96m{event.get('delta', '')}\033[0m", end="", flush=True)

                elif event_type == "RUN_FINISHED":
                    print(f"\n\033[92m[Run Finished]\033[0m")

                elif event_type == "RUN_ERROR":
                    error_msg = event.get("message", "Unknown error")
                    print(f"\n\033[91m[Error: {error_msg}]\033[0m")

            print()

    except KeyboardInterrupt:
        print("\n\nExiting...")
    except Exception as e:
        print(f"\n\033[91mError: {e}\033[0m")


if __name__ == "__main__":
    asyncio.run(main())

フロントエンドツールのしくみ

プロトコルフロー

クライアント登録: クライアントがツール宣言 (名前、説明、パラメーター) をサーバーに送信する
サーバーオーケストレーション: AI エージェントは、ユーザー要求に基づいてフロントエンドツールを呼び出すタイミングを決定します
ツール呼び出し要求: サーバーが SSE 経由 TOOL_CALL_REQUEST イベントをクライアントに送信する
クライアントの実行: クライアントがツールをローカルで実行する
結果の送信: クライアントは POST 要求を介してサーバーに結果を送信します
エージェント処理: サーバーに結果が組み込まれており、応答を続行する

キーイベント

TOOL_CALL_REQUEST: サーバーがフロントエンドツールの実行を要求する
TOOL_CALL_RESULT: クライアントが実行結果を送信する (HTTP POST 経由)

予期される出力

User (:q or quit to exit): What's the temperature reading from my sensors?

[Run Started]

[Client Tool Call: read_climate_sensors]
  Arguments: {'include_temperature': True, 'include_humidity': True}
[Client Tool Result: {'temperature': 22.5, 'humidity': 45.0, 'air_quality_index': 75}]

Based on your sensor readings, the current temperature is 22.5°C and the 
humidity is at 45%. These are comfortable conditions!
[Run Finished]

サーバーのセットアップ

概要チュートリアルの標準 AG-UI サーバーでは、フロントエンドツールが自動的にサポートされます。サーバー側で変更は必要ありません。ツールオーケストレーションは自動的に処理されます。

ベストプラクティス

セキュリティ

def access_sensitive_data() -> str:
    """Access user's sensitive data."""
    # Always check permissions first
    if not has_permission():
        return "Error: Permission denied"

    try:
        # Access data
        return "Data retrieved"
    except Exception as e:
        # Don't expose internal errors
        return "Unable to access data"

エラー処理

def read_file(path: str) -> str:
    """Read a local file."""
    try:
        with open(path, "r") as f:
            return f.read()
    except FileNotFoundError:
        return f"Error: File not found: {path}"
    except PermissionError:
        return f"Error: Permission denied: {path}"
    except Exception as e:
        return f"Error reading file: {str(e)}"

非同期操作

async def capture_photo() -> str:
    """Capture a photo from device camera."""
    # Simulate camera access
    await asyncio.sleep(1)
    return "photo_12345.jpg"

トラブルシューティング

ツールが呼び出されない

ツール宣言がサーバーに送信されることを確認する
ツールの説明が目的を明確に示すかどうかを確認する
ツールの登録に関するサーバーログを確認する

実行エラー

包括的なエラー処理を追加する
処理前にパラメーターを検証する
わかりやすいエラーメッセージを返す
デバッグのエラーをログに記録する

タイプの問題

複合型に Pydantic モデルを使用する
シリアル化の前にモデルをディクテーションに変換する
型変換を明示的に処理する

次のステップ

バックエンドツールレンダリング: サーバー側ツールとの組み合わせ

その他のリソース

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-11-11

次の方法で共有

AG-UI を使用したフロントエンド ツールのレンダリング

[前提条件]

フロントエンド ツールとは

クライアントでのフロントエンド ツールの登録

ツールをサーバーに送信する方法

ミドルウェアを使用したツールの検査と変更

主要概念

フロントエンド ツールのしくみ

サーバーサイドフロー

クライアントサイドフロー

フロントエンド ツールを使用した予想される出力

フロントエンド ツールのサーバーセットアップ

次のステップ

その他のリソース

[前提条件]

フロントエンド ツールとは

フロントエンド ツールの作成

フロントエンド ツールを使用した AG-UI クライアントの作成

フロントエンド ツールのしくみ

プロトコル フロー

キー イベント

予期される出力

サーバーのセットアップ

ベスト プラクティス

セキュリティ

エラー処理

非同期操作

トラブルシューティング

ツールが呼び出されない

実行エラー

タイプの問題

次のステップ

その他のリソース

フィードバック

その他のリソース

AG-UI を使用したフロントエンドツールのレンダリング

フロントエンドツールとは

クライアントでのフロントエンドツールの登録

フロントエンドツールのしくみ

フロントエンドツールを使用した予想される出力

フロントエンドツールのサーバーセットアップ

フロントエンドツールとは

フロントエンドツールの作成

フロントエンドツールを使用した AG-UI クライアントの作成

フロントエンドツールのしくみ

プロトコルフロー

キーイベント

ベストプラクティス