マイクロソフト ファウンドリー エージェント サービス

FoundryAgentは、Agent Framework を Foundry Agent Service によって管理されるエージェント定義Microsoft接続します。 エージェントのモデル、命令、ホストされているツール、およびバージョンは Foundry で構成されます。アプリケーションはその定義に接続し、標準の Agent Framework の実行、ストリーミング、およびセッション API を使用します。

次の場合に、この統合を使用します。

  • プロンプト エージェント。名前付きおよびバージョン管理されたサーバー側エージェント定義です。
  • ホストされたエージェント。エージェント固有のエンドポイントを介して到達したエージェント アプリケーションがデプロイされます。

アプリケーションがエージェント定義を所有する直接モデル推論については、Foundry モデル プロバイダー Microsoft参照してください。 Agent Framework アプリケーションをホスト型エージェントとしてデプロイするには、「 Foundry Hosted Agents」を参照してください。

パッケージをインストールする

dotnet add package Azure.AI.Projects --prerelease
dotnet add package Azure.Identity
dotnet add package Microsoft.Agents.AI.Foundry --prerelease

プロンプト エージェントに接続する

Foundry プロジェクトの AIProjectClient を作成し、 AgentReference を FoundryAgentとしてラップします。 アプリケーションで特定のプロンプト エージェント定義を使用する必要がある場合は、バージョンをピン留めします。

using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.Identity;
using Microsoft.Agents.AI.Foundry;

