Foundry Barındırılan Temsilciler

Microsoft Foundry Aracı Hizmeti'nde barındırılan aracılar, kapsayıcılı aracı uygulamalarını Microsoft yönetilen altyapıya dağıtmanıza olanak tanır. Platform, aracınızın mantığına odaklanabilmeniz için ölçeklendirme, oturum durumu kalıcılığı, güvenlik ve yaşam döngüsü yönetimini işler. Microsoft Foundry Barındırılan Aracılar genel olarak kullanılabilir ve kendi kodunuzla veya tercih edilen aracı çerçevesiyle oluşturulmuş aracıları destekler. Bu makale özellikle Agent Framework barındırma tümleştirmesini kapsar.

Agent Framework barındırma tümleştirmesiyle, Agent ile sarmalanmış bir iş akışı da dahil olmak üzere bir Workflow.as_agent() öğesini, minimum kodla Foundry Responses veya Invocations protokolü üzerinden kullanıma sunabilirsiniz.

Uyarı

Ayrıca, Azure Geliştirici CLI (azd) iş akışlarını kullanarak diğer çerçevelerle oluşturulmuş aracı kodunu Foundry'de barındırılan aracılara dağıtabilirsiniz. Çerçeveden bağımsız kavramlar ve dağıtım kılavuzu için bkz. Barındırılan aracılar nelerdir? Bu makalenin geri kalanında Agent Framework tümleştirmesi ele alınmaktadır.

Barındırılan aracılar hangi durumlarda kullanılmalıdır?

İstediğiniz zaman Foundry barındırılan aracıları seçin:

  • Yönetilen altyapı — kapsayıcıları, web sunucularını veya ölçeklendirme kurallarını kendiniz yapılandırmanız gerekmez.
  • Yerleşik oturum yönetimi — platform, sırayla ve boşta kalma dönemlerinde $HOME dosyalarını kalıcı olarak saklar.
  • Ayrılmış aracı kimliği — Dağıtılan her aracı, modellere, araçlara ve alt hizmetlere güvenli erişim için bir Entra kimliğine sahip olur.
  • OpenAI uyumlu uç noktalar — istemciler, Yanıtlar protokolü aracılığıyla OpenAI uyumlu herhangi bir SDK kullanarak aracınızla etkileşime geçebilir.
  • Gerçek zamanlı sesli aracılar için, sunucu tarafı ses etkinliği algılama, yankı iptali ve gürültü azaltma özelliklerinden yararlanmak üzere Foundry Tools (Voice Live) içinde Azure Speech ile barındırılan aracılar kullanın. Ayrıntılar için bkz. Voice Live'ı barındırılan aracılarla kullanma.

Uyarı

Python agent-framework-foundry-hosting tümleştirmesi yayın öncesidir. Yönetilen barındırma hizmeti olan Microsoft Foundry Barındırılan Aracılar genel kullanıma sunuldu.

Prerequisites

Yerel test için şunları da yapmanız gerekir:

  • Model dağıtımı olan bir Microsoft Foundry projesi (örneğin, gpt-4o)
  • Azure CLI yüklü ve kimliği doğrulanmış (az login)

Barındırma NuGet paketini yükleyin:

dotnet add package Microsoft.Agents.AI.Foundry.Hosting --prerelease
  • Python 3.10 veya üzeri

Yayın öncesi barındırma paketini, Foundry istemcisini ve Azure kimlik doğrulama paketini yükleyin:

pip install --pre agent-framework-foundry agent-framework-foundry-hosting azure-identity

Foundry'de platform, çağıranın kullanıcı bağlamını ve çağrı bağlamını sağlar; barındırma altyapısı, kullanıcı başına durumu yalıtmak ve istek bağlamını Foundry hizmetlerine iletmek için bunları kullanır. Yerel çalıştırmalar bu platform bağlamını almaz, bu nedenle uygulamaların gerektiğinde kendi kimlik ve durum denetimlerini sağlaması gerekir.

Yanıtlar protokolü

