Mulai cepat: Membangun agen menggunakan API Respons

Dalam panduan singkat ini, Anda memanggil API Respons pada endpoint proyek Foundry dari kode Anda sendiri untuk membuat agen sementara — agen yang definisinya (instruksi, alat, model) ditentukan dalam kode aplikasi Anda alih-alih sebagai sumber daya persisten di Foundry Agent Service. Setiap panggilan membangun agen dalam proses Anda dan memanggil API Respons untuk inferensi model dan orkestrasi alat.

Pola ini cocok untuk pengembang, ISV, dan pelaku digital yang ingin definisi agen mereka dirilis dan dikelola versinya bersama bagian lain dari kode aplikasi mereka, alih-alih sebagai sumber daya terpisah yang harus terus diselaraskan secara manual dengan aplikasi. Tidak seperti agen prompt, tidak ada sumber daya agen di Foundry yang dapat dibuat, diperbarui, atau dihapus — manajemen siklus hidup digantikan dengan memanggil Responses API secara langsung.

API Responses merupakan satu-satunya titik masuk untuk model dan alat di Foundry. Anda dapat memanggilnya di dua titik akhir yang berbeda:

  • Titik akhir proyek Foundry (mulai cepat ini, direkomendasikan) — dukungan Foundry penuh. Menyediakan akses ke model Foundry dari katalog serta alat platform (pencarian file, interpreter kode, memori, pencarian web, MCP, SharePoint, WorkIQ, Fabric IQ, dan banyak lagi) melalui satu permukaan API tunggal yang dicakup per proyek, yang dapat diakses di {project_endpoint}/openai/v1/responses.
  • endpoint Azure OpenAI — latensi terbaik dan kompatibilitas maksimum dengan klien OpenAI yang sudah ada. Gunakan ini ketika Anda hanya memerlukan model OpenAI dan alat OpenAI standar dan tidak memerlukan kemampuan khusus Foundry.

Jalur yang direkomendasikan adalah Kerangka Kerja Agen, yang menangani autentikasi, kabel alat, dan orkestrasi pesan untuk Anda. Dalam Python ini FoundryChatClient; dalam .NET AIProjectClient.AsAIAgent(...). OpenAI SDK juga bekerja terhadap titik akhir ini dan dicakup sebagai alternatif dalam Menggunakan OpenAI SDK secara langsung.

Jika Anda tidak memiliki langganan Azure, buat akun gratis.

Kapan menggunakan pola agen sementara

Gunakan pola ini saat Anda menjalankan kode agen di luar Foundry — yang mungkin disematkan dalam aplikasi Anda sendiri — tetapi ingin mengakses fitur agen Foundry, seperti model dan alat platform.

Pola sementara dan agen yang dihosting bersifat aditif, bukan alternatif. Kode agen Agent Framework yang sama juga dapat dikemas sebagai agen yang dihosting dan diekspos melalui FOUNDRY Agents API — berguna ketika Anda ingin titik akhir yang dikelola Foundry yang dapat dipanggil oleh aplikasi, layanan, atau agen lain. Anda dapat melakukan keduanya dari satu basis kode: menjalankan agen dalam proses di mana agen dikirim dengan aplikasi Anda, dan menerbitkan definisi yang sama dengan agen yang dihosting di mana penelepon lain membutuhkannya.

Apa yang ditambahkan endpoint proyek Foundry ke OpenAI Responses API

