Microsoft Foundry

Microsoft Agent Framework mendukung pengambilan kesimpulan model langsung dari titik akhir proyek Microsoft Foundry dan agen yang dikelola oleh layanan di Layanan Agen Foundry.

Memulai Langkah Awal

Tambahkan paket NuGet yang diperlukan ke proyek Anda.

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

Dua jenis agen

Integrasi Microsoft Foundry mengekspos dua pola penggunaan yang berbeda:

Tipe Jenis yang diproduksi Deskripsi Gunakan ketika diperlukan
Agen Tanggapan ChatClientAgent Aplikasi Anda secara terprogram menyediakan model, instruksi, dan alat saat runtime melalui AIProjectClient.AsAIAgent(...). Tidak ada sumber daya agen sisi server yang dibuat. Anda memiliki definisi agen dan menginginkan penyiapan yang sederhana dan fleksibel. Ini adalah pola yang digunakan di sebagian besar sampel.
Agen Foundry (versi) FoundryAgent Dikelola server — definisi agen dibuat dan di-versi baik melalui portal Foundry atau secara terprogram melalui AIProjectClient.AgentAdministrationClient. Teruskan ProjectsAgentVersion atau ProjectsAgentRecord atau AgentReference ke AIProjectClient.AsAIAgent(...). Anda memerlukan definisi agen berversi yang ketat yang dikelola di portal Foundry, melalui API layanan

Agen Respon (inferensi langsung)

Gunakan AsAIAgent pada AIProjectClient langsung dengan model dan instruksi. Ini adalah titik awal yang direkomendasikan untuk sebagian besar skenario.

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

AIAgent agent = new AIProjectClient(
    new Uri("<your-foundry-project-endpoint>"),
    new DefaultAzureCredential())
        .AsAIAgent(
            model: "gpt-4o-mini",
            name: "Joker",
            instructions: "You are good at telling jokes.");

Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate."));

Peringatan

DefaultAzureCredential nyaman untuk pengembangan tetapi membutuhkan pertimbangan yang cermat dalam produksi. Dalam produksi, pertimbangkan untuk menggunakan kredensial tertentu (misalnya, ManagedIdentityCredential) untuk menghindari masalah latensi, pemeriksaan kredensial yang tidak diinginkan, dan potensi risiko keamanan dari mekanisme fallback.

Jalur ini bersifat code-first dan tidak membuat sumber daya agen yang dikelola oleh server.

Agen Foundry (versi terpisah)

Gunakan API asli AIProjectClient.AgentAdministrationClient dari AI Projects SDK untuk mengambil sumber daya agen versi, lalu membungkusnya dengan AsAIAgent. Agen dapat dibuat dan dikonfigurasi langsung di portal Foundry atau secara terprogram melalui AIProjectClient.AgentAdministrationClient.

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

var aiProjectClient = new AIProjectClient(
    new Uri("<your-foundry-project-endpoint>"),
    new DefaultAzureCredential());

// Retrieve an existing agent by name (uses the latest version automatically)
ProjectsAgentRecord jokerRecord = await aiProjectClient.AgentAdministrationClient.GetAgentAsync("Joker");
FoundryAgent agent = aiProjectClient.AsAIAgent(jokerRecord);

Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate."));

Penting

Alat-alat dan instruksi Agen Foundry hanya digunakan dengan alat dan instruksi yang sama saat dikembangkan; mencoba memodifikasi alat atau instruksi selama runtime tidak didukung.

Menggunakan agen

Baik ChatClientAgent (Respons) maupun FoundryAgent (versi) adalah instans standar AIAgent dan mendukung semua operasi standar termasuk sesi, alat, middleware, dan streaming.

AgentSession session = await agent.CreateSessionAsync();
Console.WriteLine(await agent.RunAsync("Tell me a joke.", session));
Console.WriteLine(await agent.RunAsync("Now make it funnier.", session));

Untuk informasi selengkapnya tentang cara menjalankan dan berinteraksi dengan agen, lihat tutorial Memulai Agen.

Tools

Agen Foundry yang dibuat dari AIProjectClient.AsAIAgent(...) (jalur Responses) mendukung cakupan alat standar Agent Framework — lihat gambaran umum Alat untuk daftar lengkap dan matriks fitur yang didukung. Untuk agen Foundry yang dimuat dari definisi agen berversi (FoundryAgent), alat agen tersebut dimiliki oleh definisi agen Foundry, bukan oleh klien.

