penyedia model Microsoft Foundry

Microsoft Agent Framework mendukung inferensi model langsung dari titik akhir proyek Microsoft Foundry saat aplikasi Anda memiliki definisi, alat, dan orkestrasi agen.

Untuk Prompt yang dikelola layanan dan Agen yang Dihosting, lihat Microsoft Foundry Agent Service.

Getting Started

Tambahkan paket NuGet yang diperlukan ke proyek Anda.

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

Dua pola integrasi

Integrasi Microsoft Foundry mengekspos dua pola penggunaan yang berbeda:

Pattern Jenis yang diproduksi Description 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 (Prompt atau Hosted) FoundryAgent Dikelola server — Agen Prompt diberi nama dan definisi versi; Agen yang Dihosting adalah aplikasi yang disebarkan yang dicapai melalui titik akhir khusus agen. Foundry memiliki definisi agen atau runtime yang dihosting. Lihat Microsoft Foundry Agent Service.

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

Warning

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.

Menggunakan agen

Agen Respons adalah standar AIAgent dan mendukung 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 Respons Foundry yang dibuat dari AIProjectClient.AsAIAgent(...) mendukung permukaan alat Kerangka Kerja Agen standar. Lihat Gambaran umum Alat untuk matriks fitur lengkap.

Alat Notes
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 Microsoft Foundry Supported.

Foundry pada Python

Di Python, semua klien khusus Foundry sekarang tinggal 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.

Important

Halaman ini mencakup Microsoft titik akhir proyek dan model Foundry. Untuk Foundry Agent Service, lihat Microsoft Foundry Agent Service. Jika Anda memiliki titik akhir sumber daya Azure OpenAI 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 dalam 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

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

Configuration

FoundryChatClient

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

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 menggunakan titik akhir proyek. FoundryEmbeddingClient menggunakan titik akhir model terpisah.

Pilih klien Python yang tepat

Skenario Klien pilihan Notes
Sumber daya Azure 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 alat agen yang dikelola layanan, lihat Microsoft Foundry Agent Service.

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.

Alat Pabrik aktif FoundryChatClient Status Detil
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 Microsoft Foundry MCPStreamableHTTPTool atau FoundryToolbox Beta 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.
Pencarian Kustom Bing 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 penemuan, sesi, dan panduan streaming A2A umum, lihat layanan agen A2A.

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)

Menggunakan agen

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

Untuk bundel konfigurasi alat yang dihosting dengan versi bernama, lihat Microsoft Foundry Toolbox.

Foundry in Go

Go SDK menyediakan agen Microsoft Foundry melalui github.com/microsoft/agent-framework-go/provider/foundryprovider.

Lihat sampel Foundry Go untuk inferensi langsung, alat fungsi, alat yang dihosting, MCP, dan contoh agen server.

Paket ini mendukung dua target agen:

Target Buka Bentuk Gunakan ketika diperlukan
Penerapan model yang didukung proyek foundryprovider.ModelDeployment("gpt-4o-mini") Aplikasi Anda memiliki instruksi, alat, dan alur percakapan.
Agen Foundry di sisi server yang ada foundryprovider.ServerAgent("my-agent") Definisi agen sudah dikonfigurasi di Foundry.

Configuration

Atur titik akhir proyek Foundry dan penyebaran model Anda:

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

Agen Foundry yang didukung oleh proyek

Gunakan ModelDeployment saat Anda ingin membuat agen Agent Framework dalam kode dan meneruskan instruksi, alat, middleware, dan penyedia konteks dari aplikasi Go Anda.

import (
    "context"
    "os"

    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
    "github.com/microsoft/agent-framework-go/agent"
    "github.com/microsoft/agent-framework-go/provider/foundryprovider"
)

endpoint := os.Getenv("FOUNDRY_PROJECT_ENDPOINT")
model := os.Getenv("FOUNDRY_MODEL")

token, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
    panic(err)
}

a := foundryprovider.NewAgent(
    endpoint,
    token,
    foundryprovider.ModelDeployment(model),
    foundryprovider.AgentConfig{
        Instructions: "You are good at telling jokes.",
        Config: agent.Config{
            Name: "Joker",
        },
    },
)

resp, err := a.RunText(context.Background(), "Tell me a joke about a pirate.").Collect()

Agen Foundry di sisi server yang ada

Gunakan ServerAgent saat Anda ingin memanggil agen yang sudah dikonfigurasi di Foundry. Agen sisi server memiliki instruksi dan alatnya, sehingga AgentConfig.Instructions diabaikan untuk target ini.