API Responses pada endpoint proyek Foundry kompatibel dengan OpenAI Responses API, sehingga klien OpenAI yang ada dapat digunakan dengannya dengan sedikit perubahan. Titik akhir proyek Foundry menambahkan yang berikut ini di atas:

  • Data dalam cakupan proyek: Berkas, penyimpanan vektor, dan data lainnya disimpan di tingkat proyek, bukan di tingkat sumber daya, yang memberikan isolasi data per proyek dan memungkinkan Anda menggunakan sumber daya Anda sendiri melalui penyiapan agen standar.
  • Model Foundry selain OpenAI: Model Foundry yang dijual langsung oleh Azure (bukan hanya model OpenAI) tersedia melalui API yang sama.
  • Alat khusus Foundry: Alat platform seperti SharePoint, WorkIQ, dan Fabric IQ tersedia selain alat OpenAI standar.
  • Autentikasi atas nama (OBO) untuk alat: Alat dapat memanggil layanan hilir sebagai pengguna yang masuk, bukan hanya sebagai identitas aplikasi.
  • Observabilitas dan tata kelola tingkat proyek: Panggilan yang dibuat melalui endpoint proyek akan melewati pelacakan, pemantauan, filter konten, dan konfigurasi identitas proyek tanpa konfigurasi tambahan (lihat Observabilitas dan kapabilitas enterprise).

Memanggil titik akhir proyek — bukan titik akhir OpenAI tingkat sumber daya — adalah apa yang membuka kunci kemampuan cakupan proyek ini.

Prerequisites

  • Python 3.10 atau yang lebih baru terinstal.
  • .NET 8 SDK atau yang lebih baru telah terpasang.

Mengatur variabel lingkungan

Simpan titik akhir proyek Anda dan nama model yang disebarkan sebagai variabel lingkungan. Sampel di bawah ini membaca nilai-nilai ini dari lingkungan.

FOUNDRY_PROJECT_ENDPOINT=<endpoint copied from welcome screen>
FOUNDRY_MODEL=<your deployed model name>

Menginstalasi paket

Instal paket Agent Framework dengan penyedia Foundry:

pip install agent-framework-foundry aiohttp

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

Microsoft.Agents.AI.Foundry menyediakan metode ekstensi AsAIAgent(...) pada AIProjectClient dan secara transitif membawa Microsoft.Agents.AI.

Buat agen

Buat agen sementara yang berjalan secara lokal dalam proses Anda dan panggil API Respons untuk inferensi model dan orkestrasi alat.

Gunakan FoundryChatClient dan kelas Agent.

import asyncio
import os

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

async def main() -> None:
    agent = Agent(
        client=FoundryChatClient(
            project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
            model=os.environ["FOUNDRY_MODEL"],
            credential=AzureCliCredential(),
        ),
        instructions="You are a helpful assistant.",
    )

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

if __name__ == "__main__":
    asyncio.run(main())

Keluaran menampilkan tanggapan agen. Karena agen bersifat sementara, tidak ada definisi yang disimpan secara persisten di layanan — definisi tersebut hanya ada selama proses Python berlangsung.

Gunakan AIProjectClient.AsAIAgent(...) dari Kerangka Kerja Agen Microsoft untuk membungkus titik akhir proyek Foundry sebagai AIAgent.

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

string endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
string deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL")
    ?? throw new InvalidOperationException("FOUNDRY_MODEL is not set.");

AIAgent agent =
    new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
    .AsAIAgent(
        model: deploymentName,
        instructions: "You are a helpful assistant.",
        name: "Assistant");

Console.WriteLine($"Agent: {await agent.RunAsync("What is the capital of France?")}");

Keluaran menampilkan tanggapan agen. Karena agen bersifat sementara, tidak ada definisi yang disimpan secara persisten ke layanan — agen hanya ada selama proses tersebut berjalan.

Tambahkan alat fungsi

Definisikan tool fungsi lokal dan berikan kepada agen. Agen secara otomatis memanggil alat-alat ini saat diperlukan selama percakapan.

Definisikan alat fungsi lokal menggunakan dekorator @tool.

import asyncio
import os
from random import randint
from typing import Annotated

from agent_framework import Agent, tool
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential
from pydantic import Field

@tool(approval_mode="never_require")
def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
) -> str:
    """Get the weather for a given location."""
    conditions = ["sunny", "cloudy", "rainy", "stormy"]
    return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}°C."

