実行中のエージェント

基本エージェントの抽象化では、エージェントを実行するためのさまざまなオプションが公開されます。呼び出し元は、0 個、1 個、または多数の入力メッセージを指定できます。呼び出し元は、ストリーミングと非ストリーミングのどちらかを選択することもできます。さまざまな使用シナリオを見てみましょう。

ストリーミングと非ストリーミング

Microsoft Agent Framework では、エージェントを実行するためのストリーミングメソッドと非ストリーミングメソッドの両方がサポートされています。

ストリーミング以外の場合は、 RunAsync メソッドを使用します。

Console.WriteLine(await agent.RunAsync("What is the weather like in Amsterdam?"));

ストリーミングには、 RunStreamingAsync メソッドを使用します。

await foreach (var update in agent.RunStreamingAsync("What is the weather like in Amsterdam?"))
{
    Console.Write(update);
}

ストリーミング以外の場合は、 run メソッドを使用します。

result = await agent.run("What is the weather like in Amsterdam?")
print(result.text)

ストリーミングには、 run_stream メソッドを使用します。

async for update in agent.run_stream("What is the weather like in Amsterdam?"):
    if update.text:
        print(update.text, end="", flush=True)

エージェントの実行オプション

基本エージェントの抽象化では、エージェントの実行ごとにオプションオブジェクトを渡すことが可能ですが、抽象化レベルで実行をカスタマイズする機能は非常に限られています。エージェントは大きく異なる可能性があるため、一般的なカスタマイズオプションはありません。

呼び出し元が使用しているエージェントの種類を認識している場合は、型固有のオプションを渡して実行をカスタマイズできます。

たとえば、ここではエージェントはChatClientAgentであり、ChatClientAgentRunOptionsから継承するAgentRunOptions オブジェクトを渡すことができます。これにより、呼び出し元は、ChatOptionsが構築されているIChatClientに渡される前に、エージェントレベルのオプションとマージされるカスタム ChatClientAgentを提供できます。

var chatOptions = new ChatOptions() { Tools = [AIFunctionFactory.Create(GetWeather)] };
Console.WriteLine(await agent.RunAsync("What is the weather like in Amsterdam?", options: new ChatClientAgentRunOptions(chatOptions)));

Python エージェントでは、各実行をカスタマイズするためのキーワード引数の渡しがサポートされています。使用できる具体的なオプションはエージェントの種類によって異なりますが、 ChatAgent では、 run メソッドと run_stream メソッドの両方に渡すことができる多くのチャットクライアントパラメーターがサポートされています。

ChatAgentの一般的なオプションは次のとおりです。

max_tokens: 生成するトークンの最大数
temperature: 応答生成のランダム性を制御します。
model: この特定の実行のモデルをオーバーライドします
tools: この実行専用のツールを追加する
response_format: 応答形式 (構造化出力など) を指定します。

# Run with custom options
result = await agent.run(
    "What is the weather like in Amsterdam?",
    temperature=0.3,
    max_tokens=150,
    model="gpt-4o"
)

# Streaming with custom options
async for update in agent.run_stream(
    "Tell me a detailed weather forecast",
    temperature=0.7,
    tools=[additional_weather_tool]
):
    if update.text:
        print(update.text, end="", flush=True)

エージェントレベルの既定値と実行レベルのオプションの両方が指定されている場合は、実行レベルのオプションが優先されます。

応答の種類

エージェントからのストリーミング応答と非ストリーミング応答の両方に、エージェントによって生成されたすべてのコンテンツが含まれます。コンテンツには、エージェントからの結果 (つまり、ユーザーの質問に対する回答) ではないデータが含まれる場合があります。返されるその他のデータの例としては、関数ツールの呼び出し、関数ツール呼び出しの結果、推論テキスト、状態の更新などがあります。

返されるすべてのコンテンツが結果であるとは言えないので、他のコンテンツから結果を分離しようとするときに、特定のコンテンツタイプを検索することが重要です。

応答からテキストの結果を抽出するには、すべてのTextContent項目のすべてのChatMessages項目を集計する必要があります。これを簡略化するために、すべてのTextContentを集計するすべての応答の種類でTextプロパティを使用できます。

非ストリーミングの場合、すべてが 1 つの AgentRunResponse オブジェクトで返されます。 AgentRunResponse では、 Messages プロパティを使用して生成されたメッセージにアクセスできます。

var response = await agent.RunAsync("What is the weather like in Amsterdam?");
Console.WriteLine(response.Text);
Console.WriteLine(response.Messages.Count);

ストリーミングの場合、 AgentRunResponseUpdate オブジェクトは生成時にストリーミングされます。各更新プログラムには、エージェントからの結果の一部と、その他のさまざまなコンテンツ項目が含まれる場合があります。ストリーミング以外の場合と同様に、 Text プロパティを使用して、更新に含まれる結果の部分を取得し、 Contents プロパティを使用して詳細を調べることができます。