Yanıtlar protokolü çoğu aracı için önerilen başlangıç noktasıdır. OpenAI uyumlu /responses bir uç noktayı kullanıma sunar ve platform konuşma geçmişini, akış ve oturum yaşam döngüsünü otomatik olarak yönetir.

Python için barındırılan aracılarda, erken sona eren bir yanıtın durumu incomplete olur. Akış istemcileri bir terminal response.incomplete olayı alırken, akış dışı istemciler status olarak incompleteayarlanır. content_filter bitiş nedeni, content_filter olarak ayarlanmış incomplete_details.reason değerine karşılık gelir ve length, max_output_tokens değerine karşılık gelir. Oluşturulan çıkış veya reddetme içeriği yanıtta kullanılabilir durumda kalır.

using Azure.AI.AgentServer.Core;
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";

AIAgent agent = new AIProjectClient(projectEndpoint, new DefaultAzureCredential())
    .AsAIAgent(
        model: deployment,
        instructions: "You are a helpful AI assistant.",
        name: "my-agent");

var builder = AgentHost.CreateBuilder(args);
builder.Services.AddFoundryResponses(agent);
builder.RegisterProtocol("responses", endpoints => endpoints.MapFoundryResponses());

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

, AgentHost.CreateBuilder Foundry barındırma ortamı için önceden yapılandırılmış bir uygulama konağı oluşturur. AddFoundryResponses aracınızı Yanıtlar protokolü işleyicisine kaydeder ve MapFoundryResponses HTTP uç noktasını eşler /responses .

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

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 helpful AI assistant.",
)

server = ResponsesHostServer(agent)
server.run()

ResponsesHostServer ajanınızı sarar ve Foundry Yanıtları protokolü aracılığıyla erişilebilir hale getirir. İş akışı olmayan bir aracı için varsayılan değer history_source="agent_server" , modelin geçmiş kaynağı olarak yapılandırılmış Agent Server yanıt sağlayıcısını kullanır. Ana bilgisayar, istemci varsayılan olarak geçmişi depoladığında aşağı akış modeli hizmetinin ikinci bir kopyayı korumasını engeller.

HistoryProvider içeren bir load_messages=True ile varsayılan geçmiş kaynağını birleştirmeyin. Ayrıca previous_response_id, conversation veya conversation_id aşağı akış hizmeti sürdürme seçeneklerini de ayarlamayın. Ana bilgisayar, yinelenen geçmiş kayıtlarını önlemek için bu yapılandırmaları reddeder.

ResponsesHostServer(agent, history_source="agent") öğesini, ajanının geçmiş sağlayıcısının veya alt akış model hizmetinin sohbet geçmişini yönetmesi gerektiğinde kullanın. Bu mod, Aracı Sunucusu'ndan yalnızca geçerli istek girişini geçirir ve aracının geçmişini ve hizmet depolama davranışını korur. Özel SupportsAgentRun uygulamalar bu modu kullanmalıdır. store parametresi ayrı kalır: Her iki modda da Yanıtlar API girişlerini ve çıkışlarını kalıcı hale getiren yanıt sağlayıcısını seçer.

Konak, sağlanan aracıya sahiptir ve barındırmaya özgü bağlam sağlayıcıları ekleyebilir. Aracıyı başka bir ana bilgisayarla yeniden kullanmayın veya ana bilgisayar oluşturulduktan hemen sonra doğrudan çağırmayın.

Bir temsilci örneği veya fabrika seçin

Hem InvocationsHostServer hem de ResponsesHostServer, agent parametresi aracılığıyla bir ajan örneğini veya sıfır argümanlı eşzamanlı ya da eşzamansız bir çağrılabiliri kabul eder. Ana bilgisayar, yaşam süresi boyunca aynı örneği yeniden kullanır. Çağrılabilen bir istek başına bir kez çalıştırılır ve döndürülen aracı bu isteğe aittir.

Ajan, AgentSession dışında değiştirilebilir durumu koruyorsa bir çağrılabilir kullanın. Özellikle, yeni bir iş akışı, yürütücüler ve sarmalanmış aracılar oluşturan bir fabrika kullanarak bir WorkflowAgent oluşturun:

def create_workflow_agent():
    return build_workflow().as_agent(name="support-workflow")