Tool Catatan
Peralatan Fungsional Supported.
Persetujuan Alat Supported. Disediakan oleh klien obrolan yang memanggil fungsi kerangka kerja.
Penerjemah Kode Supported.
Pencarian File Supported.
Alat MCP yang Dihosting Supported.
Alat MCP Lokal Supported.
Kotak Alat Foundry Supported.

Kotak peralatan

Nota

Dokumentasi Foundry Toolbox .NET akan segera tersedia.

Pengeringan di Python

Di Python, semua klien khusus Foundry sekarang hidup di bawah agent_framework.foundry.

  • agent-framework-foundry menyediakan konektor Cloud Foundry: FoundryChatClient, FoundryAgent, FoundryEmbeddingClient, dan FoundryMemoryProvider.
  • agent-framework-foundry-local menyediakan FoundryLocalClient untuk eksekusi model lokal.

Penting

Halaman ini mencakup klien Python saat ini untuk titik akhir proyek Microsoft Foundry, titik akhir model, dan Foundry Agent Service. Jika Anda memiliki titik akhir sumber daya OpenAI Azure mandiri (https://<your-resource>.openai.azure.com), gunakan panduan Python di halaman penyedia OpenAI. Jika Anda ingin menjalankan model yang didukung secara lokal, lihat halaman Penyedia lokal Foundry.

Pola percakapan dan pola agen pada Foundry di Python

Skenario bentuk Python Gunakan ketika diperlukan
Inferensi biasa dengan titik akhir Respons Foundry Agent(client=FoundryChatClient(...)) Aplikasi Anda memiliki definisi agen, alat, dan perulangan percakapan, dan Anda ingin model disebarkan dalam proyek Foundry.
Agen yang dikelola layanan di Foundry Agent Service FoundryAgent(...) Anda ingin menyambungkan ke PromptAgent atau HostedAgent yang dibuat dan dikonfigurasi di portal Foundry atau melalui API layanan.

Penginstalan

pip install agent-framework-foundry
pip install azure-identity

Paket yang sama agent-framework-foundry juga termasuk FoundryEmbeddingClient untuk penyematan titik akhir model Foundry.

Konfigurasi

FoundryChatClient

FOUNDRY_PROJECT_ENDPOINT="https://<your-project>.services.ai.azure.com"
FOUNDRY_MODEL="gpt-4o-mini"

FoundryAgent

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 di-host dapat mengabaikannya.

FoundryEmbeddingClient

FOUNDRY_MODELS_ENDPOINT="https://<apim-instance>.azure-api.net/<foundry-instance>/models"
FOUNDRY_MODELS_API_KEY="<api-key>"
FOUNDRY_EMBEDDING_MODEL="text-embedding-3-small"
FOUNDRY_IMAGE_EMBEDDING_MODEL="Cohere-embed-v3-english"  # optional

FoundryChatClient dan FoundryAgent gunakan titik akhir proyek. FoundryEmbeddingClient menggunakan titik akhir model terpisah.

Pilih klien Python yang tepat

Skenario Klien pilihan Catatan
Azure Sumber Daya OpenAI OpenAIChatCompletionClient / OpenAIChatClient Gunakan halaman penyedia OpenAI.
inferensi proyek Microsoft Foundry Agent(client=FoundryChatClient(...)) Menggunakan titik akhir Respons Foundry.
agen yang dikelola oleh layanan Microsoft Foundry FoundryAgent Direkomendasikan untuk Prompt Agents dan HostedAgents.
penyematan titik akhir model Microsoft Foundry FoundryEmbeddingClient Menggunakan FOUNDRY_MODELS_ENDPOINT ditambah FOUNDRY_EMBEDDING_MODEL / FOUNDRY_IMAGE_EMBEDDING_MODEL.
Runtime Foundry Lokal Agent(client=FoundryLocalClient(...)) Lihat Foundry Local.

Membuat agen dengan FoundryChatClient

FoundryChatClient menyambungkan ke model yang diterapkan dalam proyek Foundry dan menggunakan endpoint respon. Pasangkan dengan standar Agent ketika aplikasi Anda harus memiliki instruksi, alat, dan penanganan sesi.

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential

agent = Agent(
    client=FoundryChatClient(
        project_endpoint="https://your-project.services.ai.azure.com",
        model="gpt-4o-mini",
        credential=AzureCliCredential(),
    ),
    name="FoundryWeatherAgent",
    instructions="You are a helpful assistant.",
)

FoundryChatClient adalah jalur Python Foundry-first untuk inferensi langsung dan mendukung alat, output terstruktur, dan streaming.

Tools

FoundryChatClient menyediakan metode pabrik statis untuk setiap alat Foundry yang dihosting. Metode factory mengembalikan objek alat SDK yang Anda teruskan ke tools= pada Agent atau langsung ke client.get_response(..., tools=[...]). Untuk FoundryAgent, alat agen hidup pada definisi agen Foundry itu sendiri — lihat Apa yang berfungsi dan apa yang tidak dengan FoundryAgent.

Metode pabrik merupakan metode kelas, jadi Anda tidak memerlukan instance untuk membuat tool:

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential

agent = Agent(
    client=FoundryChatClient(credential=AzureCliCredential()),
    instructions="You can search the web and run code.",
    tools=[
        FoundryChatClient.get_web_search_tool(),
        FoundryChatClient.get_code_interpreter_tool(),
    ],
)

Dukungan alat

Tabel di bawah ini mencantumkan setiap alat yang diekspos Python FoundryChatClient hari ini. FoundryAgent berfungsi dengan alat yang sama, tetapi alat tersebut harus dikonfigurasi pada definisi agen Foundry, bukan diteruskan melalui kode.

Tool Pabrik aktif FoundryChatClient Status Detail
Peralatan Fungsional n/a — teruskan objek Python apa pun yang dapat dipanggil atau @ai_function GA Dipanggil secara lokal dalam proses Python Anda.
Persetujuan Alat n/a — membungkus alat yang ada GA Bekerja dengan MCP yang dihosting dan alat fungsi.
Penerjemah Kode get_code_interpreter_tool GA Eksekusi kode dalam sandbox di Foundry.
Pencarian File get_file_search_tool GA Cari file yang diunggah melalui penyimpanan vektor Foundry.
Pencarian Web get_web_search_tool GA Landasan web berbasis Bing yang dikelola oleh Microsoft. Hanya model Azure OpenAI.
Pembuatan Gambar get_image_generation_tool GA Pembuatan gambar yang dihosting di Foundry.
MCP yang di-host get_mcp_tool GA Server MCP jarak jauh yang dipanggil oleh Foundry.
MCP lokal n/a — gunakan MCPStreamableHTTPTool / MCPStdioTool GA Berjalan di dalam proses Anda; kompatibel dengan klien apa pun.
Kotak Alat Foundry MCPStreamableHTTPTool ke titik akhir kotak alat MCP GA Dikonsumsi melalui MCP dari FoundryChatClient; sisi server terlampir pada FoundryAgent.
Bing Grounding get_bing_grounding_tool Experimental Bawa Grounding Anda sendiri dengan sumber daya Bing Search.
Bing Custom Search get_bing_custom_search_tool Preview Grounding Bing dibatasi untuk daftar domain yang dikumpulkan.
Pencarian Azure AI get_azure_ai_search_tool Experimental Cari indeks Pencarian Azure AI melalui koneksi Foundry.
SharePoint get_sharepoint_tool Preview Jawaban dasar dalam konten SharePoint.
Microsoft Fabric get_fabric_tool Preview Ajukan kueri ke agen data Fabric.
Pencarian Memori get_memory_search_tool Preview Cari penyimpanan memori yang dikelola Foundry.
Penggunaan Komputer get_computer_use_tool Preview Biarkan agen mendorong lingkungan desktop atau browser.
Automasi Browser get_browser_automation_tool Preview Mengendalikan browser melalui koneksi Azure Playwright.
Agen-ke-Agen (A2A) get_a2a_tool Preview Gunakan agen A2A lain sebagai alat.

Nota

Pabrik eksperimental membungkus jenis GA Foundry SDK tetapi pembungkus itu sendiri dapat berubah sebelum GA. Factory pratinjau membungkus tipe SDK Foundry yang kapabilitas dasarnya masih dalam tahap pratinjau dan dapat berubah atau dihapus. Keduanya menghasilkan ExperimentalWarning saat pertama kali digunakan dalam suatu proses.

Varian pencarian web

Foundry menyediakan tiga opsi grounding yang didukung oleh Bing. Pilih salah satu yang cocok dengan skenario Anda:

  • get_web_search_tool (GA) — default tanpa penyiapan; sumber daya Bing dikelola oleh Microsoft. Hanya model Azure OpenAI. Terbatas pada user_location dan search_context_size.
  • get_bing_grounding_tool (eksperimental) — bawa Grounding Anda sendiri dengan sumber daya Bing Search Azure. Mendukung count, freshness, market, set_lang, dan model non-OpenAI Foundry.
  • get_bing_custom_search_tool (pratinjau) — gunakan instans Bing Custom Search milik Anda sendiri untuk membatasi dasar respons ke kumpulan domain yang telah dikurasi.

Ketiganya mengirim data pencarian di luar batas kepatuhan Azure. Lihat gambaran umum grounding web untuk perbandingan lengkap.

client = FoundryChatClient(credential=AzureCliCredential())

# Default (GA): minimal configuration
web_search = client.get_web_search_tool(
    user_location={"city": "Amsterdam", "country": "NL"},
    search_context_size="medium",
)

Pembuatan gambar

get_image_generation_tool mengonfigurasi alat pembuatan gambar terhosting milik Foundry. Model menghasilkan konten gambar dalam respons - tidak ada file tambahan untuk dikelola.

image_gen = FoundryChatClient.get_image_generation_tool(
    model="gpt-image-1",
    size="1024x1024",
    output_format="png",
    quality="high",
)

Grounding dengan Bing

get_bing_grounding_tool membungkus Grounding dengan alat Bing Search Foundry. Anda membuat sumber daya Grounding dengan Bing Search sendiri dan menambahkannya sebagai koneksi proyek Foundry, lalu meneruskan ID koneksi.

bing = FoundryChatClient.get_bing_grounding_tool(
    connection_id="/subscriptions/.../connections/my-bing",
    market="en-US",
    freshness="Day",
    count=10,
)

get_bing_custom_search_tool membatasi landasan ke daftar izin yang ditentukan pada sumber daya Pencarian Kustom Bing.

bing_custom = FoundryChatClient.get_bing_custom_search_tool(
    connection_id="/subscriptions/.../connections/my-bing-custom",
    instance_name="docs-only",
    market="en-US",
)

get_azure_ai_search_tool memungkinkan agen mengkueri indeks Pencarian Azure AI melalui koneksi proyek Foundry.

ai_search = FoundryChatClient.get_azure_ai_search_tool(
    index_connection_id="/subscriptions/.../connections/my-search",
    index_name="product-docs",
    query_type="vector_semantic_hybrid",
    top_k=5,
)

Sharepoint

get_sharepoint_tool mendasarkan jawaban pada konten SharePoint yang dapat diakses melalui koneksi Foundry SharePoint.

sharepoint = FoundryChatClient.get_sharepoint_tool(
    connection_id="/subscriptions/.../connections/my-sharepoint",
)

Microsoft Fabric

get_fabric_tool menghubungkan agen ke agen data Microsoft Fabric melalui koneksi Foundry sehingga agen dapat menjawab pertanyaan atas data Fabric Anda.

fabric = FoundryChatClient.get_fabric_tool(
    connection_id="/subscriptions/.../connections/my-fabric",
)

get_memory_search_tool memungkinkan agen menelusuri penyimpanan memori yang dikelola Foundry, dengan cakupan opsional untuk pengguna atau tenant.

memory = FoundryChatClient.get_memory_search_tool(
    memory_store_name="user-preferences",
    scope="{{$userId}}",
)

Penggunaan komputer

get_computer_use_tool mengonfigurasi alat pratinjau Computer Use — model ini dapat mengendalikan lingkungan desktop atau browser dengan memberikan perintah pointer dan keyboard.

computer = FoundryChatClient.get_computer_use_tool(
    environment="browser",
    display_width=1280,
    display_height=800,
)

Automasi browser

get_browser_automation_tool menghubungkan agen ke sumber daya Pengujian Azure Playwright melalui koneksi Foundry. Agen dapat mengendalikan browser sungguhan dengan Playwright.

browser = FoundryChatClient.get_browser_automation_tool(
    connection_id="/subscriptions/.../connections/my-playwright",
)

Agen-ke-Agen (A2A)

get_a2a_tool mengekspos agen A2A jarak jauh sebagai alat agar agen Foundry dapat memanggilnya. Sediakan base_url (dan secara opsional agent_card_path) atau project_connection_id untuk koneksi A2A yang tersimpan.

a2a = FoundryChatClient.get_a2a_tool(
    base_url="https://remote-agent.example.com",
    agent_card_path="/.well-known/agent-card.json",
)

Untuk panduan A2A umum — penemuan, sesi, streaming — lihat halaman penyedia Agen-ke-Agen.

Buat penyematan dengan FoundryEmbeddingClient

Gunakan FoundryEmbeddingClient saat Anda menginginkan penyematan teks atau gambar dari titik akhir model Foundry.

from agent_framework.foundry import FoundryEmbeddingClient

async with FoundryEmbeddingClient() as client:
    result = await client.get_embeddings(["hello from Agent Framework"])
    print(result[0].dimensions)

Menghubungkan ke agen yang dikelola layanan dengan FoundryAgent

Gunakan FoundryAgent saat definisi agen berada di Foundry. Ini adalah API Python yang direkomendasikan untuk Prompt Agents dan HostedAgents.

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",
    agent_version="1.0",
    credential=AzureCliCredential(),
)