async def main() -> None:
    agent = Agent(
        client=FoundryChatClient(
            project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
            model=os.environ["FOUNDRY_MODEL"],
            credential=AzureCliCredential(),
        ),
        instructions="You are a helpful weather agent.",
        tools=get_weather,
    )

    result = await agent.run("What's the weather like in Seattle?")
    print(f"Agent: {result}")

if __name__ == "__main__":
    asyncio.run(main())

Agen menggunakan Api Respons untuk menentukan kapan harus memanggil get_weather fungsi, menjalankannya secara lokal, dan mengembalikan hasilnya dalam bahasa alami.

Tentukan metode lokal, hiasi dengan [Description] atribut, dan bungkus dengan AIFunctionFactory.Create(...).

using System.ComponentModel;
using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

[Description("Get the weather for a given location.")]
static string GetWeather(
    [Description("The location to get the weather for.")] string location)
{
    string[] conditions = ["sunny", "cloudy", "rainy", "stormy"];
    Random rng = Random.Shared;
    return $"The weather in {location} is {conditions[rng.Next(conditions.Length)]} with a high of {rng.Next(10, 31)}°C.";
}

AITool weatherTool = AIFunctionFactory.Create(GetWeather);

string endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
string deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL")
    ?? throw new InvalidOperationException("FOUNDRY_MODEL is not set.");

AIAgent agent =
    new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
    .AsAIAgent(
        model: deploymentName,
        instructions: "You are a helpful weather agent.",
        name: "WeatherAssistant",
        tools: [weatherTool]);

