Agen Microsoft Foundry

Microsoft Agent Framework mendukung pembuatan agen yang menggunakan Foundry Agent Service. Anda dapat membuat instans agen berbasis layanan persisten dengan riwayat obrolan yang dikelola layanan.

Memulai Langkah Awal

Tambahkan paket NuGet yang diperlukan ke proyek Anda.

dotnet add package Azure.Identity
dotnet add package Microsoft.Agents.AI.AzureAI.Persistent --prerelease

Membuat Agen Foundry

Sebagai langkah pertama, Anda perlu membuat klien untuk terhubung ke Layanan Agen.

using System;
using Azure.AI.Agents.Persistent;
using Azure.Identity;
using Microsoft.Agents.AI;

var persistentAgentsClient = new PersistentAgentsClient(
    "https://<myresource>.services.ai.azure.com/api/projects/<myproject>",
    new DefaultAzureCredential());

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.

Untuk menggunakan Layanan Agen, Anda perlu membuat sumber daya agen dalam layanan. Ini dapat dilakukan menggunakan Azure.AI.Agents.Persistent SDK atau menggunakan pembantu Microsoft Agent Framework.

Menggunakan SDK Persisten

Buat agen persisten dan memerolehnya sebagai AIAgent dengan menggunakan PersistentAgentsClient.

// Create a persistent agent
var agentMetadata = await persistentAgentsClient.Administration.CreateAgentAsync(
    model: "gpt-4o-mini",
    name: "Joker",
    instructions: "You are good at telling jokes.");

// Retrieve the agent that was just created as an AIAgent using its ID
AIAgent agent1 = await persistentAgentsClient.GetAIAgentAsync(agentMetadata.Value.Id);

// Invoke the agent and output the text result.
Console.WriteLine(await agent1.RunAsync("Tell me a joke about a pirate."));

Menggunakan fungsi bantu Agent Framework

Anda juga dapat membuat dan mengembalikan AIAgent dalam satu langkah:

AIAgent agent2 = await persistentAgentsClient.CreateAIAgentAsync(
    model: "gpt-4o-mini",
    name: "Joker",
    instructions: "You are good at telling jokes.");

Penggunaan Kembali Agen Foundry

Anda dapat menggunakan kembali Agen Foundry yang ada dengan mengambilnya menggunakan ID unik mereka.

AIAgent agent3 = await persistentAgentsClient.GetAIAgentAsync("<agent-id>");

Petunjuk / Saran

Lihat sampel .NET untuk contoh lengkap yang dapat dijalankan.

Menggunakan agen

Agen adalah standar AIAgent dan mendukung semua operasi standar AIAgent .

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

Konfigurasi

Variabel Lingkungan

Sebelum menggunakan Agen Foundry, Anda perlu menyiapkan variabel lingkungan ini:

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

Atau, Anda dapat memberikan nilai-nilai ini langsung dalam kode Anda.

Penginstalan

Tambahkan paket Agent Framework Azure AI ke proyek Anda:

pip install agent-framework-azure-ai --pre

Memulai Langkah Awal

Authentication

Agen Foundry menggunakan kredensial Azure untuk autentikasi. Pendekatan paling sederhana adalah menggunakan AzureCliCredential setelah menjalankan az login. Semua klien Azure AI menerima parameter terpadu credential yang mendukung TokenCredential, AsyncTokenCredential atau penyedia token yang dapat dipanggil — penyimpanan cache dan refresh token ditangani secara otomatis.

from azure.identity.aio import AzureCliCredential

async with AzureCliCredential() as credential:
    # Use credential with Azure AI agent client

Membuat Agen Foundry

Pembuatan Agen Dasar

Foundry Agent Service v1

Cara paling sederhana untuk membuat agen adalah menggunakan AzureAIAgentClient dengan variabel lingkungan:

import asyncio
from agent_framework.azure import AzureAIAgentClient
from azure.identity.aio import AzureCliCredential