server = ResponsesHostServer(agent=create_workflow_agent)

İş akışı adını ve yürütücü kimliklerini kararlı tutun, böylece daha sonra Yanıt istekleri kaydedilen denetim noktalarını bulabilir. ResponsesHostServer oturum, denetim noktası ve işlev onayı depoları aracılığıyla desteklenen duruma devam eder; istek kapsamlı bir aracıda rastgele alanlar kalıcı değildir. İş akışı ve dayanıklı uzun süre çalışan iş akışı örneklerine bakın.

Durumu kalıcı hale getirmek ve uzun süreli konuşmaları yönetmek

ResponsesHostServer ve InvocationsHostServer kalıcı oturum depolarını varsayılan olarak yapılandırın. AgentSessionStoreProvider, bir FoundryAgentSessionStore sağlar; Yanıt oturumları agent_sessions mantıksal deposunu kullanırken, Çağrı oturumları ayrı invocation_sessions deposunu kullanır. Bu depolar, barındırılan ortamda Foundry State Store'u, yerel olarak çalıştırdığınızda ise SDK'nın dosya tabanlı depolamasını kullanır.

Responses iş akışı aracıları için, CheckpointStoreProvider bir FoundryCheckpointStore sağlar. FunctionApprovalStoreProvider bekleyen onaylar için bir FoundryFunctionApprovalStore sunar.

history_source="agent" ile yapılandırılmış oturum deposu, AgentSession tarafından taşınan sağlayıcı durumunu, InMemoryHistoryProvider’den gelen iletiler de dahil olmak üzere kalıcı olarak saklar.

Her iki ana bilgisayar da StoreProvider[SessionStore] ile agent_session_store_provider arasını kabul eder. Oturum durumu serileştirmeyi desteklemelidir AgentSession . register_state_type() ile özel durum türleri için codec'leri kaydedin; geri yüklenen durum Python nesne kimliğini korumaz. Yeni varsayılan depoların son yazma tarihinden 30 gün sonra oturumları sona erer. Özel sağlayıcılar kendi saklama sürelerini yönetir.

Yanıta özgü depolama için, ContextScopedStoreProvider öğesine bir checkpoint_store_provider veya StoreProvider öğesine bir function_approval_store_provider geçirin.

ResponsesServerOptions içinden azure.ai.agentserver.responses öğesini içe aktarın ve options parametresi aracılığıyla ResponsesHostServer öğesine iletin. Kullanılabilir uzun süreli konuşma seçenekleri ajan türüne bağlıdır:

Capability Ajan türü Gereksinimler ve davranış
Dayanıklı arka plan yanıtları Yalnızca iş akışı ResponsesServerOptions(resilient_background=True)ayarlayın. background=true ve store=true ile Responses isteğini gönderin. Yeniden başlatmanın ardından ana bilgisayar, en son kalıcı iş akışı denetim noktasından devam eder veya denetim noktası yoksa özgün girdiyi yeniden oynatır. Ana bilgisayar tarafından yönetildiği için iş akışında denetim noktası depolama alanını yapılandırmayın. Son kalıcı denetim noktasından sonraki işlem tekrarlanabileceğinden, dış yan etkileri idempotent yapın.
Yönlendirilebilir konuşmalar Yalnızca iş akışı dışı store=true ayarlayın ve ResponsesServerOptions(steerable_conversations=True) ile Responses istekleri gönderin. Aynı conversation değerini yeniden kullanarak turları tek bir doğrusal zincir üzerinde tutun. Alternatif olarak, hemen önce gelen previous_response_id öğesini gönderin ve çözümlenmiş agent_session_id öğesini koruyun. Ana bilgisayar, bir çatala yol açacak eskimiş önceki kayıtları reddeder.

ResponsesHostServer, iş akışı olmayan bir aracıda esnek arka plan yanıtlarını veya iş akışı aracısında yönlendirilebilir konuşmaları etkinleştirirseniz RuntimeError oluşturur. Eksiksiz uygulamalar için özel depolama, dayanıklı uzun süre çalışan iş akışı ve yönlendirilebilir uzun süre çalışan aracı örneklerine bakın.

