Layanan Agen Microsoft Foundry

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

Gunakan integrasi ini untuk:

Prompt Agents, yang diberi nama dan definisi agen sisi server versi.
Agen yang Dihosting, yang merupakan aplikasi agen yang disebarkan dicapai melalui titik akhir 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

Menyambungkan ke Agen Prompt

AIProjectClient Buat 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 menyelesaikan versi terdaftar terbaru berdasarkan nama.

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

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

Warning

DefaultAzureCredential nyaman untuk pengembangan. Dalam produksi, lebih suka kredensial tertentu seperti ManagedIdentityCredential untuk menghindari pemeriksaan kredensial yang tidak diinginkan.

Menyambungkan ke Agen yang Dihosting

Agen yang Dihosting mengekspos titik akhir OpenAI khusus agen. Buat titik akhir dari titik akhir proyek dan nama agen 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 yang dikontrol administrator titik akhir menentukan versi Agen yang Dihosting 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 yang Dihosting dapat menghilangkannya.

Menyambungkan ke Agen Prompt

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, berikan panggilan yang tools= cocok saat membuat FoundryAgent sehingga klien dapat menjalankannya saat diminta. Lihat Sampel penerbitan dan koneksi Prompt Agent.

Menyambungkan ke Agen yang Dihosting

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. Panggilan berjalan dalam proses aplikasi ketika Foundry memintanya.
Alat yang dihosting, termasuk pencarian web, penerjemah kode, pencarian file, MCP, pembuatan gambar, dan Microsoft Foundry Toolbox	Konfigurasikan ini pada definisi agen Foundry. Meneruskannya sisi klien tidak menambahkannya ke agen yang dikelola layanan.

Untuk lampiran Toolbox dan panduan konsumsi MCP langsung, lihat Microsoft Foundry Toolbox.

Anda tidak dapat mendaftarkan alat baru yang terlihat model pada waktu 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 membutuhkan pemilihan alat dinamis, pemuatan keterampilan, atau perilaku apa pun yang mengubah alat yang terlihat model pada waktu proses.

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_choiceparallel_tool_calls`	Dihapus dari permintaan. Alat harus dideklarasikan pada definisi agen Foundry.
`instructions` 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 kerangka kerja.
Parameter pengambilan sampel, metadata, `user`, , `store`dan `response_format`	Diteruskan, tetapi agen Foundry atau konfigurasi model dapat mengambil alih atau membatasinya.

Agen yang Dihosting menerima pemfilteran sisi klien yang sama, tetapi agen yang disebarkan dapat menerima, mengabaikan, atau menginterpretasikan kembali 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 mewarisi batas waktu OpenAI SDK secara default. Teruskan timeout= dalam detik saat percakapan multi-giliran 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,
)

Batas waktu diterapkan ke salinan per agen klien HTTP dan tidak memengaruhi agen lain yang berbagi yang sama AIProjectClient.

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, streaming, dan lanjutkan 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 AgentSession kembali 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-13

Layanan Agen Microsoft Foundry

Instal paket-paket tersebut

Menyambungkan ke Agen Prompt

Mengambil versi Prompt Agent terbaru

Menyambungkan ke Agen yang Dihosting

Instal paket-paket tersebut

Configuration

Menyambungkan ke Agen Prompt

Menyambungkan ke Agen yang Dihosting

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, streaming, dan lanjutkan percakapan

Langkah berikutnya

Saran dan Komentar

Sumber Daya Tambahan:

Apa yang berfungsi dan apa yang tidak dengan `FoundryAgent`