async def main():
    async with (
        AzureCliCredential() as credential,
        AzureAIAgentClient(credential=credential).as_agent(
            name="HelperAgent",
            instructions="You are a helpful assistant."
        ) as agent,
    ):
        result = await agent.run("Hello!")
        print(result.text)

asyncio.run(main())

Foundry Agent Service v2

Cara paling sederhana untuk membuat agen adalah menggunakan AzureAIClient dengan variabel lingkungan:

import asyncio
from agent_framework.azure import AzureAIClient
from azure.identity.aio import AzureCliCredential

async def main():
    async with (
        AzureCliCredential() as credential,
        AzureAIClient(credential=credential).as_agent(
            name="HelperAgent",
            instructions="You are a helpful assistant."
        ) as agent,
    ):
        result = await agent.run("Hello!")
        print(result.text)

asyncio.run(main())

Konfigurasi Eksplisit

Foundry Agent Service v1

Anda juga dapat menyediakan konfigurasi secara eksplisit alih-alih menggunakan variabel lingkungan:

import asyncio
from agent_framework.azure import AzureAIAgentClient
from azure.identity.aio import AzureCliCredential

async def main():
    async with (
        AzureCliCredential() as credential,
        AzureAIAgentClient(
            project_endpoint="https://<your-project>.services.ai.azure.com/api/projects/<project-id>",
            model_deployment_name="gpt-4o-mini",
            credential=credential,
            agent_name="HelperAgent"
        ).as_agent(
            instructions="You are a helpful assistant."
        ) as agent,
    ):
        result = await agent.run("Hello!")
        print(result.text)

asyncio.run(main())

Foundry Agent Service v2

Anda juga dapat menyediakan konfigurasi secara eksplisit alih-alih menggunakan variabel lingkungan:

import asyncio
from agent_framework.azure import AzureAIClient
from azure.ai.projects.aio import AIProjectClient
from azure.identity.aio import AzureCliCredential

async def main():
    async with (
        AzureCliCredential() as credential,
        AIProjectClient(
            endpoint="https://<your-project>.services.ai.azure.com/api/projects/<project-id>",
            credential=credential
        ) as project_client,
        AzureAIClient(
            project_client=project_client,
            model_deployment_name="gpt-4o-mini",
        ).as_agent(
            name="HelperAgent",
            instructions="You are a helpful assistant."
        ) as agent,
    ):
        result = await agent.run("Hello!")
        print(result.text)

asyncio.run(main())

Menggunakan Agen Foundry yang Ada

Menggunakan Agen yang Sudah Ada

Foundry Agent Service v1

Jika Anda memiliki agen yang sudah ada di Foundry, Anda dapat menggunakannya dengan memberikan ID-nya:

import asyncio
from agent_framework import Agent
from agent_framework.azure import AzureAIAgentClient
from azure.identity.aio import AzureCliCredential

async def main():
    async with (
        AzureCliCredential() as credential,
        Agent(
            chat_client=AzureAIAgentClient(
                credential=credential,
                agent_id="<existing-agent-id>"
            ),
            instructions="You are a helpful assistant."
        ) as agent,
    ):
        result = await agent.run("Hello!")
        print(result.text)

asyncio.run(main())

Foundry Agent Service v2

Jika Anda memiliki agen yang sudah ada di Foundry, Anda dapat mengambilnya berdasarkan nama menggunakan penyedia agen proyek:

import asyncio
import os
from agent_framework.azure import AzureAIProjectAgentProvider
from azure.ai.projects.aio import AIProjectClient
from azure.identity.aio import AzureCliCredential

async def main():
    async with (
        AzureCliCredential() as credential,
        AIProjectClient(
            endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
            credential=credential
        ) as project_client,
    ):
        provider = AzureAIProjectAgentProvider(project_client=project_client)
        agent = await provider.get_agent(name="<existing-agent-name>")

        result = await agent.run("Hello!")
        print(result)

asyncio.run(main())

Membuat dan Mengelola Agen Persisten

Foundry Agent Service v1

