Microsoft Agent Framework aracılarını Foundry tarafından barındırılan aracılar olarak barındırma

Microsoft Agent Framework barındırma paketlerini kullanarak, Foundry tarafından barındırılan aracıların protokolleri aracılığıyla bir Agent Framework aracısını kullanıma sunun. Barındırma paketleri aracı mantığınızı kodda tutmanıza olanak tanırken Foundry barındırılan çalışma zamanını, oturumları, ölçeği, kimliği ve protokol uç noktalarını yönetir.

Bu makalede, yalın bir Agent Framework ajanı oluşturur, bunu Responses veya Invocations protokolü aracılığıyla kullanıma sunar, HTTP üzerinden test eder ve Azure Developer CLI ile Foundry’ye dağıtırsınız.

Microsoft Foundry Skill, bağdaştırıcıyı uygulamaya geçirmeye, protokolleri test etmeye ve azd ile dağıtmaya yardımcı olabilir.

Prerequisites

Azure aboneliği. Ücretsiz bir tane oluşturun.
Dökümhane projesi.
gpt-4.1 veya gpt-4o gibi dağıtıma alınmış bir sohbet modeli.
Barındırılan bir aracıyı dağıtmak için projedeki Foundry Proje Yöneticisi rolü. Ayrıntılar için bkz: Barındırılan aracı dağıtma.
Azure CLI oturum açtı (az login) böylece DefaultAzureCredential kimlik doğrulaması yapabilir.

Python 3.10 veya üzeri.

.NET 10 SDK veya üzeri.

Paketleri yükleme

Agent Framework'ü ve Foundry barındırma paketini yükleyin:

pip install -U agent-framework agent-framework-foundry-hosting azure-identity python-dotenv

Paket, agent_framework_foundry_hosting Foundry protokolleri için konak sunucuları sağlar:

ResponsesHostServer OpenAI ile uyumlu /responses uç noktası için.
InvocationsHostServer genel /invocations uç nokta için.

Projenize Agent Framework ve Foundry barındırma paketlerini ekleyin:

dotnet add package Microsoft.Agents.AI
dotnet add package Microsoft.Agents.AI.Foundry.Hosting
dotnet add package Azure.AI.Projects
dotnet add package Azure.Identity

Çağırmalar protokolü için, Çağırmalar sunucu paketini de ekleyin:

dotnet add package Azure.AI.AgentServer.Invocations

Bu paketler, Foundry protokolleri için konak uzantıları sağlar:

AddFoundryResponses ve MapFoundryResponses, OpenAI uyumlu /responses uç noktası için.
genel amaçlı AddInvocationsServer uç noktası için MapInvocationsServer ve /invocations

Barındırma protokolü seçme

Barındırılan aracılar bir veya daha fazla protokolü kullanıma açabilir. Konuşma aracılarının çoğu için Yanıtlar ile başlayın.

Protocol	Bitiş noktası	Şu durumlarda kullanın:
Yanıtlar	`/responses`	OpenAI ile uyumlu sohbet, akış desteği, yanıt geçmişi ve konuşma ileti dizileri istiyorsunuz.
Çağrılar	`/invocations`	Özel bir JSON şekli, web kancası stili uç nokta veya konuşma dışı işleme istiyorsunuz.

Protokol davranışı ve oturumları hakkında arka plan için bkz. Barındırılan aracılar ve Barındırılan aracı oturumlarını yönetme.

Ortam değişkenlerini yapılandırma

Yerel geliştirme için proje uç noktasını ve model dağıtım adını ayarlayın:

export FOUNDRY_PROJECT_ENDPOINT="https://<resource>.services.ai.azure.com/api/projects/<project>"
export AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4.1"

PowerShell'de:

$env:FOUNDRY_PROJECT_ENDPOINT="https://<resource>.services.ai.azure.com/api/projects/<project>"
$env:AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4.1"

Aynı kod, Foundry'de barındırılan bir aracı olarak çalıştığında platform, çalışma zamanında FOUNDRY_PROJECT_ENDPOINT ve AZURE_AI_MODEL_DEPLOYMENT_NAME ekler.

Yanıtlar protokolü

Akış, yanıt geçmişi ve konuşma yazışması ile OpenAI uyumlu bir sohbet uç noktası istediğinizde Yanıtlar protokolunu kullanın.