var projectClient = new AIProjectClient(
    new Uri(Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")!),
    new DefaultAzureCredential());

FoundryAgent agent = projectClient.AsAIAgent(
    new AgentReference(
        Environment.GetEnvironmentVariable("FOUNDRY_AGENT_NAME")!,
        Environment.GetEnvironmentVariable("FOUNDRY_AGENT_VERSION")!));

Console.WriteLine(await agent.RunAsync("What can you help me with?"));

また、最新バージョンを使用する ProjectsAgentRecord や、明示的に取得したバージョンを使用する ProjectsAgentVersion を取得し、そのオブジェクトを projectClient.AsAIAgent(...)に渡すこともできます。

最新の Prompt Agent バージョンを取得する

アプリケーションが登録されている最新バージョンを名前で解決する必要がある場合は、 AgentAdministrationClient を使用します。

ProjectsAgentRecord agentRecord =
    await projectClient.AgentAdministrationClient.GetAgentAsync(
        Environment.GetEnvironmentVariable("FOUNDRY_AGENT_NAME")!);

FoundryAgent latestAgent = projectClient.AsAIAgent(agentRecord);
Console.WriteLine(await latestAgent.RunAsync("What can you help me with?"));

Important

FoundryAgentは、Foundry 定義に格納されているモデル、命令、およびホステッド ツールを使用します。 Foundry でこれらの機能を構成します。クライアントは、実行時にそれらを置き換えることはできません。

Warning

DefaultAzureCredential は開発に便利です。 運用環境では、意図しない資格情報のプローブを回避するために、 ManagedIdentityCredential などの特定の資格情報を使用します。

ホストされるエージェントに接続する

ホストされるエージェントは、エージェント固有の OpenAI エンドポイントを公開します。 プロジェクト エンドポイントと登録済みエージェント名からエンドポイントをビルドし、 AIProjectClient.AsAIAgent(...)に渡します。

Env.TraversePath().Load();

// Port the Hosted-* samples listen on when run locally with `dotnet run`.
const int LocalAgentPort = 8088;

// AZURE_AI_AGENT_NAME is the registered server-side agent name.
string agentName = Environment.GetEnvironmentVariable("AZURE_AI_AGENT_NAME")
    ?? throw new InvalidOperationException("AZURE_AI_AGENT_NAME is not set.");

// Pick the server to talk to. `--local` and `--remote` mirror the flag `azd ai agent invoke`
// exposes; with neither, ask at startup.
    ══════════════════════════════════════════════════════════
    """);
Console.ResetColor();
Console.WriteLine();

エンドポイントの管理者が制御するバージョン セレクターによって、アクティブな Hosted Agent のバージョンが決まります。

パッケージをインストールする

pip install agent-framework-foundry

Configuration

FOUNDRY_PROJECT_ENDPOINT="https://<your-project>.services.ai.azure.com"
FOUNDRY_AGENT_NAME="my-agent"
FOUNDRY_AGENT_VERSION="1.0"

プロンプト エージェントの FOUNDRY_AGENT_VERSION を使用します。 ホストされるエージェントでは、これを省略できます。

プロンプト エージェントに接続する

プロジェクト エンドポイント、エージェント名、およびエージェントのバージョンを指定します。 このサービスは、格納されているモデル、命令、およびホステッド ツールの構成を提供します。

async def main() -> None:
    agent = FoundryAgent(
        project_endpoint="https://your-project.services.ai.azure.com",
        agent_name="my-prompt-agent",
        agent_version="1.0",
        credential=AzureCliCredential(),
    )

    result = await agent.run("What is the capital of France?")
    print(f"Agent: {result}")

    # Streaming
    print("Agent (streaming): ", end="", flush=True)
    async for chunk in agent.run("Tell me a fun fact.", stream=True):
        if chunk.text:
            print(chunk.text, end="", flush=True)
    print()

プロンプト エージェントがローカル関数ツールを宣言する場合は、クライアントが要求されたときに実行できるように、FoundryAgentを構築するときにtools=を介して一致する呼び出し可能オブジェクトを渡します。 プロンプト エージェントの発行と接続のサンプルを参照してください。

ホストされるエージェントに接続する

ホストされるエージェントでは、 agent_versionは必要ありません。 プロジェクト エンドポイントと登録済みのエージェント名で接続します。

async def main() -> None:
    # HostedAgents don't need agent_version
    agent = FoundryAgent(
        project_endpoint=os.getenv("FOUNDRY_PROJECT_ENDPOINT"),
        agent_name=os.getenv("FOUNDRY_AGENT_NAME"),
        credential=AzureCliCredential(),
    )

    result = await agent.run("Summarize the latest news about AI.")
    print(f"Agent: {result}")

何が機能し、何が機能しないのか FoundryAgent

FoundryAgent は、Foundry に既に存在するエージェント定義に接続します。 格納されている命令とツールの構成は権限があるため、クライアント側の動作はアプリケーション所有の Agent(client=FoundryChatClient(...))とは異なります。

Tools

FoundryAgent(...) に渡されるツールの種類 Behavior
FunctionToolローカル Python呼び出し可能 Foundry エージェントに一致する関数定義が既に存在する場合にのみサポートされます。 呼び出し可能オブジェクトは、Foundry が要求したときにアプリケーション プロセスで実行されます。
Web 検索、コード インタープリター、ファイル検索、MCP、イメージ生成、Microsoft Foundry ツールボックスなど、ホストされているツール Foundry エージェント定義でこれらを構成します。 クライアント側で渡しても、サービスマネージド エージェントには追加されません。

ツールボックスの添付ファイルと直接の MCP 消費ガイダンスについては、「foundry ツールボックスMicrosoft参照してください。

構築時に新しいモデル表示ツールを登録することはできません。 呼び出し可能な関数を渡すと、Foundry エージェントによって既に宣言されている関数のローカル実装のみが提供されます。

コンテキスト プロバイダー

コンテキスト プロバイダーの動作 FoundryAgentで動作しますか?
取得したメモリ、RAG スニペット、ユーザー プロファイル情報などのメッセージを追加します Yes. 挿入されたコンテキストは要求と共に転送されます。
会話を永続化または観察する Yes. プロバイダーは、要求と応答をローカルで実行します。
ツールを動的に追加する いいえ。これらのツールが Foundry エージェント定義で既に宣言されている場合を除きます。

アプリケーションで動的なツールの選択、スキルの読み込み、または実行時にモデルに表示されるツールを変更する動作が必要な場合は、 Agent(client=FoundryChatClient(...)) を使用します。

実行オプション

Foundry エージェント定義は信頼の源であるため、 default_options または agent.run(...) を通じて渡されるすべてのオプションが受け入れられないわけではありません。

オプション エージェントの動作を確認する
model 無視されます。 モデルは Foundry エージェント定義に由来します。
tools、tool_choice、parallel_tool_calls 要求から削除されました。 Foundry エージェント定義でツールを宣言する必要があります。
instructions およびシステムまたは開発者のメッセージ 無視されます。 格納されている Foundry 命令は権限があります。
conversation_id 必要に応じて、Foundry エージェント セッションに使用され、マップされます。
extra_body フレームワークによって提供されるエージェント参照に転送およびマージされます。
サンプリング パラメーター、メタデータ、 user、 store、および response_format 転送されますが、Foundry エージェントまたはモデルの構成は、それらをオーバーライドまたは制約できます。

ホストされるエージェントは、同じクライアント側のフィルター処理を受け取りますが、デプロイされたエージェントは、転送されたオプションを受け入れる、無視する、または再解釈できます。 特定のホステッド エージェントに対する動作を確認します。

Tip

命令、生成オプション、またはツールを実行ごとに制御する必要がある場合は、 Agent(client=FoundryChatClient(...)) を使用します。

Hosted Agent サービス セッションを管理する

サービス側セッションを使用するホスト型エージェントには、プレビュー応答画面が必要です。

アプリケーションがテナントまたはユーザーにバインドする必要がある場合は、サービス セッションを明示的に作成し、その識別子をエージェント フレームワーク セッションとしてラップします。

    queries = [
        "Hi!",
        "Your name is Javis. What can you do?",
        "What is your name?",
    ]
    for query in queries:
        print(f"\nUser: {query}")
        print("Agent: ", end="", flush=True)
        async for chunk in agent.run(query, session=session, stream=True):
            if chunk.text:
                print(chunk.text, end="", flush=True)
    print()


async def run_service_managed_session(
    *,
    agent: FoundryAgent,
    project_client: AIProjectClient,
    agent_name: str,
) -> None:
    """Let Foundry create the hosted-agent session, then delete it when finished."""
    session = AgentSession()
    print("\nService-managed hosted-agent session")
    print(f"Before first request: {session.state.get(FOUNDRY_HOSTED_AGENT_SESSION_ID_KEY)}")
    try:
        await run_conversation(agent, session)
        print(f"After conversation: {session.state.get(FOUNDRY_HOSTED_AGENT_SESSION_ID_KEY)}")
    finally:
        hosted_session_id = session.state.get(FOUNDRY_HOSTED_AGENT_SESSION_ID_KEY)
        if isinstance(hosted_session_id, str) and hosted_session_id:
            await project_client.agents.delete_session(agent_name, hosted_session_id)
            print(f"Deleted session: {hosted_session_id}")


async def run_user_managed_session(
    *,
    agent: FoundryAgent,
    project_client: AIProjectClient,
    agent_name: str,
    agent_version: str | None,
) -> None:
    """Create, attach, and delete a hosted-agent session explicitly."""
    resolved_agent_version = agent_version
    if resolved_agent_version is None:
        agent_details = await project_client.agents.get(agent_name)
        resolved_agent_version = agent_details.versions.latest.version

    hosted_session = await project_client.agents.create_session(
        agent_name,
        version_indicator=VersionRefIndicator(agent_version=resolved_agent_version),
    )
    session = AgentSession()
    session.state[FOUNDRY_HOSTED_AGENT_SESSION_ID_KEY] = hosted_session.agent_session_id

    print("\nUser-managed hosted-agent session")
    print(f"Created session: {hosted_session.agent_session_id}")
    try:
        await run_conversation(agent, session)
    finally:
        await project_client.agents.delete_session(agent_name, hosted_session.agent_session_id)
        print(f"Deleted session: {hosted_session.agent_session_id}")


async def main() -> None:
    credential = AzureCliCredential()
    project_endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
    agent_name = os.environ["FOUNDRY_AGENT_NAME"]
    agent_version = os.getenv("FOUNDRY_AGENT_VERSION")

    project_client = AIProjectClient(

Tip

完全な例については、 using_deployed_agent.py サンプル を参照してください。

カスタム HTTP タイムアウトを設定する

FoundryAgent は、既定で OpenAI SDK タイムアウトを継承します。 複数ターンの会話やネットワーク条件に別の制限が必要な場合に、 timeout= を秒単位で渡します。

from agent_framework.foundry import FoundryAgent
from azure.identity import AzureCliCredential

agent = FoundryAgent(
    project_endpoint="https://your-project.services.ai.azure.com",
    agent_name="my-prompt-agent",
    credential=AzureCliCredential(),
    timeout=120.0,
)

タイムアウトは HTTP クライアントのエージェントごとのコピーに適用され、同じ AIProjectClientを共有する他のエージェントには影響しません。

Note

FoundryAgent Prompt と Hosted Agents の統合は現在、Agent Framework Go では使用できません。 最新の状態については、 Agent Framework Go リポジトリ を参照してください。

会話を実行、ストリーミング、続行する

接続後、他の Agent Framework エージェントと同じ API を使用します。

  • RunAsyncまたはrunを使用して要求を実行します。
  • RunStreamingAsyncまたはrun(..., stream=True)を使用して更新プログラムをストリーミングします。
  • AgentSessionを再利用して会話を続けます。
  • Foundry プロジェクトで会話を表示して永続化する必要がある場合は、Foundry サーバー側の会話 API を使用します。

Foundry エージェント名、バージョン、エンドポイント、および会話識別子は、信頼されたサーバー側の状態のままにします。 既存の会話を再開する前に、呼び出し元を承認します。

次のステップ

Foundry モデル プロバイダー Microsoft確認する

  • Last updated on