Untuk HostedAgent, hilangkan agent_version dan gunakan nama agen yang dihosting sebagai gantinya.

Apa yang berfungsi dan apa yang tidak dengan FoundryAgent

FoundryAgent menyambungkan ke agen yang sudah ada di Foundry (Prompt Agent atau Agen yang Dihosting). Definisi agen - instruksi dan konfigurasi alatnya - hidup di Foundry, bukan dalam kode Python Anda. Ini berarti beberapa fitur tingkat Agent berperilaku berbeda dibandingkan dengan fitur tersebut pada Agent(client=FoundryChatClient(...)) atau agen lain yang didukung oleh klien chat.

Tools

Jenis alat yang diteruskan ke FoundryAgent(...) Behavior
FunctionTool (objek Python lokal yang dapat dipanggil) Didukung, tetapi hanya jika definisi fungsi yang cocok sudah ada pada agen Foundry. Runtime Foundry memutuskan alat mana yang akan diekspos ke model berdasarkan definisi agen. Saat model memanggil fungsi, Foundry mengembalikan panggilan alat ke klien dan kerangka kerja memanggil Python lokal Anda yang dapat dipanggil dalam proses Anda (bukan di Foundry), lalu mengirim hasilnya kembali. Meneruskan FunctionTool di sisi klien hanya menyediakan implementasi lokal tersebut — jika fungsi itu tidak dideklarasikan pada agen Foundry, model tidak akan pernah memanggilnya.
Alat yang dihosting (pencarian web, penerjemah kode, pencarian file, MCP, pembuatan gambar, dll.) Diabaikan. Ini harus dikonfigurasi pada definisi agen Foundry itu sendiri, baik di portal Foundry atau melalui API layanan. Meneruskannya di sisi klien tidak menimbulkan efek apa pun karena runtime Foundry hanya mengenali tool yang dilampirkan ke definisi agen.