Untuk kontrol lebih besar atas siklus hidup agen, Anda dapat membuat agen persisten menggunakan klien Azure AI Projects:

import asyncio
import os
from agent_framework import Agent
from agent_framework.azure import AzureAIAgentClient
from azure.ai.projects.aio import AIProjectClient
from azure.identity.aio import AzureCliCredential

async def main():
    async with (
        AzureCliCredential() as credential,
        AIProjectClient(
            endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
            credential=credential
        ) as project_client,
    ):
        # Create a persistent agent
        created_agent = await project_client.agents.create_agent(
            model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
            name="PersistentAgent",
            instructions="You are a helpful assistant."
        )

        try:
            # Use the agent
            async with Agent(
                chat_client=AzureAIAgentClient(
                    project_client=project_client,
                    agent_id=created_agent.id
                ),
                instructions="You are a helpful assistant."
            ) as agent:
                result = await agent.run("Hello!")
                print(result.text)
        finally:
            # Clean up the agent
            await project_client.agents.delete_agent(created_agent.id)

asyncio.run(main())

Foundry Agent Service v2

Untuk kontrol lebih besar atas siklus hidup agen, Anda dapat membuat agen persisten menggunakan klien Azure AI Projects:

import asyncio
import os
from agent_framework.azure import AzureAIProjectAgentProvider
from azure.ai.projects.aio import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition
from azure.identity.aio import AzureCliCredential

async def main():
    async with (
        AzureCliCredential() as credential,
        AIProjectClient(
            endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
            credential=credential
        ) as project_client,
    ):
        # Create a persistent agent
        created_agent = await project_client.agents.create_version(
            agent_name="PersistentAgent",
            definition=PromptAgentDefinition(
                model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
                instructions="You are a helpful assistant."
            ),
        )

        try:
            # Use the agent
            provider = AzureAIProjectAgentProvider(project_client=project_client)
            agent = provider.as_agent(created_agent)

            result = await agent.run("Hello!")
            print(result)
        finally:
            # Clean up the agent
            await project_client.agents.delete_version(
                agent_name=created_agent.name,
                agent_version=created_agent.version
            )

asyncio.run(main())

Fitur Agen

Opsi Pengaturan Penalaran dan Pemfilteran Konten

Saat membuat agen melalui penyedia proyek Azure AI, Anda dapat mengatur default_options untuk mengaktifkan penalaran model dan pemfilteran konten AI yang bertanggung jawab.

Gunakan reasoning untuk model berkemampuan penalaran:

