Microsoft Foundry Aracıları

Microsoft Agent Framework , Foundry Agent Hizmeti'ni kullanan aracılar oluşturmayı destekler. Hizmet tarafından yönetilen sohbet geçmişiyle kalıcı hizmet tabanlı aracı örnekleri oluşturabilirsiniz.

Başlangıç Yapmak

Projenize gerekli NuGet paketlerini ekleyin.

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

Döküm Aracıları Oluşturma

İlk adım olarak Aracı Hizmetine bağlanmak için bir istemci oluşturmanız gerekir.

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());

Uyarı

DefaultAzureCredential geliştirme için uygundur ancak üretimde dikkatli bir şekilde dikkate alınması gerekir. Üretimde gecikme sorunları, istenmeyen kimlik bilgisi yoklama ve geri dönüş mekanizmalarından kaynaklanan olası güvenlik risklerini önlemek için belirli bir kimlik bilgisi (ör ManagedIdentityCredential. ) kullanmayı göz önünde bulundurun.

Aracı Hizmeti'ni kullanmak için hizmette bir aracı kaynağı oluşturmanız gerekir. Bu, Azure.AI.Agents.Persistent SDK'sı veya Microsoft Agent Framework yardımcıları kullanılarak yapılabilir.

Kalıcı SDK kullanma

Kalıcı bir ajan oluşturun ve bunu AIAgent kullanarak PersistentAgentsClient olarak alın.

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

Agent Framework yardımcılarını kullanma

Ayrıca AIAgent'yi tek bir adımda oluşturup döndürebilirsiniz.

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

Döküm Temsilcilerini Yeniden Kullanma

Mevcut Foundry Ajanlarını, ID'lerini kullanarak yeniden kullanabilirsiniz.

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

Tavsiye

Çalıştırılabilir örneklerin tamamı için .NET örneklerine bakın.

Aracıyı kullanma

Aracı, standart bir AIAgent'dir ve tüm standart AIAgent işlemlerini destekler.

Aracıları çalıştırma ve aracılarla etkileşim kurma hakkında daha fazla bilgi için bkz. Aracı kullanmaya başlama öğreticileri.

Konfigürasyon

Ortam Değişkenleri

Foundry Aracılarını kullanmadan önce şu ortam değişkenlerini ayarlamanız gerekir:

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"

Alternatif olarak, bu değerleri doğrudan kodunuzda sağlayabilirsiniz.

Installation

Projenize Agent Framework Azure AI paketini ekleyin:

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

Başlangıç Yapmak

Kimlik Doğrulaması

Döküm aracıları kimlik doğrulaması için Azure kimlik bilgilerini kullanır. En basit yaklaşım, AzureCliCredential çalıştırdıktan sonra az login kullanmaktır. Tüm Azure AI istemcileri, birleşik bir credential parametresini kabul eder; bu parametre TokenCredential, AsyncTokenCredential veya çağrılabilir bir belirteç sağlayıcısını destekler. Belirteç önbelleğe alma ve yenileme işlemleri otomatik olarak gerçekleştirilir.

from azure.identity.aio import AzureCliCredential

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

Döküm Aracıları Oluşturma

Temel Ajan Oluşturma

Döküm Aracı Hizmeti v1

Aracı oluşturmanın en basit yolu, ortam değişkenleriyle kullanmaktır AzureAIAgentClient :

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 Servisi v2

Aracı oluşturmanın en basit yolu, ortam değişkenleriyle kullanmaktır AzureAIClient :

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())

Açık Yapılandırma

Foundry Temsilci Hizmeti v1

Ortam değişkenlerini kullanmak yerine açıkça yapılandırma da sağlayabilirsiniz:

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())

Döküm Ajan Hizmeti v2

Ortam değişkenlerini kullanmak yerine açıkça yapılandırma da sağlayabilirsiniz:

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())

Mevcut Dökümhane Ajanlarını Kullanma

Mevcut Temsilciyi Kullanma

Döküm Ajan Hizmeti v1

Foundry'de mevcut bir aracınız varsa, ID'sini sağlayarak kullanabilirsiniz.

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 Hizmeti v2

Foundry'de mevcut bir aracınız varsa, proje aracı sağlayıcısını kullanarak aracıyı ada göre alabilirsiniz.

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())

Kalıcı Aracılar Oluşturma ve Yönetme

Foundry Agent Hizmeti v1

Aracı yaşam döngüsü üzerinde daha fazla denetim için Azure AI Projeleri istemcisini kullanarak kalıcı aracılar oluşturabilirsiniz:

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())

Döküm Ajans Hizmeti v2

Aracı yaşam döngüsü üzerinde daha fazla denetim için Azure AI Projeleri istemcisini kullanarak kalıcı aracılar oluşturabilirsiniz:

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())

Temsilci Özellikleri

Akıl yürütme ve içerik filtreleme seçenekleri

Azure AI proje sağlayıcıları aracılığıyla ajan oluştururken, model akıl yürütmeyi ve sorumlu yapay zeka içerik filtrelemesini etkinleştirecek şekilde ayarlayabilirsiniz default_options.

Akıl yürütme özellikli modeller için kullanın reasoning :

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(

Yapılandırılmış bir RAI ilkesini uygulamak için rai_config kullanın.

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(

İşlev Araçları

Foundry Agent Service v1

Foundry aracılarına özel işlev araçları sağlayabilirsiniz:

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())

Döküm Aracı Hizmeti v2

Foundry aracılarına özel işlev araçları sağlayabilirsiniz:

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())

Kod Yorumlayıcı

Döküm Aracı Hizmeti v1

Döküm aracıları barındırılan kod yorumlayıcı aracılığıyla kod yürütmeyi destekler:

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())

Üretim Aracı Hizmeti v2

Döküm aracıları barındırılan kod yorumlayıcı aracılığıyla kod yürütmeyi destekler:

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())

Akış Yanıtları

Döküm Aracı Hizmeti v1

Akış kullanılarak oluşturulurken yanıtları alın:

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())

Döküm Aracı Hizmeti v2

Akış kullanılarak oluşturulurken yanıtları alın:

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())

Ajanı Kullanma

Aracı standart bir BaseAgent'dir ve tüm standart aracı işlemleri destekler.

Aracıları çalıştırma ve aracılarla etkileşim kurma hakkında daha fazla bilgi için bkz. Aracı kullanmaya başlama öğreticileri.

Sonraki Adımlar

Üretim Modelleri Tabanlı Aracılar