Singkatnya: Anda tidak dapat menambahkan alat baru pada waktu konstruksi. Setiap alat yang dapat dipanggil model — termasuk fungsi Python lokal — harus sudah menjadi bagian dari definisi agen di Foundry. Memberikan FunctionTool ke FoundryAgent(...) hanya menyediakan implementasi lokal yang berjalan di dalam proses Python Anda saat fungsi yang didefinisikan oleh Foundry dipanggil; hal tersebut tidak mendaftarkan tool baru pada agen.

Penyedia konteks

context_providers=[...] didukung sebagian. Apakah penyedia konteks berfungsi tergantung pada apa yang coba dilakukan penyedia:

Perilaku penyedia konteks Kompatibel dengan FoundryAgent?
Menambahkan konteks tambahan sebagai pesan (misalnya, memori yang diambil, cuplikan RAG, informasi profil pengguna) Yes. Konteks yang diinjeksikan diteruskan bersama permintaan.
Menyimpan secara persisten atau mengamati percakapan (misalnya, menulis giliran percakapan ke penyimpanan eksternal) Yes. Berjalan secara lokal pada siklus permintaan/respons.
Menambahkan alat secara dinamis (misalnya, SkillsProvider, atau penyedia apa pun yang mengembalikan alat dari invoking()) Tidak, kecuali alat-alat tersebut sudah menjadi bagian dari definisi agen Foundry itu. Runtime Foundry menjalankan model terhadap alat yang melekat pada agen di Foundry; alat yang hanya ada secara lokal tidak terekspos ke model dan tidak akan dipanggil.