await foreach (var update in agent.RunStreamingAsync("What is the weather like in Amsterdam?"))
{
    Console.WriteLine(update.Text);
    Console.WriteLine(update.Contents.Count);
}

非ストリーミングの場合、すべてが 1 つの AgentRunResponse オブジェクトで返されます。 AgentRunResponse では、 messages プロパティを使用して生成されたメッセージにアクセスできます。

応答からテキストの結果を抽出するには、すべてのTextContent項目のすべてのChatMessage項目を集計する必要があります。これを簡略化するために、すべてのTextContentを集計するすべての応答の種類でTextプロパティを使用できます。

response = await agent.run("What is the weather like in Amsterdam?")
print(response.text)
print(len(response.messages))

# Access individual messages
for message in response.messages:
    print(f"Role: {message.role}, Text: {message.text}")

ストリーミングの場合、 AgentRunResponseUpdate オブジェクトは生成時にストリーミングされます。各更新プログラムには、エージェントからの結果の一部と、その他のさまざまなコンテンツ項目が含まれる場合があります。ストリーミング以外の場合と同様に、 text プロパティを使用して、更新に含まれる結果の部分を取得し、 contents プロパティを使用して詳細を調べることができます。

async for update in agent.run_stream("What is the weather like in Amsterdam?"):
    print(f"Update text: {update.text}")
    print(f"Content count: {len(update.contents)}")

    # Access individual content items
    for content in update.contents:
        if hasattr(content, 'text'):
            print(f"Content: {content.text}")

メッセージの種類

エージェントからの入力と出力はメッセージとして表されます。メッセージはコンテンツ項目に分割されます。

Microsoft Agent Framework では、 Microsoft.Extensions.AI 抽象化によって提供されるメッセージとコンテンツタイプが使用されます。メッセージは ChatMessage クラスによって表され、すべてのコンテンツクラスは基本 AIContent クラスから継承されます。

さまざまな種類のコンテンツを表すために使用されるさまざまな AIContent サブクラスが存在します。一部は基本 Microsoft.Extensions.AI 抽象化の一部として提供されますが、プロバイダーは必要に応じて独自の型を追加することもできます。

Microsoft.Extensions.AIの一般的な種類を次に示します。

タイプ	Description
TextContent	ユーザーや開発者からの入力と、エージェントからの出力の両方が可能なテキストコンテンツ。通常、エージェントからのテキストの結果が含まれます。
DataContent	入力と出力の両方が可能なバイナリコンテンツ。エージェントとの間でイメージ、オーディオ、またはビデオのデータを渡すために使用できます (サポートされている場合)。
UriContent	通常、ホストされているコンテンツ (画像、オーディオ、ビデオなど) を指す URL。
FunctionCallContent	関数ツールを呼び出す推論サービスによる要求。
FunctionResultContent	関数ツールの呼び出しの結果。

Python エージェントフレームワークは、 agent_framework パッケージのメッセージとコンテンツタイプを使用します。メッセージは ChatMessage クラスによって表され、すべてのコンテンツクラスは基本 BaseContent クラスから継承されます。

さまざまな種類のコンテンツを表すために使用されるさまざまな BaseContent サブクラスが存在します。

タイプ	Description
`TextContent`	エージェントからの入力と出力の両方が可能なテキストコンテンツ。通常、エージェントからのテキストの結果が含まれます。
`DataContent`	データ URI として表されるバイナリコンテンツ (base64 でエンコードされたイメージなど)。エージェントとの間でバイナリデータを渡すために使用できます。
`UriContent`	画像、オーディオファイル、ドキュメントなどのホストされているコンテンツを指す URI。
`FunctionCallContent`	関数ツールを呼び出す AI サービスによる要求。
`FunctionResultContent`	関数ツールの呼び出しの結果。
`ErrorContent`	処理が失敗したときのエラー情報。
`UsageContent`	AI サービスからのトークンの使用状況と課金情報。

さまざまなコンテンツタイプを操作する方法を次に示します。

from agent_framework import ChatMessage, TextContent, DataContent, UriContent

# Create a text message
text_message = ChatMessage(role="user", text="Hello!")

# Create a message with multiple content types
image_data = b"..."  # your image bytes
mixed_message = ChatMessage(
    role="user",
    contents=[
        TextContent("Analyze this image:"),
        DataContent(data=image_data, media_type="image/png"),
    ]
)

# Access content from responses
response = await agent.run("Describe the image")
for message in response.messages:
    for content in message.contents:
        if isinstance(content, TextContent):
            print(f"Text: {content.text}")
        elif isinstance(content, DataContent):
            print(f"Data URI: {content.uri}")
        elif isinstance(content, UriContent):
            print(f"External URI: {content.uri}")

次のステップ

複数ターンの会話とスレッド

フィードバック

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

Last updated on 2025-10-01