Foundry tarafından barındırılan bir MCP aracı kullanıcı onayı gerektirdiğinde, ResponsesHostServer bir çıkış öğesiyle tamamlanmamış bir oauth_consent_request yanıt döndürür. consent_link’ı kullanıcıya sunun, ardından kullanıcı onayını tamamladıktan sonra previous_response_id olarak eksik yanıtın kimliğiyle devam edin. Ana bilgisayar, bu yeniden denemede aracının oturumunu korur ve yalnızca mutlak HTTPS onay bağlantılarını sunar.

Çağırma protokolü

Çağırmalar protokolü, HTTP isteği ve yanıtı üzerinde tam denetim sağlar. OpenAI uyumlu olmayan özel yüklere, konuşma dışı işlemeye veya akış protokollerine ihtiyacınız olduğunda bunu kullanın.

C# dilinde Çağırmalar protokolüyle, gelen istekleri işlemek için özel InvocationHandler bir uygulama uygularsınız:

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

var builder = AgentHost.CreateBuilder(args);

builder.Services.AddSingleton<AIAgent, MyAgent>();
builder.Services.AddInvocationsServer();
builder.Services.AddScoped<InvocationHandler, MyInvocationHandler>();

builder.RegisterProtocol("invocations", endpoints => endpoints.MapInvocationsServer());

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

AddInvocationsServer yöntemi, Çağırma Protokolü hizmetlerini kaydeder. Aracınızın her isteği nasıl işlediğini tanımlamak için uygulamanız InvocationHandler gerekir.

Hafif bir kurulum için InvocationsHostServer paketinden agent_framework_foundry_hosting kullanın. Aracınızı ResponsesHostServer gibi sarar ve oturum yönetimini otomatik olarak yönetir.

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

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

InvocationsHostServer Responses host’u için açıklanan aynı örnek veya istek kapsamındaki fabrika biçimlerini kabul eder. Yapılandırılan depodan serileştirilmiş oturumları geri yükler, böylece ana bilgisayar yeniden başlatıldıktan sonra tamamlanmış konuşmalar devam edebilir. Depolama davranışı, saklama ve özelleştirme için bkz. Durumu kalıcı hale getirme ve uzun süren konuşmaları işleme.

Barındırıldığında, platform oturum kimliği ve kullanıcı kimliği birlikte kaydedilen oturumu tanımlar. AgentSession.session_id öğesini tek bir opak değer olarak ele alın; ayrıştırmayın veya iç temsilimine bağımlı olmayın. Yerel çalıştırmalar platform oturum kimliğini değiştirmeden kullanır. Depo işlem veya tam olarak bir kez yürütme sağlamadığından uygulamaların aynı oturum için çakışan istekleri koordine etmesi gerekir.

Çağırma protokolü, bekleyen veya kesintiye uğrayan iş akışı çalıştırmalarını sürdürmez. Farklı iş akışı devamlılığı davranışına ihtiyacınız olduğunda aşağıdaki bölümdeki özel işleyici desenini kullanın.

İstek işleme üzerinde tam denetim sağlamak için, InvocationAgentServerHost paketinden doğrudan azure.ai.agentserver.invocations kullanın ve kendi çağrı işleyicinizi uygulayın:

import os
from collections.abc import AsyncGenerator

from agent_framework import Agent, AgentSession
from agent_framework.foundry import FoundryChatClient
from azure.ai.agentserver.invocations import InvocationAgentServerHost
from azure.identity import DefaultAzureCredential
from starlette.requests import Request
from starlette.responses import JSONResponse, Response, StreamingResponse

_sessions: dict[str, AgentSession] = {}

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

app = InvocationAgentServerHost()


@app.invoke_handler
async def handle_invoke(request: Request):
    """Handle streaming multi-turn chat."""
    data = await request.json()
    session_id = request.state.session_id
    stream = data.get("stream", False)
    user_message = data.get("message", None)

    if user_message is None:
        return Response(content="Missing 'message' in request", status_code=400)

    session = _sessions.setdefault(session_id, AgentSession(session_id=session_id))

    if stream:

        async def stream_response() -> AsyncGenerator[str]:
            async for update in agent.run(user_message, session=session, stream=True):
                yield update.text

        return StreamingResponse(
            stream_response(),
            media_type="text/event-stream",
            headers={"Cache-Control": "no-cache", "Connection": "keep-alive"},
        )

    response = await agent.run([user_message], session=session, stream=stream)
    return JSONResponse({"response": response.text})


