Layanan Agen Microsoft Foundry

FoundryAgentmenghubungkan Agent Framework ke definisi agen yang dikelola oleh Microsoft Foundry Agent Service. Model, instruksi, alat terhosting, dan versi agen dikonfigurasi di Foundry; aplikasi Anda terhubung ke definisi tersebut dan menggunakan API run, streaming, dan sesi standar Agent Framework.

Gunakan integrasi ini untuk:

Prompt Agents, yaitu definisi agen di sisi server yang diberi nama dan berversi.
Agen yang Di-hosting, yaitu aplikasi agen yang di-deploy dan diakses melalui endpoint khusus agen.

Untuk inferensi model langsung di mana aplikasi Anda memiliki definisi agen, lihat penyedia model Microsoft Foundry. Untuk menyebarkan aplikasi Agent Framework sebagai Agen yang Dihosting, lihat Foundry Hosted Agents.

Instal paket-paket tersebut

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

Hubungkan ke Agen Prompt

Buat AIProjectClient untuk proyek Foundry dan bungkus AgentReference sebagai FoundryAgent. Sematkan versi saat aplikasi harus menggunakan definisi Prompt Agent tertentu.

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?"));

Anda juga dapat mengambil ProjectsAgentRecord untuk menggunakan versi terbarunya atau ProjectsAgentVersion untuk menggunakan versi yang diambil secara eksplisit, lalu meneruskan objek tersebut ke projectClient.AsAIAgent(...).

Mengambil versi Prompt Agent terbaru

Gunakan AgentAdministrationClient ketika aplikasi harus menentukan versi terdaftar terbaru berdasarkan namanya.

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?"));

Penting

Sebuah FoundryAgent menggunakan model, instruksi, dan alat terhosting yang tersimpan dalam definisi Foundry-nya. Mengonfigurasi kemampuan tersebut di Foundry; klien tidak dapat menggantinya pada waktu proses.

Warning

DefaultAzureCredential nyaman untuk pengembangan. Dalam produksi, sebaiknya gunakan kredensial spesifik seperti ManagedIdentityCredential untuk menghindari penelusuran kredensial yang tidak disengaja.

Hubungkan ke Agen yang dihosting

Agen Terhosting menyediakan endpoint OpenAI yang khusus untuk agen. Bentuk titik akhir dari titik akhir proyek dan nama agen yang terdaftar, lalu teruskan ke 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();

Pemilih versi endpoint yang dikendalikan administrator menentukan versi Agen yang Dihosting yang aktif.

Instal paket-paket tersebut

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"

Gunakan FOUNDRY_AGENT_VERSION untuk Prompt Agents. Agen Hosted dapat tidak menyertakannya.

Hubungkan ke Prompt Agent

Berikan titik akhir proyek, nama agen, dan versi agen. Layanan ini menyediakan model tersimpan, instruksi, dan konfigurasi alat yang dihosting.

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()

Jika Prompt Agent mendeklarasikan alat fungsi lokal, teruskan callable yang sesuai melalui tools= saat membangun FoundryAgent agar klien dapat mengeksekusinya saat diminta. Lihat contoh Prompt Agent untuk menerbitkan dan menghubungkan.

Hubungkan ke Agen yang Di-host

Agen yang dihosting tidak memerlukan agent_version. Sambungkan dengan titik akhir proyek dan nama agen terdaftar.

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}")

Apa yang berfungsi dan apa yang tidak dengan `FoundryAgent`

FoundryAgent menyambungkan ke definisi agen yang sudah ada di Foundry. Instruksi tersimpan dan konfigurasi alat bersifat otoritatif, sehingga perilaku sisi klien berbeda dari yang dimiliki Agent(client=FoundryChatClient(...))aplikasi .

Tools

Jenis alat yang diteruskan ke `FoundryAgent(...)`	Behavior
`FunctionTool`dengan Python lokal yang dapat dipanggil	Didukung hanya ketika definisi fungsi yang cocok sudah ada pada agen Foundry. Fungsi yang dapat dipanggil berjalan di dalam proses aplikasi saat diminta oleh Foundry.
Alat yang dihosting, termasuk pencarian web, penerjemah kode, pencarian file, MCP, pembuatan gambar, dan Microsoft Foundry Toolbox	Konfigurasikan ini pada definisi agen Foundry. Meneruskannya di sisi klien tidak akan menambahkannya ke dalam agen yang dikelola oleh layanan.

Untuk lampiran Toolbox dan panduan terkait penggunaan MCP secara langsung, lihat Microsoft Foundry Toolbox.

Anda tidak dapat mendaftarkan alat baru yang dapat dilihat oleh model saat konstruksi. Meneruskan fungsi yang dapat dipanggil hanya menyediakan implementasi lokal untuk fungsi yang sudah dideklarasikan agen Foundry.

Penyedia konteks

