Hızlı Başlangıç: Yanıtlar API'sini kullanarak aracı oluşturma

Bu hızlı başlangıçta, kendi kodunuzdan bir Foundry proje uç noktasındaki Responses API'sini çağırarak geçici bir aracı — yani tanımı (yönergeler, araçlar, model) Foundry Agent Service'te kalıcı bir kaynak olarak değil, uygulama kodunuzda bulunan bir aracı — oluşturursunuz. Her çağrı işleminizdeki aracıyı oluşturur ve model çıkarımı ve araç düzenlemesi için Yanıtlar API'sini çağırır.

Bu yaklaşım, aracı tanımlarının uygulama kodunun geri kalanıyla birlikte dağıtılmasını ve sürümlendirilmesini isteyen; bunların, birinin uygulamayla senkronize tutmak zorunda olduğu bant dışı bir kaynak olmasını istemeyen geliştiriciler, ISV'ler ve dijital öncelikli kuruluşlar için uygundur. İstem aracılarından farklı olarak, Foundry'de oluşturulacak, güncelleştirilecek veya silinecek bir aracı kaynağı yoktur; yaşam döngüsü yönetimi doğrudan Yanıtlar API'sini çağırarak değiştirilir.

Yanıtlar API'si, Foundry için tek model ve araçlar giriş noktasıdır. Bunu iki farklı uç noktada çağırabilirsiniz:

  • Foundry proje uç noktası (bu hızlı başlangıç için önerilen) — tam Foundry desteği. Katalogdaki Foundry modellerini ve platform araçlarını (dosya arama, kod yorumlayıcı, bellek, web araması, MCP, SharePoint, WorkIQ, Fabric IQ ve daha fazlası) {project_endpoint}/openai/v1/responses üzerinden erişilen, proje kapsamındaki tek bir API arabirimi aracılığıyla kullanıma sunar.
  • Azure OpenAI uç noktası — mevcut OpenAI istemcileriyle en iyi gecikme süresi ve en yüksek uyumluluk. Bunu yalnızca OpenAI modellerine ve standart OpenAI araçlarına ihtiyacınız olduğunda ve Foundry'ye özgü özelliklere ihtiyacınız olmadığında kullanın.

Önerilen yol, kimlik doğrulamasını, araç kablolarını ve ileti düzenlemeyi sizin için işleyen Agent Framework'dür. Python’da bu FoundryChatClient; .NET'te ise AIProjectClient.AsAIAgent(...). OpenAI SDK'sı bu uç noktada da çalışır ve OpenAI SDK'sını doğrudan kullanma başlığı altında alternatif olarak ele alınmıştır.

Azure aboneliğiniz yoksa ücretsiz hesap oluşturun.

Geçici aracı deseni ne zaman kullanılır?

Aracı kodunu Foundry dışında barındırırken (potansiyel olarak kendi uygulamanıza eklenmiş olabilir) ancak modeller ve platform araçları gibi Foundry aracısı özelliklerine erişmek istediğinizde bu düzeni kullanın.

Kısa ömürlü model ve barındırılan aracılar, alternatif değil, birbirini tamamlayıcıdır. Aynı Agent Framework ajan kodu, barındırılan bir ajan olarak da paketlenebilir ve Foundry Agents API aracılığıyla sunulabilir; bu, diğer uygulamaların, hizmetlerin veya ajanların çağırabileceği Foundry tarafından yönetilen bir uç nokta istediğiniz durumlarda kullanışlıdır. Her ikisini de tek bir kod tabanından yapabilirsiniz: aracıyı uygulamanızla birlikte geldiği süreçte çalıştırın ve diğer arayanların ihtiyaç duyduğu barındırılan bir aracıyla aynı tanımı yayımlayın.

Foundry projesi uç noktasının OpenAI Responses API'ye ek olarak sundukları

Bir Foundry proje uç noktasındaki Yanıtlar API'si OpenAI Yanıtları API'siyle uyumludur, bu nedenle mevcut OpenAI istemcileri en az değişiklikle buna karşı çalışır. Foundry proje uç noktası, aşağıdakileri üste ekler:

  • Project kapsamlı veriler: Dosyalar, vektör depoları ve diğer veriler kaynak düzeyi yerine project düzeyinde depolanır; bu da project başına veri yalıtımı sağlar ve standart aracı kurulumu aracılığıyla kendi kaynaklarınızı getirmenizi sağlar.
  • OpenAI'ye ek olarak Foundry Models: Yalnızca OpenAI modelleri değil, doğrudan Azure tarafından sunulan Foundry Models de aynı API üzerinden kullanılabilir.
  • Foundry'ye özgü araçlar: standart OpenAI araçlarının yanı sıra SharePoint, WorkIQ ve Fabric IQ gibi platform araçları da kullanılabilir.
  • Araçlar için adına (OBO) kimlik doğrulaması: Araçlar aşağı akış hizmetlerini yalnızca uygulama kimliği olarak değil oturum açmış kullanıcı olarak çağırabilir.
  • Proje düzeyinde gözlemlenebilirlik ve yönetişim: Proje uç noktası üzerinden yapılan çağrılar, ek yapılandırma gerektirmeden projenin iz sürme, izleme, içerik filtreleri ve kimlik yapılandırmasından geçer (bkz. Gözlemlenebilirlik ve kurumsal özellikler).

Bu projeye özgü yeteneklerin kilidini açan şey, kaynak düzeyinde bir OpenAI uç noktası değil, proje uç noktasını çağırmaktır.

Prerequisites

  • Python 3.10 veya üzeri yüklü.

Ortam değişkenlerini ayarlama

Proje uç noktanızı ve dağıtılan model adınızı ortam değişkenleri olarak depolayın. Aşağıdaki örneklerde ortamdan bu değerler okunur.

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