Jika Anda memerlukan pemilihan alat secara dinamis, pemuatan skill, atau perilaku lain yang bergantung pada alat yang ditambahkan saat runtime, gunakan Agent(client=FoundryChatClient(...)) sebagai gantinya — jalur tersebut menangani loop model secara lokal dan mendukung seluruh jenis alat serta penyedia konteks untuk penambahan alat.

Jalankan opsi (default_options dan agent.run(...) opsi)

Opsi yang Anda berikan ke FoundryAgent(default_options=...) atau ke agent.run(..., **options) (seperti temperature, top_p, max_tokens, instructions, tool_choice, response_format, metadata, dll.) tidak semuanya diterapkan. Karena definisi agen dalam Foundry adalah sumber kebenaran, banyak opsi diabaikan secara diam-diam.

Untuk Prompt Agents, kerangka kerja secara eksplisit menghapus atau mengambil alih hal-hal berikut sebelum mengirim permintaan ke FOUNDRY Responses API:

Option Perilaku dengan FoundryAgent
model Diabaikan. Model diambil dari definisi agen Foundry.
tools, tool_choice, parallel_tool_calls Dihapus dari isi permintaan. Alat harus dideklarasikan pada definisi agen Foundry (lihat bagian sebelumnya). FunctionTool objek yang dapat dipanggil tetap dikonfigurasi secara lokal untuk pemanggilan fungsi, namun daftar alat itu sendiri tidak dikirim ke layanan.
instructions dan pesan sistem/pengembang Diabaikan. Instruksi agen Foundry sendiri bersifat otoritatif. Pesan sistem/pengembang dilucuti dari daftar pesan sebelum permintaan dikirim.
conversation_id Digunakan, dan dipetakan ke sesi agen Foundry saat merujuk ke salah satunya.
extra_body Diteruskan, digabungkan dengan payload yang ditetapkan oleh agent_reference framework.
Parameter pengambilan sampel (temperature, , top_p, max_tokens, seed, frequency_penaltypresence_penalty, stop... ), metadata, user, store, response_format, dll. Diteruskan ke API Respons. Apakah Foundry benar-benar menerapkannya bergantung pada konfigurasi agen dan model — definisi agen dapat mengesampingkan atau membatasinya — jadi jangan mengandalkan bahwa pengaturan tersebut akan diterapkan pada Prompt Agent.

