Azure OpenAI Aracıları

Microsoft Agent Framework, her biri farklı araç özelliklerine sahip farklı bir API yüzeyini hedefleyen üç ayrı Azure OpenAI istemci türünü destekler:

İstemci Türü	API	En Uygun
Sohbet Tamamlama	Sohbet Tamamlamaları API'si	Basit aracılar, geniş model desteği
Yanıt	Yanıtlar API'si	Barındırılan araçlarla (kod yorumlayıcı, dosya arama, web araması, barındırılan MCP) tam özellikli aracılar
Asistanlar	Yardımcılar API'si	Kod yorumlayıcı ve dosya arama ile sunucu tarafından yönetilen aracılar

Tavsiye

Doğrudan OpenAI eşdeğerleri (OpenAIChatClient, OpenAIResponsesClient, OpenAIAssistantsClient) için OpenAI sağlayıcısı sayfasına bakın. Araç desteği aynıdır.

Başlangıç Yapmak

Projenize gerekli NuGet paketlerini ekleyin.

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

Tüm Azure OpenAI istemci türleri bir AzureOpenAIClientoluşturarak başlar:

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

AzureOpenAIClient client = new AzureOpenAIClient(
    new Uri("https://<myresource>.openai.azure.com"),
    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.

Sohbet Tamamlama İstemcisi

Sohbet Tamamlama istemcisi, ChatCompletion API'sini kullanarak aracılar oluşturmak için basit bir yol sağlar.

var chatClient = client.GetChatClient("gpt-4o-mini");

AIAgent agent = chatClient.AsAIAgent(
    instructions: "You are good at telling jokes.",
    name: "Joker");

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

Desteklenen araçlar: İşlev araçları, web araması, yerel MCP araçları.

Yanıt İstemcisi

Yanıtlar istemcisi kod yorumlayıcı, dosya arama, web araması ve barındırılan MCP gibi en zengin araç desteğini sağlar.

var responsesClient = client.GetResponseClient("gpt-4o-mini");

AIAgent agent = responsesClient.AsAIAgent(
    instructions: "You are a helpful coding assistant.",
    name: "CodeHelper");

Console.WriteLine(await agent.RunAsync("Write a Python function to sort a list."));

Desteklenen araçlar: İşlev araçları, araç onayı, kod yorumlayıcı, dosya arama, web araması, barındırılan MCP, yerel MCP araçları.

Asistan İstemcisi

Assistants istemcisi, yerleşik kod yorumlayıcı ve dosya arama ile sunucu tarafından yönetilen aracılar oluşturur.

var assistantsClient = client.GetAssistantClient();

AIAgent agent = assistantsClient.AsAIAgent(
    instructions: "You are a data analysis assistant.",
    name: "DataHelper");

Console.WriteLine(await agent.RunAsync("Analyze trends in the uploaded data."));

Desteklenen araçlar: İşlev araçları, kod yorumlayıcı, dosya arama, yerel MCP araçları.

İşlev Araçları

Herhangi bir Azure OpenAI aracısına özel işlev araçları sağlayabilirsiniz:

using System.ComponentModel;
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)
    => $"The weather in {location} is cloudy with a high of 15°C.";

AIAgent agent = new AzureOpenAIClient(
    new Uri(endpoint),
    new DefaultAzureCredential())
     .GetChatClient(deploymentName)
     .AsAIAgent(instructions: "You are a helpful assistant", tools: [AIFunctionFactory.Create(GetWeather)]);

Console.WriteLine(await agent.RunAsync("What is the weather like in Amsterdam?"));

Akış Yanıtları

await foreach (var update in agent.RunStreamingAsync("Tell me a joke about a pirate."))
{
    Console.Write(update);
}

Tavsiye

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

Ajanı Kullanma

Üç istemci türü de aynı aracı işlemlerini (akış, iş parçacıkları, ara yazılım) destekleyen bir standart AIAgent oluşturur.

Daha fazla bilgi için Başlangıç öğreticilerine bakın.

Kurulum

pip install agent-framework --pre

Konfigürasyon

Her istemci türü farklı ortam değişkenleri kullanır:

Sohbet Tamamlama

AZURE_OPENAI_ENDPOINT="https://<myresource>.openai.azure.com"
AZURE_OPENAI_CHAT_DEPLOYMENT_NAME="gpt-4o-mini"

Yanıtlar

AZURE_OPENAI_ENDPOINT="https://<myresource>.openai.azure.com"
AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME="gpt-4o-mini"

Assistants

AZURE_OPENAI_ENDPOINT="https://<myresource>.openai.azure.com"
AZURE_OPENAI_CHAT_DEPLOYMENT_NAME="gpt-4o-mini"

İsteğe bağlı olarak şunları da ayarlayabilirsiniz:

AZURE_OPENAI_API_VERSION="2024-10-21"  # Default API version
AZURE_OPENAI_API_KEY="<your-api-key>"  # If not using Azure CLI authentication

Tüm istemciler kimlik doğrulaması için Azure kimlik bilgilerini kullanır. En basit yaklaşım, AzureCliCredential çalıştırıldıktan sonra az login'dır.

Sohbet Tamamlama İstemcisi

AzureOpenAIChatClient geniş model desteğine sahip en basit seçenek olan Sohbet Tamamlamaları API'sini kullanır.