Yanıtlar konağı oluşturma

Foundry modeli kullanan minimal bir Agent Framework aracısı ile adlı main.py bir dosya oluşturun.

import os

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from agent_framework_foundry_hosting import ResponsesHostServer
from azure.identity import DefaultAzureCredential
from dotenv import load_dotenv

# Load environment variables from a .env file when present.
load_dotenv()


def main() -> None:
    client = FoundryChatClient(
        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
        model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
        credential=DefaultAzureCredential(),
    )

    agent = Agent(
        client=client,
        instructions="You are a friendly assistant. Keep your answers brief.",
        # The hosting infrastructure manages conversation history, so the
        # service doesn't need to store it.
        default_options={"store": False},
    )

    server = ResponsesHostServer(agent)
    server.run()


if __name__ == "__main__":
    main()

Bu kod parçacığının yaptığı iş:FoundryChatClient aracılığıyla Foundry modeli tarafından desteklenen bir Agent Framework aracısı oluşturur, ardından bu aracıyı ResponsesHostServer bileşenine aktarır. Ana bilgisayar bir HTTP sunucusu başlatır ve aracıyı POST /responses üzerinden kullanıma sunar. Varsayılan olarak, sunucu bağlantı noktasına 8088bağlanır.

Referans: Microsoft Agent Framework belgeleri

Uygulamayı yerel olarak çalıştırın:

python main.py

Program.cs Responses Protokolü aracılığıyla bir Foundry modeli kullanan asgari bir Agent Framework aracısı içeren bir dosya oluşturun.

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