a := foundryprovider.NewAgent(
    endpoint,
    token,
    foundryprovider.ServerAgent("my-agent"),
    foundryprovider.AgentConfig{
        Config: agent.Config{
            Name: "my-agent",
        },
    },
)

resp, err := a.RunText(ctx, "Summarize the current project status.").Collect()

Tools

Agen Foundry yang didukung proyek mendukung antarmuka alat standar Go Agent Framework untuk alat lokal dan deklarasi alat terhosting yang didukung.

Alat Status Notes
Peralatan Fungsional Dukungan Fungsi berjalan di dalam proses Go Anda.
Persetujuan Alat Dukungan Bekerja dengan alat fungsi lokal melalui perulangan panggilan otomatis alat.
Penerjemah Kode Dukungan Gunakan &hostedtool.CodeInterpreter{}.
Pencarian Web Dukungan Gunakan &hostedtool.WebSearch{}.
Alat MCP Lokal Dukungan Gunakan tool/mcptool untuk menyambungkan ke server MCP dan mengekspos alatnya secara lokal.
Alat MCP yang Dihosting Saat ini belum didokumentasikan untuk Go Foundry Gunakan alat MCP lokal saat Anda memerlukan server MCP dengan agen Go Foundry.
Kotak Alat Microsoft Foundry Saat ini tidak terekspos melalui pembantu Go.

Untuk alat fungsi lokal, tambahkan nilai tool.Tool hingga agent.Config.Tools:

a := foundryprovider.NewAgent(
    endpoint,
    token,
    foundryprovider.ModelDeployment(model),
    foundryprovider.AgentConfig{
        Instructions: "You are a helpful assistant.",
        Config: agent.Config{
            Tools: []tool.Tool{weatherTool},
        },
    },
)

Untuk eksekusi kode yang dihosting, berikan deklarasi alat yang dihosting:

a := foundryprovider.NewAgent(
    endpoint,
    token,
    foundryprovider.ModelDeployment(model),
    foundryprovider.AgentConfig{
        Instructions: "You solve problems with code.",
        Config: agent.Config{
            Tools: []tool.Tool{&hostedtool.CodeInterpreter{}},
        },
    },
)

Header klien dan model yang dilayani

Foundry menerima header x-client-* dalam setiap eksekusi. Tambahkan dengan foundryprovider.WithClientHeader atau foundryprovider.WithClientHeaders:

resp, err := a.RunText(
    ctx,
    "Hello!",
    foundryprovider.WithClientHeader("x-client-scenario", "docs"),
).Collect()

Saat Foundry mengembalikan header respons x-ms-served-model, penyedia Go menambahkannya ke properti tambahan respons/pembaruan sebagai ServedModel.

if servedModel, ok := resp.AdditionalProperties["ServedModel"].(string); ok {
    fmt.Println(servedModel)
}

Penyedia memori untuk foundry

Gunakan foundryprovider.NewMemoryProvider saat Anda ingin agen Agent Framework mengambil data dari dan memperbarui penyimpanan memori yang dikelola Foundry pada setiap eksekusi.

import (
    "log/slog"

    "github.com/microsoft/agent-framework-go/agent"
    "github.com/microsoft/agent-framework-go/provider/foundryprovider"
)

memoryProvider := foundryprovider.NewMemoryProvider(
    endpoint,
    tokenCredential,
    "memory-store-sample",
    func(*agent.Session) string { return "user-123" },
    foundryprovider.MemoryProviderConfig{
        Logger: slog.Default(),
    },
)

a := foundryprovider.NewAgent(
    endpoint,
    tokenCredential,
    foundryprovider.ModelDeployment(model),
    foundryprovider.AgentConfig{
        Instructions: "Use known memories about the user when responding.",
        Config: agent.Config{
            Name:             "FoundryMemoryAgent",
            ContextProviders: []agent.ContextProvider{memoryProvider},
        },
    },
)

Titik akhir harus berupa titik akhir Microsoft Foundry yang dilingkup proyek, dan penyimpanan memori harus sudah ada dalam proyek tersebut. Panggilan balik cakupan harus mengembalikan kunci partisi pengguna, penyewa, atau percakapan yang stabil.

Tip

Lihat sampel Foundry memory Go untuk contoh lengkap yang dapat dijalankan.

Kekurangan Go Saat Ini

Dukungan Go saat ini tidak menyertakan API penyebaran/siklus hidup/admin yang dihosting Foundry, klien penyematan, atau pembantu khusus Go untuk Microsoft Foundry Toolbox. Gunakan portal Foundry atau SDK layanan untuk operasi tersebut.

Langkah berikutnya

Foundry Local

  • Last updated on