import asyncio
from agent_framework.azure import AzureOpenAIChatClient
from azure.identity import AzureCliCredential

async def main():
    agent = AzureOpenAIChatClient(credential=AzureCliCredential()).as_agent(
        name="Joker",
        instructions="You are good at telling jokes.",
    )
    result = await agent.run("Tell me a joke about a pirate.")
    print(result)

asyncio.run(main())

Desteklenen araçlar: İşlev araçları, web araması, yerel MCP araçları.

Yanıt İstemcisi

AzureOpenAIResponsesClient Barındırılan araçlarla en zengin özellik seçeneği olan Yanıtlar API'sini kullanır.

import asyncio
from agent_framework.azure import AzureOpenAIResponsesClient
from azure.identity import AzureCliCredential

async def main():
    agent = AzureOpenAIResponsesClient(credential=AzureCliCredential()).as_agent(
        name="FullFeaturedAgent",
        instructions="You are a helpful assistant with access to many tools.",
    )
    result = await agent.run("Write and run a Python script that calculates fibonacci numbers.")
    print(result)

asyncio.run(main())

Azure AI Foundry projeye ait uç nokta ile Yanıtlar İstemcisi

AzureOpenAIResponsesClient Azure AI Foundry proje uç noktasından da oluşturulabilir:

from agent_framework.azure import AzureOpenAIResponsesClient
from azure.identity import AzureCliCredential

client = AzureOpenAIResponsesClient(
    project_endpoint="https://<your-project>.services.ai.azure.com/api/projects/<project-id>",
    deployment_name="gpt-4o-mini",
    credential=AzureCliCredential(),
)
agent = client.as_agent(
    name="FoundryResponsesAgent",
    instructions="You are a helpful assistant.",
)

Desteklenen araçlar: İşlev araçları, araç onayı, kod yorumlayıcı, dosya arama, web araması, barındırılan MCP, yerel MCP araçları.

Yanıt İstemcisi ile Barındırılan Araçlar

Yanıtlar istemcisi barındırılan get_*_tool() her araç türü için yöntemler sağlar:

async def hosted_tools_example():
    client = AzureOpenAIResponsesClient(credential=AzureCliCredential())

    code_interpreter = client.get_code_interpreter_tool()
    web_search = client.get_web_search_tool()
    file_search = client.get_file_search_tool(vector_store_ids=["vs_abc123"])
    mcp_tool = client.get_mcp_tool(
        name="GitHub",
        url="https://api.githubcopilot.com/mcp/",
        approval_mode="never_require",
    )

    agent = client.as_agent(
        name="PowerAgent",
        instructions="You have access to code execution, web search, files, and GitHub.",
        tools=[code_interpreter, web_search, file_search, mcp_tool],
    )
    result = await agent.run("Search the web for Python best practices, then write a summary.")
    print(result)

Asistanlar İstemcisi

AzureOpenAIAssistantsClient Yerleşik kod yorumlayıcı ve dosya arama ile sunucu tarafından yönetilen aracılar olan Yardımcılar API'sini kullanır. async with Otomatik yardımcı yaşam döngüsü yönetimi için bağlam yöneticisine dikkat edin.

import asyncio
from agent_framework.azure import AzureOpenAIAssistantsClient
from azure.identity import AzureCliCredential

async def main():
    async with AzureOpenAIAssistantsClient(credential=AzureCliCredential()).as_agent(
        name="DataAnalyst",
        instructions="You analyze data using code execution.",
    ) as agent:
        result = await agent.run("Calculate the first 20 prime numbers.")
        print(result)

asyncio.run(main())

Desteklenen araçlar: İşlev araçları, kod yorumlayıcı, dosya arama, yerel MCP araçları.

Ortak Özellikler

Üç istemci türü de şu standart aracı özelliklerini destekler:

İşlev Araçları

from agent_framework import tool

@tool
def get_weather(location: str) -> str:
    """Get the weather for a given location."""
    return f"The weather in {location} is sunny, 25°C."

async def example():
    agent = AzureOpenAIResponsesClient(credential=AzureCliCredential()).as_agent(
        instructions="You are a weather assistant.",
        tools=get_weather,
    )
    result = await agent.run("What's the weather in Tokyo?")
    print(result)

Çok Aşamalı Konuşmalar

async def thread_example():
    agent = AzureOpenAIResponsesClient(credential=AzureCliCredential()).as_agent(
        instructions="You are a helpful assistant.",
    )
    session = await agent.create_session()

    result1 = await agent.run("My name is Alice", session=session)
    print(result1)
    result2 = await agent.run("What's my name?", session=session)
    print(result2)  # Remembers "Alice"

Yayın

async def streaming_example():
    agent = AzureOpenAIResponsesClient(credential=AzureCliCredential()).as_agent(
        instructions="You are a creative storyteller.",
    )
    print("Agent: ", end="", flush=True)
    async for chunk in agent.run("Tell me a short story about AI.", stream=True):
        if chunk.text:
            print(chunk.text, end="", flush=True)
    print()

Ajanı Kullanma

Tüm istemci türleri aynı işlemleri destekleyen bir standart Agent oluşturur.

Daha fazla bilgi için Başlangıç öğreticilerine bakın.

Sonraki Adımlar

OpenAI Sağlayıcısı