var projectEndpoint = new Uri(
    Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set."));

var deployment =
    Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME")
    ?? "gpt-4o";

// Create the agent via the AI project client using the Responses API.
AIAgent agent = new AIProjectClient(projectEndpoint, new DefaultAzureCredential())
    .AsAIAgent(
        model: deployment,
        instructions: "You are a friendly assistant. Keep your answers brief.",
        name: "assistant",
        description: "A simple general-purpose AI assistant");

// Host the agent as a Foundry hosted agent using the Responses API.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddFoundryResponses(agent);

var app = builder.Build();
app.MapFoundryResponses();
app.Run();

Bu kod parçacığının yaptığı iş: Foundry proje istemcisinden bir AIAgent oluşturur, bunu AddFoundryResponses ile bir Foundry Responses ana bilgisayarı olarak kaydeder ve POST /responses uç noktasını MapFoundryResponses ile eşler. Varsayılan olarak, ana bilgisayar bağlantı noktasında 8088hizmet eder.

Başvuru: AIProjectClient | DefaultAzureCredential

Uygulamayı yerel olarak çalıştırın:

dotnet run

Yanıtlar uç noktasını test edin

Yerel sunucuya akışsız bir Responses isteği gönderin.

Bash:

curl -sS -H "Content-Type: application/json" \
  -X POST http://localhost:8088/responses \
  -d '{"input":"Give me one practical tip for testing hosted agents.","stream":false}'

PowerShell:

$body = @{
  input  = "Give me one practical tip for testing hosted agents."
  stream = $false
} | ConvertTo-Json

Invoke-RestMethod `
    -Uri http://localhost:8088/responses `
    -Method Post `
    -Body $body `
    -ContentType "application/json"

Sunucu, yanıt metnini ve yanıt kimliğini içeren bir JSON nesnesiyle yanıt verir. Akış yanıtları için stream değerini true olarak ayarlayın. Ana makine, response.created, response.output_text.delta ve response.completed gibi Responses API sunucu tarafından gönderilen olaylarını gönderir.

Çok aşamalı konuşmalar

Konuşmaya devam etmek için önceki yanıt kimliğini sonraki isteğin previous_response_id alanına geçirin:

curl -sS -H "Content-Type: application/json" \
  -X POST http://localhost:8088/responses \
  -d '{"input":"Can you make that more concise?","previous_response_id":"<previous-response-id>","stream":false}'

Aracı Foundry’de çalıştırdığınızda, aynı yaklaşım barındırılan aracı Responses uç noktası üzerinden de çalışır. Daha sonraki adımların da aynı barındırılan korumalı alan dosya sistemine ihtiyacı varsa, agent_session_id ekleyin veya bir conversation kimliği kullanın. Ayrıntılar için bkz. Barındırılan aracı oturumlarını yönetme.

Çağırma protokolü

Arayanlarınız Yanıtlar API'sinin istek şeklini kullanamıyorsa veya senaryonuz sohbet konuşması değilse Çağırmalar protokolunu kullanın. Invocations ana bilgisayarı, oturum durumunu bir agent_session_id sorgu parametresi ve yanıt üst bilgisi üzerinden yönetir.

Bir çağrı ana bilgisayarı oluşturun

Responses örneğindekiyle aynı aracı kurulumunu kullanın, ancak InvocationsHostServer yerine ResponsesHostServer ile başlayın.

import os

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from agent_framework_foundry_hosting import InvocationsHostServer
from azure.identity import DefaultAzureCredential
from dotenv import load_dotenv

# Load environment variables from a .env file when present.
load_dotenv()


def main() -> None:
    client = FoundryChatClient(
        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
        model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
        credential=DefaultAzureCredential(),
    )

    agent = Agent(
        client=client,
        instructions="You are a friendly assistant. Keep your answers brief.",
        default_options={"store": False},
    )

    server = InvocationsHostServer(agent)
    server.run()


if __name__ == "__main__":
    main()

Bu kod parçacığının yaptığı iş: Agent Framework aracısını POST /invocationsaracılığıyla barındırır. Ana bilgisayar, oturum durumunu hem agent_session_id sorgu parametresi hem de yanıt üst bilgisi aracılığıyla yönetir.

Referans: Microsoft Agent Framework belgeleri

Çağırmalar protokolü, her isteği işlemek için uyguladığınız bir InvocationHandler kullanır. Çağırmalar sunucusunu ve işleyicinizi kaydedin, ardından uç noktaları eşleyin.

using Azure.AI.AgentServer.Invocations;
using Microsoft.Agents.AI;

var builder = WebApplication.CreateBuilder(args);

// Register your agent and the Invocations server services.
builder.Services.AddInvocationsServer();
builder.Services.AddScoped<InvocationHandler, MyInvocationHandler>();

var app = builder.Build();

// Map the Invocations protocol endpoints:
//   POST /invocations              - invoke the agent
//   GET  /invocations/{id}         - get result
//   POST /invocations/{id}/cancel  - cancel
app.MapInvocationsServer();
app.Run();

Bu kod parçacığının yaptığı iş: Çağrılar sunucu hizmetlerini ve uygulamanızı InvocationHandler kaydeder, ardından uç noktaları eşler /invocations . Her isteğin nasıl işlendiğini tanımlamak için uygularsınız MyInvocationHandler . Tam bir işleyici örneği için .NET Çağırmalar örneğine bakın.

Referans: AddInvocationsServer

Çağrılar uç noktasını test etme

Yerel sunucuya bir istek gönderin:

curl -sS -X POST http://localhost:8088/invocations \
  -H "Content-Type: application/json" \
  -d '{"message":"My name is Alice.","stream":false}'

Çok aşamalı konuşmalar için yanıt üst bilgisindeki değeri bir sonraki istekte agent_session_id sorgu parametresi olarak yeniden kullanınagent_session_id:

curl -sS -X POST "http://localhost:8088/invocations?agent_session_id=<session-id>" \
  -H "Content-Type: application/json" \
  -d '{"message":"What is my name?"}'

Platform, Çağrılar protokolü için konuşma geçmişini depolamaz. Daha sonraki çağrıları aynı barındırılan sandbox'a yönlendirmek için agent_session_id sorgu parametresini kullanın.

Deploy

Azure Geliştirici CLI'sını (azd) kullanarak dağıtın. Akış, aracı kapsayıcı görüntüsünü oluşturmak ve bunu Foundry tarafından barındırılan aracı çalışma zamanına dağıtmak için örnek manifest dosyalarını ve Docker'ı kullanır.

Barındırılan aracı dağıtımı için projede Foundry Project Manager rolü gereklidir. Ayrıntılar için bkz: Barındırılan aracı dağıtma.

Azure Geliştirici CLI uzantısını yükleme

Bir örneği başlatmadan önce AI aracısı uzantısını yükleyin ve oturum açın:

azd ext install azure.ai.agents
azd auth login

azd ai agent run, örnekteki Dockerfile'da tanımlanan kapsayıcı imajını oluşturduğu için Docker'ın yerel olarak çalışıyor olması gerekir. Komut ayrıntıları için bkz. Azure Developer CLI başvurusu.

Örnek bir manifest ile başlat

Yeni bir klasör oluşturun ve örnek bildirimden başlatın. Bildirim URL'sini kullanmak istediğiniz örnekle değiştirin.

mkdir my-agent-framework-agent
cd my-agent-framework-agent

azd ai agent init -m https://github.com/microsoft/agent-framework/blob/main/python/samples/04-hosting/foundry-hosted-agents/responses/basic/agent.manifest.yaml

mkdir my-agent-framework-agent
cd my-agent-framework-agent

azd ai agent init -m https://github.com/microsoft/agent-framework/blob/main/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-ChatClientAgent/agent.manifest.yaml

azd ai agent init istemlerini izleyin. Henüz bir Dökümhane projeniz ve model dağıtımınız yoksa, başlatma akışı bunları oluştururken size yol gösterebilir.

Azure kaynaklarını sağlama

Başlatılan proje yeni bir Foundry projesi ve model dağıtımı kullanıyorsa, önce Azure kaynaklarını sağlayın:

azd provision

Bu komut, diğer kaynakların yanında bir Foundry örneği, model dağıtımına sahip bir Foundry projesi, Application Insights örneği ve barındırılan aracı görüntüleri için bir kapsayıcı kayıt defteri içeren bir kaynak grubu oluşturur.

Kapsayıcıyı yerel olarak çalıştırın

Ajan ana bilgisayarını azd aracılığıyla yerel olarak çalıştırın:

azd ai agent run

Ana bilgisayar üzerinde http://localhost:8088hizmet eder. Başka bir terminalde yerel protokol uç noktasını çağırın:

azd ai agent invoke --local "Hello!"

Ayrıca, uç noktayı curl kullanarak doğrudan çağırabilirsiniz:

curl -X POST http://localhost:8088/responses \
  -H "Content-Type: application/json" \
  -d '{"input": "Hello!"}'

Foundry'ye dağıt

Aracıyı dağıt

azd deploy

Dağıtım, aracıyı bir konteyner imajı olarak paketler, bunu sağlanan konteyner kayıt deposuna gönderir ve Foundry tarafından barındırılan aracı çalışma zamanına dağıtır.

Foundry barındırma altyapısı, aşağıdakiler dahil olmak üzere çalışma zamanı ortam değişkenlerini aracıya ekler:

FOUNDRY_PROJECT_ENDPOINT: Aracının dağıtıldığı Foundry projesinin uç nokta URL'si.
AZURE_AI_MODEL_DEPLOYMENT_NAME: azd ai agent init sırasında seçilen model dağıtım adı.
APPLICATIONINSIGHTS_CONNECTION_STRING: Projenin Application Insights örneğine ait bağlantı dizesi.

Tam dağıtım kavramları, izinler ve yönetim ayrıntıları için bkz. Barındırılan aracı dağıtma ve Barındırılan aracı yaşam döngüsünü yönetme.

Troubleshooting

Agent Framework ile barındırılan aracılar geliştirirken sık karşılaşılan sorunları tanılamak için bu denetim listesini kullanın.

Barındırılan kapsayıcıdaki modele erişilemiyor

Barındırılan aracı sürümünün AZURE_AI_MODEL_DEPLOYMENT_NAME içerdiğini ve aracı kimliğinin Foundry projesini çağırma iznine sahip olduğunu onaylayın. Platform kümeleri FOUNDRY_PROJECT_ENDPOINT; kodunuz Foundry'de çalışırken bu değişkeni okumalıdır.

Konuşma durumu devam etmiyor

Responses protokolü için, sonraki adımlarda previous_response_id veya bir conversation kimliği iletin.

Çağrılar protokolü için platform konuşma geçmişini depolamaz. Sonraki çağrıları aynı barındırılan korumalı alana yönlendirmek için bir agent_session_id sorgu parametresi kullanın.

Protokol sürümü uyuşmazlığı

Yükseltmeden sonra istekler başarısız olursa bildirim ve barındırma paketinizin her ikisinin de protokol 2.0.0 sürümünü kullandığını onaylayın. Protokol sürümü 1.0.0 artık desteklenmiyor.

Sonraki adım

Barındırılan aracı dağıt

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-07-03