Paketleri yükleme

Agent Framework paketini Foundry sağlayıcısıyla yükleyin:

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, AsAIAgent(...) üzerinde AIProjectClient uzantısı yöntemini sağlar ve geçişli olarak Microsoft.Agents.AI getirir.

Bir ajan oluştur

sürecinizde yerel olarak çalışan ve model çıkarımı ve araç düzenlemesi için Yanıtlar API'sini çağıran kısa ömürlü bir aracı oluşturun.

FoundryChatClient ve Agent sınıfını kullanın.

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

Çıktı, ajanın yanıtını yazdırır. Aracı kısa ömürlü olduğundan, hizmette hiçbir tanım kalıcı olmaz; yalnızca Python işleminin ömrü boyunca var olur.

Foundry proje uç noktasını bir AIAgent olarak sarmalamak için Microsoft Agent Framework’ten AIProjectClient.AsAIAgent(...) kullanın.

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?")}");

Çıktı, ajanın yanıtını yazdırır. Ajan geçici olduğundan, hizmete hiçbir tanım kalıcı olarak kaydedilmez; yalnızca işlem süresince var olur.

İşlev araçları ekleme

Yerel işlevleri tanımlayın ve bunları aracıya iletin. Ajan, konuşma sırasında gerektiğinde bu araçları otomatik olarak çağırır.

Dekoratör kullanarak @tool yerel işlev araçlarını tanımlayın.

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

Aracı, işlevin ne zaman çağrıldığını get_weather belirlemek, yerel olarak yürütmek ve sonucu doğal dilde döndürmek için Yanıtlar API'sini kullanır.

Yerel bir yöntem tanımlayın, bunu [Description] öznitelikleriyle işaretleyin ve AIFunctionFactory.Create(...) ile sarın.

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?")}");

Aracı, çağrısının GetWeatherne zaman yapileceğini belirlemek için Yanıtlar API'sini kullanır, yerel olarak yürütür ve sonucu doğal dilde döndürür.

Web arama aracını kullanma

Foundry proje uç noktasındaki Yanıtlar API'sinde web araması gibi yerleşik barındırılan araçlar sağlanır. Aracınıza herhangi bir yerel uygulama olmadan web araması erişimi verin.

FoundryChatClient.get_web_search_tool() kullanın:

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

Web arama aracı, Foundry projesi Yanıtları API'sini kullanarak sunucu tarafı yürütür. Aracınıza hem web erişimi hem de özel kod özellikleri vermek için bunu yerel işlev araçlarıyla birleştirebilirsiniz:

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
    ],
)

new HostedWebSearchTool() öğesini tools listesine geçirin:

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?")}");

Web arama aracı, Foundry projesi Yanıtları API'sini kullanarak sunucu tarafı yürütür. Aracınıza hem web erişimi hem de özel kod özellikleri vermek için bunu yerel işlev araçlarıyla birleştirebilirsiniz:

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

Yanıtları akış olarak iletin

Tam iletiyi beklemek yerine, oluşturdukları yanıtları alın.

parametresini stream=True kullanın:

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

RunStreamingAsync öğesini çağırın ve AgentResponseUpdate akışı üzerinde yineleme yapın:

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

Akış çıktısı, model her belirteci oluştururken konsolda kademeli olarak görünür.

Gözlemlenebilirlik ve kurumsal özellikler

Kısa ömürlü, yönetilmeyen anlamına gelmez. Çağrılar proje uç noktasından geçtiğinden, ek kablo bağlantısı olmadan projenin kurumsal yapılandırmasını devralır:

  • İz sürme ve izleme: İstekler, araç çağrıları ve token kullanımı proje için Foundry’nin gözlemlenebilirlik bölümüne aktarılır.
  • Content filtreleri ve idare: Project düzeyinde içerik filtreleri ve sorumlu yapay zeka ilkeleri her çağrı için geçerlidir.
  • Kimlik ve erişim: Çağrılar projenin kimlik yapılandırmasında kimlik doğrulaması yapar; OBO özellikli araçlar oturum açmış kullanıcı olarak görev yapabilir.

Geçici desen, kısıtlı özelliklere sahip bir katman değildir — aracıyı ister süreç içinde çalıştırın ister aynı kodu barındırılan bir aracı olarak paketleyin, aynı Foundry modellerini, araçları, gözlemlenebilirliği ve yönetişimi elde edersiniz. Seçim, özellik kümesiyle değil dağıtım şekliyle ilgilidir.

OpenAI SDK'sını doğrudan kullanma

Foundry proje Yanıtları API'si OpenAI uyumlu olduğundan, istemciyi proje uç noktasına ({project_endpoint}/openai/v1/responses ) işaret ederek doğrudan OpenAI SDK'sından da çağırabilirsiniz. Bu yolu yalnızca OpenAI SDK kodunuz varsa veya istek ve yanıt şekilleri üzerinde daha düşük düzeyde denetime ihtiyacınız varsa kullanın. Yeni kodda, sizin için kimlik doğrulamasını, araç entegrasyonunu ve orkestrasyonu yöneten Agent Framework’ün tercih edilmesi gerekir.

SDK örnekleri için bkz:

Foundry Responses örnekleri (azure-ai-projects)

Azure. AI. OpenAI örnekleri

Kaynakları temizle

Burada oluşturulan Agent Framework aracıları kısa ömürlü olduğundan, hizmet tarafı temizleme gerekmez. Ajan yalnızca yerel sürecinizde bulunur. Artık ihtiyacınız olmayan Foundry kaynakları oluşturduysanız, bunları Foundry portalında silin.

İlgili içerik

Bu düzende daha derine gidin

Barındırılan aracıyla aynı aracı kodunu paketleme

  • Last updated on