Console.WriteLine($"Agent: {await agent.RunAsync("What's the weather like in Seattle?")}");

Agen menggunakan Api Respons untuk menentukan kapan harus memanggil GetWeather, menjalankannya secara lokal, dan mengembalikan hasilnya dalam bahasa alami.

Menggunakan alat pencarian web

API Respons pada titik akhir proyek Foundry menyediakan alat bawaan yang dihosting seperti pencarian web. Berikan agen Anda akses ke pencarian web tanpa implementasi lokal apa pun.

Gunakan FoundryChatClient.get_web_search_tool():

import asyncio
import os

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

async def main() -> None:
    agent = Agent(
        client=FoundryChatClient(
            project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
            model=os.environ["FOUNDRY_MODEL"],
            credential=AzureCliCredential(),
        ),
        instructions="You are a research assistant. Use web search to find current information.",
        tools=[
            FoundryChatClient.get_web_search_tool(),
        ],
    )

    result = await agent.run("What are the latest updates to Microsoft Foundry?")
    print(f"Agent: {result}")

if __name__ == "__main__":
    asyncio.run(main())

Alat pencarian web menjalankan sisi server melalui API Respons proyek Foundry. Anda dapat menggabungkannya dengan alat fungsi lokal untuk memberi agen Anda akses web dan kemampuan kode kustom:

agent = Agent(
    client=FoundryChatClient(
        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
        model=os.environ["FOUNDRY_MODEL"],
        credential=AzureCliCredential(),
    ),
    instructions="You are a helpful assistant with web and weather capabilities.",
    tools=[
        FoundryChatClient.get_web_search_tool(),
        get_weather,  # Local function tool defined with @tool
    ],
)

Teruskan new HostedWebSearchTool() dalam daftar tools:

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

string endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
string deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL")
    ?? throw new InvalidOperationException("FOUNDRY_MODEL is not set.");

AIAgent agent =
    new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
    .AsAIAgent(
        model: deploymentName,
        instructions: "You are a research assistant. Use web search to find current information.",
        name: "ResearchAssistant",
        tools: [new HostedWebSearchTool()]);

Console.WriteLine($"Agent: {await agent.RunAsync("What are the latest updates to Microsoft Foundry?")}");

Alat pencarian web menjalankan sisi server melalui API Respons proyek Foundry. Anda dapat menggabungkannya dengan alat fungsi lokal untuk memberi agen Anda akses web dan kemampuan kode kustom:

AIAgent agent =
    new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
    .AsAIAgent(
        model: deploymentName,
        instructions: "You are a helpful assistant with web and weather capabilities.",
        name: "Assistant",
        tools: [new HostedWebSearchTool(), weatherTool]);

Respons bertahap

Terima respons saat dihasilkan alih-alih menunggu pesan lengkap.

Gunakan parameter stream=True

import asyncio
import os

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

async def main() -> None:
    agent = Agent(
        client=FoundryChatClient(
            project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
            model=os.environ["FOUNDRY_MODEL"],
            credential=AzureCliCredential(),
        ),
        instructions="You are a helpful assistant.",
    )

    print("Agent: ", 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()

if __name__ == "__main__":
    asyncio.run(main())

Panggil RunStreamingAsync dan ulangi AgentResponseUpdate aliran:

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

string endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
string deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL")
    ?? throw new InvalidOperationException("FOUNDRY_MODEL is not set.");

AIAgent agent =
    new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
    .AsAIAgent(
        model: deploymentName,
        instructions: "You are a helpful assistant.",
        name: "Assistant");

Console.Write("Agent: ");
await foreach (AgentResponseUpdate update in agent.RunStreamingAsync("Tell me a fun fact."))
{
    Console.Write(update);
}
Console.WriteLine();

Output streaming ditampilkan secara bertahap di konsol saat model menghasilkan token demi token.

Kemampuan observabilitas dan perusahaan

Sementara tidak berarti tidak terkelola. Karena panggilan melalui titik akhir proyek, mereka mewarisi konfigurasi perusahaan proyek tanpa kabel tambahan:

  • Pelacakan dan pemantauan: Permintaan, pemanggilan alat, dan penggunaan token dialirkan ke observabilitas Foundry untuk proyek.
  • Filter konten dan tata kelola: Filter konten tingkat proyek dan kebijakan AI yang bertanggung jawab diterapkan pada setiap permintaan.
  • Identitas dan akses: Panggilan diautentikasi menggunakan konfigurasi identitas proyek; alat yang diaktifkan untuk OBO dapat bertindak sebagai pengguna yang sedang masuk.

Pola ephemeral bukan tingkatan dengan kapabilitas yang lebih rendah — Anda mendapatkan model, alat, observabilitas, dan tata kelola Foundry yang sama, baik saat Anda menjalankan agen dalam proses yang sama maupun mengemas kode yang sama sebagai agen yang dihosting. Pilihannya adalah tentang bentuk penyebaran, bukan set fitur.

Gunakan OpenAI SDK secara langsung

Karena API Respons proyek Foundry kompatibel dengan OpenAI, Anda juga dapat memanggilnya langsung dari OpenAI SDK dengan mengarahkan klien ke titik akhir proyek ({project_endpoint}/openai/v1/responses). Gunakan jalur ini hanya jika Anda sudah memiliki kode OpenAI SDK atau memerlukan kontrol tingkat yang lebih rendah atas bentuk permintaan dan respons. Kode baru sebaiknya menggunakan Agent Framework, yang menangani autentikasi, integrasi alat, dan orkestrasi untuk Anda.

Untuk sampel SDK, lihat:

sampel Respons Foundry (azure-ai-projects)

Azure. AI. Sampel OpenAI

Membersihkan sumber daya

Karena agen Agent Framework yang dibuat di sini bersifat ephemeral, tidak diperlukan pembersihan sisi layanan. Agen hanya ada dalam proses lokal Anda. Jika Anda membuat sumber daya Foundry yang tidak lagi Anda butuhkan, hapus di portal Foundry.

Konten terkait

Masuk lebih dalam pada pola ini

Mengemas kode agen yang sama dengan agen yang dihosting

  • Last updated on