Untuk Agen Terhosting, penghapusan di sisi klien yang sama juga berlaku, tetapi selebihnya bergantung pada apa yang diimplementasikan oleh agen terhosting tertentu. Agen yang dihosting dapat menerima, mengabaikan, atau menginterpretasikan ulang opsi apa pun yang diteruskan. Perlakukan opsi runtime hanya sebagai acuan dan verifikasi perilaku sebenarnya pada agen terhosting yang Anda panggil.

Tip

Jika Anda memerlukan kontrol yang presisi atas parameter generasi, instruksi, atau pemilihan alat untuk setiap eksekusi, konfigurasikan di definisi agen Foundry, atau beralih ke Agent(client=FoundryChatClient(...)), yang mematuhi ChatOptions secara menyeluruh.

Tip

Patokan praktis yang baik: jika sebuah fitur bergantung pada perubahan instruksi atau alat agen di setiap eksekusi, fitur tersebut sebaiknya ditempatkan di Agent(client=FoundryChatClient(...)). Jika definisi agen sudah ditetapkan di Foundry dan Anda hanya memerlukan pemanggilan fungsi lokal serta konteks pada tingkat pesan, FoundryAgent adalah pilihan yang tepat.

Menyambungkan ke agen Foundry yang telah diterapkan (dihosting)

Untuk HostedAgents yang menjalankan sesi sisi layanan (/agents/{name}/sessions), gunakan FoundryAgent dengan allow_preview=True untuk memilih ke permukaan Respons pratinjau:

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

