第7章最小のエージェントを作って会話する

本章は初稿です。

7.1 この章で学ぶこと

ここからは、部品を一つずつつなぎます。最初の Agent は、モデルと短い指示だけを持ち、社内文書の検索やチケット登録は行いません。「まだできないこと」を明確にしておくと、後でツールを追加した効果が分かります。

到達点は、Agent の定義、Conversation の作成、Response の生成を区別し、一つの質問を送って出力を確認することです。接続前に、第5章の準備表と第6章の通信経路を確認してください。

7.2 図で最初の呼び出しを追う

公式クイックスタートは、モデルと指示を指定した Prompt エージェントを作り、会話と応答を通じてやり取りする例を示しています。[^quickstart]

図7-1 定義する操作と、質問に答える操作は別である。 上から順に読み、実線は要求、破線は結果です。資格情報の取得やネットワークの内部は省略しています。この段階では検索ツールを設定していません。

操作	入力するもの	確認するもの
Agent の版を定義する	名前、モデル、指示	作成された名前と版
Conversation を作る	新しい相談の開始	会話の ID
Response を生成する	会話の ID と利用者の入力	応答の ID、状態、出力

利用者が発言するたびに Agent を作り直す必要はありません。振る舞いを再利用し、相談の履歴を会話として扱います。

7.3 学習用コードを読む

次は、Azure AI Projects SDK 2.x 系の公式例を基にした学習用コードです。[^quickstart] 本教材では Azure へ接続して動作検証していません。実行する場合は、公式手順のパッケージ、認証、利用可能なモデルを再確認してください。

第5章の三つの環境変数を設定し、自分専用の学習用作業ディレクトリに first_agent.py として保存する想定です。実在する社内情報や資格情報は入力しません。

python

import os

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition
from azure.identity import DefaultAzureCredential

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
deployment = os.environ["FOUNDRY_MODEL_DEPLOYMENT"]
agent_name = os.environ["FOUNDRY_AGENT_NAME"]

instructions = (
    "あなたは社内 IT 支援の学習用アシスタントです。"
    "相談内容を整理し、不足する情報を確認してください。"
    "まだ社内文書を参照できないため、会社固有の設定値は断定しないでください。"
)

with DefaultAzureCredential() as credential:
    with AIProjectClient(endpoint=endpoint, credential=credential) as project:
        agent = project.agents.create_version(
            agent_name=agent_name,
            definition=PromptAgentDefinition(
                model=deployment,
                instructions=instructions,
            ),
        )
        print(f"agent={agent.name}, created_version={agent.version}")

        with project.get_openai_client(agent_name=agent.name) as client:
            conversation = client.conversations.create()
            response = client.responses.create(
                conversation=conversation.id,
                input="VPN の相談をしたいのですが、何を伝えればよいですか。",
            )
            if response.status != "completed":
                raise RuntimeError(f"Response did not complete: {response.status}")
            if not response.output_text:
                raise RuntimeError("The response did not contain answer text.")

            print(f"conversation={conversation.id}, response={response.id}")
            print(response.output_text)

環境変数がなければ、別の接続先で黙って実行せず、読み出し時にエラーになります。API の失敗も、成功した回答へ置き換える処理はありません。失敗した場所とサービスの診断情報から、準備、権限、経路、入力を順に確認します。

この例のクライアントは Agent の名前を指定しています。名前だけの参照を、作成した版への厳密な固定と同一視しないでください。学習中は同名 Agent を他の処理で更新せず、作成した版を記録します。版を厳密に指定する実装は、利用する SDK の参照方法を確認して追加します。

7.4 返ってきたものを観察する

表示される文章そのものは固定しません。たとえば OS、エラー表示、発生時期を尋ねる回答なら、相談の入口として評価できます。一方、「会社の VPN サーバー名はこれです」と根拠なく断定するなら、期待する振る舞いではありません。

response.output_text は文章を読むための便利な入口ですが、Response 全体と同じものではありません。後でツールを使う場合には、関数要求などを response.output から取り出します。[^runtime]

観察する点	この段階での期待
相談を理解したか	必要な確認事項を挙げる
社内情報を知っているように振る舞わないか	固有の設定値を作らない
検索や登録をしたと主張しないか	設定していない機能の実行を装わない
調査用の識別子があるか	Agent、会話、応答を区別して記録する

7.5 小さな実習：できないことも確かめる

最初の質問を「当社の正しい VPN サーバー名を教えて」に置き換えます。ツールも社内文書も追加せず、回答を観察してください。

期待するのは、もっともらしい設定値ではなく、「その会社の情報を参照できない」と分かる応答です。机上学習なら、望ましい回答例と望ましくない回答例を一つずつ作り、理由を書きます。実行した場合は、入力、指示、作成した版、応答の ID、観察結果を残します。

コードの再実行は Agent の新しい版を作り、会話も新しく作ります。比較のために一時的に残す場合も、不要な版や会話を学習後に整理します。接続を閉じる with 文は、サービス側の版や履歴を削除する処理ではありません。

7.6 確認課題

「Agent の作成に成功した」「Response が完了した」「社内の質問に正しく答えた」は、それぞれ別の判定です。今回のコードで確認できるものと、まだ確認できないものを説明してください。

この段階では、社内の根拠に基づく回答品質は検証できません。社内検索につなぐ前に、生成された文章を社内の正式な手順として扱わないことが重要です。

7.7 まとめ

最小の Agent でも、準備、定義、会話、応答という流れがあります。まず接続と一回の入出力を確認し、次章で指示の変更が振る舞いへ与える影響を学びます。

7.8 参考情報

Quickstart: Create a prompt agent — 本章のコードを試す際の最新の前提条件と実行例
Build with runtime components in Foundry Agent Service — 応答の出力項目と会話の扱い

[^quickstart]: Quickstart: Create a prompt agent — Microsoft

[^runtime]: Build with runtime components in Foundry Agent Service — Microsoft

前章：第6章 Microsoft Foundry のネットワーク構成を設計する · 教材の目次へ戻る · 次章：第8章指示でエージェントの振る舞いを整える

第7章 最小のエージェントを作って会話する