from agent_framework.azure import AzureAIProjectAgentProvider
from azure.ai.projects.models import Reasoning
from azure.identity.aio import AzureCliCredential
    async with (
        AzureCliCredential() as credential,
        AzureAIProjectAgentProvider(credential=credential) as provider,
    ):
        agent = await provider.create_agent(
    async with (
        AzureCliCredential() as credential,
        AzureAIProjectAgentProvider(credential=credential) as provider,
    ):
        agent = await provider.create_agent(

Gunakan rai_config untuk menerapkan kebijakan RAI yang dikonfigurasi:

from azure.ai.projects.models import RaiConfig
from azure.identity.aio import AzureCliCredential
async def main() -> None:
    print("=== Azure AI Agent with Content Filtering ===\n")

    # Replace with your RAI policy from Azure AI Foundry portal
    rai_policy_name = (
        "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/"
        "Microsoft.CognitiveServices/accounts/{accountName}/raiPolicies/{policyName}"
    )

    async with (
        AzureCliCredential() as credential,
        AzureAIProjectAgentProvider(credential=credential) as provider,
    ):
        # Create agent with content filtering enabled via default_options
        agent = await provider.create_agent(

Perangkat Fungsional

Foundry Agent Service v1

Anda dapat menyediakan alat fungsi kustom untuk agen Foundry:

import asyncio
from typing import Annotated
from agent_framework.azure import AzureAIAgentClient
from azure.identity.aio import AzureCliCredential
from pydantic import Field

def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
) -> str:
    """Get the weather for a given location."""
    return f"The weather in {location} is sunny with a high of 25°C."

async def main():
    async with (
        AzureCliCredential() as credential,
        AzureAIAgentClient(credential=credential).as_agent(
            name="WeatherAgent",
            instructions="You are a helpful weather assistant.",
            tools=get_weather
        ) as agent,
    ):
        result = await agent.run("What's the weather like in Seattle?")
        print(result.text)

asyncio.run(main())

Foundry Agent Service v2

Anda dapat menyediakan alat fungsi kustom untuk agen Foundry:

import asyncio
from typing import Annotated
from agent_framework.azure import AzureAIClient
from azure.identity.aio import AzureCliCredential
from pydantic import Field

def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
) -> str:
    """Get the weather for a given location."""
    return f"The weather in {location} is sunny with a high of 25°C."

async def main():
    async with (
        AzureCliCredential() as credential,
        AzureAIClient(credential=credential).as_agent(
            name="WeatherAgent",
            instructions="You are a helpful weather assistant.",
            tools=get_weather
        ) as agent,
    ):
        result = await agent.run("What's the weather like in Seattle?")
        print(result.text)

asyncio.run(main())

Penerjemah Kode

Foundry Agent Service v1

Agen Foundry mendukung eksekusi kode melalui penerjemah kode yang dihosting:

import asyncio
from agent_framework.azure import AzureAIAgentClient
from azure.identity.aio import AzureCliCredential

async def main():
    async with (
        AzureCliCredential() as credential,
        AzureAIAgentClient(credential=credential) as client,
        client.as_agent(
            name="CodingAgent",
            instructions="You are a helpful assistant that can write and execute Python code.",
            tools=client.get_code_interpreter_tool(),
        ) as agent,
    ):
        result = await agent.run("Calculate the factorial of 20 using Python code.")
        print(result.text)

asyncio.run(main())

Foundry Agent Service v2

Agen Foundry mendukung eksekusi kode melalui penerjemah kode yang dihosting:

import asyncio
from agent_framework.azure import AzureAIClient
from azure.identity.aio import AzureCliCredential

async def main():
    async with (
        AzureCliCredential() as credential,
        AzureAIClient(credential=credential) as client,
        client.as_agent(
            name="CodingAgent",
            instructions="You are a helpful assistant that can write and execute Python code.",
            tools=client.get_code_interpreter_tool(),
        ) as agent,
    ):
        result = await agent.run("Calculate the factorial of 20 using Python code.")
        print(result.text)

asyncio.run(main())

Respons yang Mengalir

Foundry Agent Service v1

Dapatkan respons seiring dengan proses pemrosesan menggunakan streaming:

import asyncio
from agent_framework.azure import AzureAIAgentClient
from azure.identity.aio import AzureCliCredential

async def main():
    async with (
        AzureCliCredential() as credential,
        AzureAIAgentClient(credential=credential).as_agent(
            name="StreamingAgent",
            instructions="You are a helpful assistant."
        ) as agent,
    ):
        print("Agent: ", end="", flush=True)
        async for chunk in agent.run("Tell me a short story", stream=True):
            if chunk.text:
                print(chunk.text, end="", flush=True)
        print()

asyncio.run(main())

Foundry Agent Service v2

Dapatkan respons seiring dengan proses pemrosesan menggunakan streaming:

import asyncio
from agent_framework.azure import AzureAIClient
from azure.identity.aio import AzureCliCredential

async def main():
    async with (
        AzureCliCredential() as credential,
        AzureAIClient(credential=credential).as_agent(
            name="StreamingAgent",
            instructions="You are a helpful assistant."
        ) as agent,
    ):
        print("Agent: ", end="", flush=True)
        async for chunk in agent.run("Tell me a short story", stream=True):
            if chunk.text:
                print(chunk.text, end="", flush=True)
        print()

asyncio.run(main())

Menggunakan Agen

Agen ini adalah BaseAgent standar dan mendukung semua operasi agen standar.

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

Langkah berikutnya

Model Foundry berbasis Agen