agent = FoundryAgent(
    agent_name="my-hosted-agent",
    credential=AzureCliCredential(),
    allow_preview=True,
)

Ketika Anda perlu mengelola sendiri sesi layanan yang mendasar — misalnya untuk mengikat sesi ke penyewa atau pengguna tertentu — buat sesi melalui API pratinjau AIProjectClient dan bungkus dengan agent.get_session(...):

from azure.ai.projects.aio import AIProjectClient
from azure.ai.projects.models import VersionRefIndicator

service_session = await project_client.beta.agents.create_session(
    agent_name="my-hosted-agent",
    isolation_key="user-123",
    version_indicator=VersionRefIndicator(agent_version="1.0"),
)
session = agent.get_session(service_session.agent_session_id)

response = await agent.run("Hello!", session=session)

Tip

using_deployed_agent.py Lihat sampel untuk contoh lengkap, termasuk menyelesaikan versi terbaru secara otomatis.

Peringatan

Python AzureAIClient versi lama, AzureAIProjectAgentProvider, AzureAIAgentClient, AzureAIAgentsProvider, dan permukaan kompatibilitas embedding Azure AI telah dihapus dari namespace agent_framework.azure saat ini. Untuk kode Python saat ini, gunakan FoundryChatClient saat aplikasi Anda memiliki instruksi dan alat, FoundryAgent saat definisi agen berada di Foundry, dan FoundryEmbeddingClient untuk penyematan titik akhir model Foundry.

Menggunakan agen

Baik FoundryChatClient dan FoundryAgent terintegrasi dengan pengalaman standar Python Agent, termasuk panggilan alat, sesi, dan respons streaming. Untuk runtime lokal, gunakan halaman penyedia Foundry Local terpisah.

Kotak peralatan

Penting

API Kotak Alat bersifat eksperimental. Permukaan dapat berubah dalam rilis mendatang.

Kotak alat Foundry adalah bundel sisi server bernama versi konfigurasi alat yang dihosting (penerjemah kode, pencarian file, pembuatan gambar, MCP, pencarian web) yang dikonfigurasi dalam proyek Microsoft Foundry. Kotak alat memungkinkan Anda mengelola konfigurasi alat sekali di portal Foundry dan menggunakannya kembali di seluruh agen.

Agent Framework hanya mencakup pemakaian — pembuatan dan pembaruan versi kotak alat dilakukan melalui portal Foundry atau azure-ai-projects SDK mentah (azure-ai-projects>=2.1.0).

FoundryAgent vs FoundryChatClient

Jenis agen Perilaku kotak alat
FoundryAgent (dalam hosting) Lampiran kotak alat terjadi di sisi server. Tidak diperlukan kabel sisi klien.
FoundryChatClient (inferensi langsung) Ambil kotak alat dengan get_toolbox() dan berikan sebagai tools=.

Dua pola konsumsi

Pattern Deskripsi
Asli (alat yang dihosting) Konfigurasi alat dijalankan pada runtime Foundry. Berikan kotak alat langsung sebagai tools=.
MCP Gunakan MCPStreamableHTTPTool pada endpoint MCP dari kotak alat. Bekerja dengan klien obrolan apa pun, bukan hanya FoundryChatClient.

Mengambil kotak alat

Gunakan FoundryChatClient.get_toolbox() untuk mengambil kotak alat:

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity.aio import AzureCliCredential

async with AzureCliCredential() as credential:
    client = FoundryChatClient(credential=credential)
    toolbox = await client.get_toolbox("research_toolbox")

    async with Agent(client=client, name="ResearchAgent", tools=toolbox) as agent:
        result = await agent.run("Summarize recent findings.")
        print(result.text)

Ketika version dihilangkan, get_toolbox menyelesaikan versi default dalam dua permintaan. Sematkan versi tertentu untuk menghindari perjalanan bolak-balik tambahan:

toolbox = await client.get_toolbox("research_toolbox", version="v3")

Nota

Setiap get_toolbox() panggilan mencapai jaringan — tidak ada cache pada sisi kerangka kerja, karena versi default bisa berubah di sisi server. Cache dimiliki oleh pemanggil.

Meratakan implisit

Anda tidak perlu menulis toolbox.tools. Kerangka kerja normalize_tools mengenali ToolboxVersionObject dan meratakan secara otomatis. Semua ini berfungsi:

# Single toolbox
agent = Agent(client=client, tools=toolbox)