if __name__ == "__main__":
    app.run()

Warning

Özel işleyici örneğindeki bellek içi oturum deposu yeniden başlatıldığında kaybolur. Üretimde dayanıklı depolama (örneğin, Cosmos DB) kullanın.

Eksiksiz bir Invocations dağıtımı için Foundry’de barındırılan Telegram örneğine bakın. API Management'ı barındırılan aracı webhook'unun önüne konumlandırır ve kalıcı konuşma geçmişi için yönetilen kimlikler, Key Vault ve Cosmos DB kullanır.

Uyarı

Foundry’de barındırılan aracılar için Go desteği yakında kullanıma sunulacak. En son durum için bkz. Agent Framework Go deposu .

Tip

Barındırılan aracı projesi örnekleri için Python örnekleri veya C# örnekleri bakın. Ya da yeni bir barındırılan aracı projesinin iskelesini sıfırdan oluşturmak için azd ai agent init komutunu kullanabilirsiniz. Adım adım yönergeler için bu hızlı başlangıç kılavuzuna bakın.

Yerel olarak çalıştırılıyor

Azure Geliştirici CLI'sı (azd), barındırılan aracınızı yerel olarak çalıştırmanın ve test etmenin en kolay yolunu sağlar.

Projeyi başlatma

Yeni bir klasör oluşturun ve örnek bildirimden başlatın:

mkdir my-hosted-agent && cd my-hosted-agent
azd ai agent init -m <path-to-agent.manifest.yaml>

Tip

Bildirim, yerel bir YAML dosyasının yolu veya uzak bildirimin URL'si olabilir.

Ortam değişkenlerini ayarlama

export FOUNDRY_PROJECT_ENDPOINT="https://<account>.services.ai.azure.com/api/projects/<project>"
export AZURE_AI_MODEL_DEPLOYMENT_NAME="<your-model-deployment>"

Aracı ana bilgisayarını çalıştırma

azd ai agent run

Agent Host http://localhost:8088 üzerinde başlar.

Aracıyı çağırma

azd ai agent invoke --local "Hello!"

Veya kullanın curl:

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

Veya PowerShell'de:

(Invoke-WebRequest -Uri http://localhost:8088/responses -Method POST -ContentType "application/json" -Body '{"input": "Hello!"}').Content

Foundry'ye dağıtım

Aracınızı yerel olarak doğruladıktan sonra Microsoft Foundry'ye dağıtın:

  1. Kaynakları sağla (henüz bir Foundry projeniz yoksa):

    azd provision

    Bu, bir Foundry örneği, proje, model dağıtımı, Application Insights ve kapsayıcı kayıt defteri içeren bir kaynak grubu oluşturur.

  2. Ajanı dağıt:

    azd deploy

    Bu işlem aracınızı kapsayıcı görüntüsü olarak paketler, Azure Container Registry'a iletir ve Foundry Aracı Hizmeti'ne dağıtır.

Foundry barındırma altyapısı, aşağıdaki ortam değişkenlerini çalışma zamanında aracı kapsayıcınıza otomatik olarak ekler:

Variable Açıklama
FOUNDRY_PROJECT_ENDPOINT Foundry projesinin uç nokta URL'si.
AZURE_AI_MODEL_DEPLOYMENT_NAME Model dağıtım adı (azd ai agent init sırasında yapılandırıldığı zaman).
APPLICATIONINSIGHTS_CONNECTION_STRING Telemetri için Application Insights bağlantı dizesi.

Dağıtıldıktan sonra aracınız, ayrılmış Foundry uçbirimi üzerinden erişilebilir ve Foundry portalından da test edilebilir.

Sonraki Adımlar

Barındırılan aracılar kavramları

  • Last updated on