Perilaku penyedia konteks	Kompatibel dengan `FoundryAgent`?
Menambahkan pesan, seperti memori yang diambil, cuplikan RAG, atau informasi profil pengguna	Yes. Konteks yang diinjeksikan diteruskan bersama permintaan.
Mempertahankan atau mengamati percakapan	Yes. Penyedia berjalan secara lokal di sekitar permintaan dan respons.
Menambahkan alat secara dinamis	Tidak, kecuali alat-alat tersebut sudah dideklarasikan pada definisi agen Foundry.

Gunakan Agent(client=FoundryChatClient(...)) saat aplikasi memerlukan pemilihan alat secara dinamis, pemuatan keterampilan, atau perilaku lain yang mengubah alat yang terlihat oleh model saat runtime.

Opsi jalankan

Karena definisi agen Foundry adalah sumber kebenaran, tidak setiap opsi yang dilewati default_options atau agent.run(...) dihormati.

Option	Perilaku Prompt Agent
`model`	Diabaikan. Model ini berasal dari definisi agen Foundry.
`tools`, `tool_choice`, `parallel_tool_calls`	Dihapus dari permintaan. Alat harus dideklarasikan pada definisi agen Foundry.
`instructions` dan pesan sistem atau pengembang	Diabaikan. Instruksi Foundry yang disimpan bersifat otoritatif.
`conversation_id`	Digunakan dan dipetakan ke sesi agen Foundry jika berlaku.
`extra_body`	Diteruskan dan digabungkan dengan referensi agen yang disediakan oleh framework.
Parameter pengambilan sampel, metadata, `user`, , `store`dan `response_format`	Diteruskan, tetapi agen Foundry atau konfigurasi model dapat mengambil alih atau membatasinya.

Agen terhosting menerima pemfilteran di sisi klien yang sama, tetapi agen yang diterapkan dapat menerima, mengabaikan, atau menafsirkan ulang opsi yang diteruskan. Verifikasi perilaku terhadap Agen yang Dihosting tertentu.

Tip

Gunakan Agent(client=FoundryChatClient(...)) saat Anda memerlukan kontrol per eksekusi atas instruksi, opsi pembuatan, atau alat.

Mengelola sesi layanan Agen yang Dihosting

Agen yang Dihosting yang menggunakan sesi sisi layanan memerlukan permukaan Respons pratinjau:

Buat sesi layanan secara eksplisit ketika aplikasi harus mengikatnya ke penyewa atau pengguna, lalu bungkus pengidentifikasinya sebagai sesi Kerangka Kerja Agen.

    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 Lihat sampel untuk contoh lengkap.

Mengatur batas waktu HTTP kustom

FoundryAgent menggunakan batas waktu bawaan dari OpenAI SDK. Masukkan timeout= dalam satuan detik jika percakapan multi putaran atau kondisi jaringan memerlukan batas yang berbeda.

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,
)

Waktu tunggu diterapkan pada setiap salinan klien HTTP per agen dan tidak memengaruhi agen lain yang menggunakan AIProjectClient yang sama.

Nota

FoundryAgent integrasi untuk Prompt dan Hosted Agents saat ini tidak tersedia untuk Agent Framework Go. Lihat repositori Agent Framework Go untuk status terbaru.

Jalankan, streamingkan, dan teruskan percakapan

Setelah menyambungkan, gunakan API yang sama dengan agen Agent Framework lainnya:

Jalankan permintaan dengan RunAsync atau run.
Streaming pembaruan dengan RunStreamingAsync atau run(..., stream=True).
Gunakan kembali AgentSession untuk melanjutkan percakapan.
Gunakan API percakapan sisi server Foundry saat percakapan harus terlihat dan bertahan dalam proyek Foundry.

Pertahankan nama agen Foundry, versi, titik akhir, dan pengidentifikasi percakapan dalam status sisi server tepercaya. Otorisasi pemanggil sebelum memulai kembali percakapan yang ada.

Langkah berikutnya

Meninjau penyedia model Microsoft Foundry

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-08-25

Layanan Agen Microsoft Foundry

Instal paket-paket tersebut

Hubungkan ke Agen Prompt

Mengambil versi Prompt Agent terbaru

Hubungkan ke Agen yang dihosting

Instal paket-paket tersebut

Configuration

Hubungkan ke Prompt Agent

Hubungkan ke Agen yang Di-host

Apa yang berfungsi dan apa yang tidak dengan FoundryAgent

Tools

Penyedia konteks

Opsi jalankan

Mengelola sesi layanan Agen yang Dihosting

Mengatur batas waktu HTTP kustom

Jalankan, streamingkan, dan teruskan percakapan

Langkah berikutnya

Saran dan Komentar

Sumber Daya Tambahan:

Apa yang berfungsi dan apa yang tidak dengan `FoundryAgent`