# Toolbox in a list
agent = Agent(client=client, tools=[toolbox])

# Mix local function tools with a toolbox
agent = Agent(client=client, tools=[get_internal_metrics, toolbox])

# Combine multiple toolboxes
agent = Agent(client=client, tools=[toolbox_a, toolbox_b])

Alat pemfilteran dengan select_toolbox_tools

Jika kotak alat Anda menggabungkan beberapa alat tetapi agen hanya memerlukan subset, gunakan select_toolbox_tools untuk mempersempit set setelah mengambil. Ini menghindari pengiriman definisi alat yang tidak perlu ke model, yang mengurangi penggunaan token dan mencegah model memanggil alat yang tidak ingin Anda ekspos:

from agent_framework.foundry import select_toolbox_tools, get_toolbox_tool_name

# Filter by tool name
tools = select_toolbox_tools(toolbox, include_names=["web_search", "code_interpreter"])

# Filter by tool type
tools = select_toolbox_tools(toolbox, include_types=["mcp", "web_search"])

# Filter with a custom predicate
tools = select_toolbox_tools(toolbox, predicate=lambda t: "search" in (get_toolbox_tool_name(t) or ""))

Fungsi pembantu get_toolbox_tool_name(tool) dan get_toolbox_tool_type(tool) mengembalikan nama pemilihan dan jenis mentah dari sebuah entri alat. FoundryHostedToolType adalah TypeAlias (Literal["code_interpreter", "file_search", "image_generation", "mcp", "web_search"] | str) untuk penyelesaian otomatis dipandu oleh IDE pada include_types / exclude_types.

Jalur konsumsi MCP

Anda juga dapat memanfaatkan kotak alat sebagai server MCP dengan mengarahkan MCPStreamableHTTPTool ke URL endpoint MCP kotak alat.

URL titik akhir MCP ditampilkan di Portal Foundry atau mengikuti format:

https://<account>.services.ai.azure.com/api/projects/<project>/toolsets/<name>/mcp?api-version=v1

Karena klien terhubung secara langsung ke endpoint kotak alat Foundry, Anda harus melakukan autentikasi menggunakan token pembawa Entra ID melalui header_provider:

from azure.identity.aio import DefaultAzureCredential
from azure.identity.aio import get_bearer_token_provider
from agent_framework import Agent, MCPStreamableHTTPTool

credential = DefaultAzureCredential()
token_provider = get_bearer_token_provider(credential, "https://ai.azure.com/.default")

mcp_tool = MCPStreamableHTTPTool(
    name="research_mcp",
    url="https://<your-toolbox-mcp-endpoint>",
    header_provider=lambda: {"Authorization": f"Bearer {token_provider()}"},
)

async with Agent(client=client, name="MCPAgent", tools=[mcp_tool]) as agent:
    result = await agent.run("Search for recent papers on LLM agents.")
    print(result.text)

Keterbatasan

  • Alat MCP di dalam kotak alat menggunakan autentikasi sisi server. Autentikasi ke server MCP upstream ditangani melalui project_connection_id (koneksi OAuth yang dikonfigurasi dalam proyek Foundry). Klien tidak pernah memegang token pembawa untuk server upstream.
  • Menggunakan toolbox sebagai server MCP memerlukan autentikasi pihak klien. Ketika Anda mengarahkan MCPStreamableHTTPTool ke titik akhir MCP kotak alat, Anda harus menyediakan Entra ID bearer token (token pembawa ID Entra) (misalnya, melalui get_bearer_token_provider(credential, "https://ai.azure.com/.default")) melalui header_provider.
  • Penanganan alur persetujuan adalah masalah runtime. Jika kotak alat MCP memicu CONSENT_REQUIRED selama agent.run(), hal ini ditangani pada waktu eksekusi, bukan selama pengambilan kotak alat.

Samples

Sample Deskripsi
foundry_chat_client_with_toolbox.py Pengambilan kotak alat dasar, penyematan versi, menggabungkan kotak alat, dan pemfilteran
foundry_chat_client_with_toolbox_mcp.py Jalur konsumsi MCP dengan MCPStreamableHTTPTool
foundry_toolbox_context_provider.py Pemilihan alat dinamis setiap giliran melalui penyedia konteks

Langkah berikutnya

Foundry Local

  • Last updated on