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ştirmesini kullanarak, en az kodla Foundry Yanıtları veya Çağırmalar protokolü aracılığıyla bir Agent yayımlayabilirsiniz. Python, yerel bir Workflow öğesini, onu bir aracıya dönüştürmeden doğrudan barındırmayı da destekler.

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("FOUNDRY_MODEL")
    ?? 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.get("FOUNDRY_MODEL") or 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. Çağıranın store alanı, üst yanıtın ve ana bilgisayar tarafından yönetilen oturum ile onay durumunun kaydedilip kaydedilmeyeceğini denetler. Ayar, history_source model geçmişini kimin sağladığını bağımsız olarak seçer:

history_source Model geçmiş davranışı
"agent_server" (varsayılan) Ana sistem, saklanan dış Responses dökümünü yeniden oluşturur ve yinelenen geçmişi önlemek için alt hizmet depolamasını devre dışı bırakır.
"service" Ana bilgisayar yalnızca mevcut girdiyi gönderir ve depolayan model hizmetinin devam kimliğini gizli olarak saklar. Kaydedilmiş bir sağlayıcı konuşması, önceki bir yanıttan dallandırılamaz.
"agent" Ana bilgisayar yalnızca geçerli girişi gönderir. Aracının HistoryProvider veya alt hizmetin depolama varsayılanları geçmişi yönetir.

HistoryProvider veya "service"’i yük özellikli bir "agent_server" ile birleştirmeyin. Varsayılan mod, , previous_response_idve conversationgibi conversation_idsabit aşağı akış devamlılık seçeneklerini de reddeder. Özel bir history_source="agent" uygulaması için SupportsAgentRun kullanın.

response_store Oluşturucu parametresi dış Yanıt kalıcılığı için arka ucu seçer. Eski oluşturucu parametresi store, response_store için kullanımdan kaldırılmış bir takma addır; parametrelerin hiçbiri çağıranın istek başına store alanını ayarlamaz. store=false içeren bir istek tek kullanımlıktır: ana bilgisayar tarafından yönetilen durumu kaydetmez, desteklenen alt akış depolamasını devre dışı bırakır ve background=true kullanamaz.

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.

Yanıtlar ana bilgisayarı yerel bilgisayar çağrılarını, ekran görüntülerini ve güvenlik denetimlerini korur. Uygulamanızın istenen eylemleri yürütmesi ve güvenlik denetimlerini açıkça kabul etmesi gerekir. Akışın tamamı için bkz. Yerel bilgisayar kullanımı.

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.

Normal bir temsilci, AgentSession dışında değiştirilebilir durumu koruduğunda callable kullanın. Ana bilgisayarlar, istek kapsamındaki bir ajan üzerinde rastgele alanları değil, yalnızca desteklenen oturum, denetim noktası ve işlev onay depolarını kalıcı hale alır.

Warning

WorkflowAgent üzerinden, agent= gibi bir workflow.as_agent() barındırmak kullanım dışıdır. A WorkflowAgent, çalıştırmalar arasında iş akışı durumunu bellekte tutar, bu nedenle bir örnek hiçbir zaman farklı kullanıcılardan veya konuşmalardan gelen istekleri işlememelidir. workflow= ve istek farkında bir fabrika aracılığıyla iş akışını yerel olarak çalıştırın.

Bir Responses ana bilgisayarını geçirene kadar, her istek için yeni bir iş akışı, yürütücüler, sarmalanmış aracılar, istemciler, sağlayıcılar ve araçlar oluşturan bir fabrika güvenli eski formdur. Konağın denetim noktalarını geri yükleyebilmesi için iş akışı adını ve yürütücü kimliklerini kararlı tutun. Bir Invocations ana bilgisayarı için, aracı barındırma hizmeti iş akışı denetim noktalarını geri yüklemediğinden, bu eski fabrika formu yalnızca durum bilgisi olmayan, tek dönüşlü iş akışlarına uygundur.

Ayrıca, bir entegrasyon istek kimliği taşıdığında veya isteğe özgü kaynakların sahibi olduğunda bir fabrika kullanın. Örneğin, geçerli platform çağrısını veya kullanıcı bağlamını kullandıklarında MCP bağlantıları, Araç Kutuları, beceri sağlayıcıları, Arama istemcileri, Bellek sağlayıcıları ve bunların kimlik bilgilerini fabrika içinde oluşturun. İşlem genelindeki bir MCP bağlantısının yeniden kullanılması, onu açan isteğin kimliğini koruyabilir.

Ana bilgisayar, her istek için fabrika tarafından oluşturulan ajanlara giriş ve çıkış yapar. Agent bağlam tarafından yönetilen istemcileri ve MCP araçlarını yönetir, ancak fabrikanızın oluşturduğu diğer sağlayıcı, aktarım veya kimlik bilgilerini kapatması gerekir. Uygulamanın fabrika dışından sağladığı paylaşılan nesneleri kapatmayın.

Responses ile yerel bir iş akışı oluşturun

Python, workflow= aracılığıyla doğrudan oluşturulmuş bir iş akışını barındırabilir. Yerel iş akışı, geçerli Yanıtlar isteğini türü belirlenmiş bir parse_response başlangıç girişine veya bekleyen yanıtların tamamına eşleyen bir geri çağrı gerektirir:

from pydantic import BaseModel

from agent_framework_foundry_hosting import (
    CheckpointStoreProvider,
    HostedResponseRequest,
    ResponsesHostServer,
    WorkflowTurn,
)


class Ticket(BaseModel):
    text: str


def build_workflow(request: HostedResponseRequest):
    return build_fresh_workflow()


async def parse_response(request: HostedResponseRequest) -> WorkflowTurn[Ticket]:
    items = await request.get_input_items()
    if any(item.get("type") in ("function_call_output", "mcp_approval_response") for item in items):
        return WorkflowTurn(responses=await request.get_workflow_responses())

    text = await request.get_input_text()
    return WorkflowTurn(input=Ticket.model_validate_json(text or ""))


server = ResponsesHostServer(
    workflow=build_workflow,
    parse_response=parse_response,
    checkpoint_store_provider=CheckpointStoreProvider(
        allowed_checkpoint_types=[f"{Ticket.__module__}:{Ticket.__qualname__}"],
    ),
)

Arka plan çalışmalarını duraklatabilen, devam ettirebilen veya geri yükleyebilen iş akışları için istek algılayan zaman uyumlu veya zaman uyumsuz bir fabrika kullanın. Factory'nin yeni oluşturulmuş bir grafiği, yeni değiştirilebilir yürütücüler, aracılar, istemciler, sağlayıcılar ve araçlarla döndürmesi gerekir. Konağın dış yanıtla ilişkili tam denetim noktasını geri yükleyebilmesi için iş akışı adını ve executor kimliklerini kararlı tutun.

Güvenilir platform kullanıcısı ve Foundry korumalı alanı yerel iş akışı durumunu yalıtır. Ana bilgisayar, herhangi bir yanıt yetkisini kullanmadan önce bekleyen tam bir yanıt grubunu doğrular. Eski, kısmi, yinelenen, yeniden oynatılan, kullanıcılar arası ve korumalı alanlar arası yanıtlar iş akışı yürütülmeden önce reddedilir. store=false içeren bir istek iş akışı durumunu kaydetmez ve devam ettirilebilir bir duraklatma döndüremez.

list[Message] kabul eden eski bir iş akışı için, yalnızca geçerli Responses dönüşünü dönüştürmek üzere response_input_messages(request) kullanın. Önceki dış geçmişi yüklemez veya bekleyen iş akışı yanıtlarını çözümlemez. Barındırma agent=workflow.as_agent() geçerli beta sırasında kullanılabilir durumda kalır, ancak kullanımdan kaldırma uyarısı verir. Tam örnekler için yerel Responses 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. Yerel Yanıtlar ve Çağrılar iş akışları, tam devamlılık kontrol noktaları için aynı sağlayıcıyı kullanır. FunctionApprovalStoreProvider bekleyen ajan aracı onayları için bir FoundryFunctionApprovalStore sağlar. Yerleşik iş akışı isteği ve onay yanıtları bunun yerine iş akışı denetim noktalarına bağlıdır.

Foundry'de çalışırken, varsayılan Python ad alanı durumunu platform kullanıcı kimliğine ve Foundry korumalı alan oturum kimliğine göre saklar. Ayrıca her durum işlemi için bir platform çağrı kimliği gerekir. Çağrı kimliği, işlemi yetkilendirir ve onunla ilişkilendirir; bu bir konuşma kimliği değildir ve depolama anahtarının bir parçası değildir.

Yanıtlar için, platformda yapılandırılmış FOUNDRY_AGENT_SESSION_ID korumalı alanı tanımlar ve çağıran tarafından sağlanan farklı bir agent_session_id reddedilir. Çağırmalar için ana bilgisayar, yönlendirilen agent_session_id sorgu parametresini istek bağlamında doğrular. Yapılandırılmamışsa FOUNDRY_AGENT_SESSION_ID sorgu parametresinin mevcut olması ve istek bağlamı ile eşleşmesi gerekir. Eksik, yinelenen veya çakışan değerler, bir SDK yedek kimliği kullanılmak yerine reddedilir.

Bu garantiler varsayılan barındırılan mağazalar için geçerlidir. Özel depo sağlayıcıları, eşdeğer kullanıcı ve korumalı alan yalıtımını uygulamalı, içteki AgentSession.session_id öğesini ana bilgisayar arama anahtarlarından ayrı tutmalı ve eski isteklerin daha yeni anlık görüntülerin üzerine yazamaması için koşullu yazma işlemleri kullanmalıdır. Yeni anahtarlar, koşulsuz ekleme veya güncelleme işlemleri yerine yalnızca oluşturma amaçlı yazma işlemleri kullanmalıdır. ETag korumalı yazma ve silme işlemleriyle Cosmos DB uygulaması için özel depolama örneğine bakın.

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.

Kapsamlandırılmış varsayılan depolar, eski kapsamlandırılmamış agent_sessions, invocation_sessions, denetim noktası veya işlev onayı verilerini okumaz. Eski bir previous_response_id veya konuşma kimliğini yeniden kullanmak yerine yeni bir Responses konuşması başlatın. Çağırmalar, kapsamı belirlenmiş depoda boş bir Agent Framework oturumuyla başlar.

Yüklenen AgentSession kayıtlar ETag koşullarını kullanır. Başka bir istek aynı oturumu önce ilerletirse, eski yazma işlemi daha yeni durumu ezmek yerine başarısız olur. Bu kontrol, ajanın veya aracın yan etkileri için işlem desteği ya da tam olarak bir kez çalıştırma garantisi sağlamaz; bu nedenle uygulamaların çakışan istekleri yine de koordine etmesi gerekir.

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

Arka plandaki dış iş, yoklama için çağıranın görebildiği response.id öğesini kullanır. Varsayılan olarak background_source="agent_server", arka planda yürütmeyi ana bilgisayarda tutar. history_source="service" öğesini yalnızca background_source="provider" ve depolama yapan, devam ettirilebilir bir Responses istemcisi ile ayarlayın. ResponsesServerOptions(resilient_background=True) de ayarlanmışsa, ana bilgisayar sağlayıcı yoklamasını yalnızca özel devamlılık belirtecini kaydettikten sonra yeniden başlatabilir. Bir sonraki belirteç kaydedilmeden önce oluşan bir çökme, bunların yeniden oynatılmasına neden olabileceğinden, yerel araç yan etkilerini idempotent yapın.

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ış
İş akışı kontrol noktası arka plan kurtarması 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.
Sağlayıcıya özel arka plan yanıtları Yanıtları depolayan bir istemciye sahip iş akışı olmayan Agent history_source="service" ve background_source="provider" ayarlayın. Kaydedilen sağlayıcı devam belirteçlerinin konak yeniden başlatmasından sonra da korunması gerekiyorsa resilient_background=True olarak ayarlayın.
Yönlendirilebilir konuşmalar Geçici olarak kullanılamıyor ayarlamayın steerable_conversations=True. Ana sistem, Agent Server SDK reddedilen yönlendirme dönüşlerini güvenli bir şekilde işleyene kadar oluşturma sırasında RuntimeError yükseltir.

Eksiksiz uygulamalar için özel depolama, temel yanıtlar geçmişi ve arka plan ve dayanıklı uzun süreli iş akışı örneklerine bakın.

Barındırılan korumalı alandaki dosyaları okuma

Barındırılan bir korumalı alanın kalıcı $HOME öğesini, genel bir dosya sistemi sınırı olarak değil, istek yönlendirmeli bir kaynak olarak değerlendirin. Yalnızca uygulamanızın açıkça özel bir dizine yüklediği dosyaları kabul edin, geçerli korumalı alan kimliğini doğrulayın ve mutlak yolları, dizin geçişini, bağlantıları, normal dosya olmayan dosyaları ve aşırı büyük veya geçersiz içeriği reddedin.

Responses protokolü için, bir isteği agent_session_id gövde alanını kullanarak barındırılan bir oturuma yönlendirin. Sorgu dizesi seçicisi Çağırmalar içindir. Oturum yüklemeleri ve Toolbox kod yorumlayıcısı dosyaları ayrı kaynaklardır; karşıya yüklenen bir korumalı alan dosyası Toolbox kapsayıcısına otomatik olarak bağlanmaz. Sınırlı UTF-8 okumaları ve yerel ile barındırılan ortama yükleme yönergeleri için oturum dosyaları örneğine bakın.

Denetim isteği seçenekleri

Ana bilgisayar, yerel Responses oluşturma alanlarını Agent Framework çalıştırma seçenekleriyle eşler. Örneğin, max_output_tokens olur max_tokensve parallel_tool_calls olur allow_multiple_tool_calls. extra_body içindeki düzleştirilmiş değerler, çevrilmiş yerel değerleri geçersiz kılar.

Normal aracı çalıştırılmadan önce çağıran model seçeneklerini kaldırmak veya değiştirmek için eşzamanlı ya da eşzamansız prepare_options(request, options) kancasını kullanın. Hook, ana bilgisayar tarafından denetlenen kimlik, depolama, devam ve taşıma alanlarını ayarlayamaz. Çalışma zamanında model seçeneklerini kabul edemeyen özel bir SupportsAgentRun uygulaması için, "ignore" değerini "error" (varsayılan), unsupported_options veya "warn" olarak ayarlayı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.

Ana makineniz beklenen yetkilendirme kaynaklarını biliyorsa, onay bağlantılarını allowed_oauth_consent_origins ile kısıtlayın:

server = ResponsesHostServer(
    agent,
    allowed_oauth_consent_origins=[
        "https://logic-region.consent.azure-apihub.net",
        "https://auth.partner.example",
    ],
)

İzin verilenler listesinin atlanması, hedef kaynağı kısıtlamadan mutlak HTTPS doğrulamasını korur. Boş bir liste verilmesi, tüm onay bağlantılarının reddedilmesine neden olur. Yalnızca tam HTTPS çıkış noktalarını yapılandırın; yol, sorgu veya parça içeren girdiler reddedilir.

Ç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.get("FOUNDRY_MODEL") or 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.

Invocations, barındırıldığında, Durumu kalıcı hale getirme ve uzun süreli konuşmaları işleme bölümünde açıklanan doğrulanmış istek kapsamını kullanır. 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, mevcut tek kullanıcılı depolama davranışlarını sürdürür.

Invocations ile yerel bir iş akışı barındırın

Yerel bir iş akışını barındırmak için workflow= açık bir geri çağırma ve parse_request geçirin. Geri çağırma işlevi, uygulama JSON şemasına sahip ve türlendirilmiş giriş veya tam bekleyen yanıt grubuyla bir WorkflowTurn döndürür:

from pydantic import BaseModel
from starlette.requests import Request

from agent_framework_foundry_hosting import (
    CheckpointStoreProvider,
    InvocationsHostServer,
    WorkflowTurn,
)


class Ticket(BaseModel):
    ticket_id: str
    question: str


class TicketDecision(BaseModel):
    approved: bool


def build_workflow(_request: Request):
    return build_fresh_workflow()


async def parse_request(request: Request) -> WorkflowTurn[Ticket]:
    payload = await request.json()
    stream = payload.get("stream", False)

    if "responses" in payload:
        decisions = {
            request_id: TicketDecision.model_validate(value)
            for request_id, value in payload["responses"].items()
        }
        return WorkflowTurn(responses=decisions, stream=stream)

    ticket = Ticket.model_validate(payload)
    return WorkflowTurn(input=ticket, stream=stream)


server = InvocationsHostServer(
    workflow=build_workflow,
    parse_request=parse_request,
    checkpoint_store_provider=CheckpointStoreProvider(
        allowed_checkpoint_types=[
            f"{Ticket.__module__}:{Ticket.__qualname__}",
            f"{TicketDecision.__module__}:{TicketDecision.__qualname__}",
        ],
    ),
)

İş akışının kaydettiği her özel uygulama türünü denetim noktası sağlayıcısının allowed_checkpoint_types listesine ekleyin.

Barındırılan iş akışları, kararlı iş akışı ve yürütücü kimliklerine sahip yeni bir oluşturulmuş graf döndüren istek farkında bir fabrika gerektirir. Doğrudan oluşturulmuş bir iş akışı yalnızca duraklatılmayan yerel, tek seferlik bir çalıştırma için kullanılabilir.

Akış dışı iş akışı yanıtları, bir output olay listesiyle uygulama JSON'unu kullanır. Akış, çerçeveli output ve request_info olaylarını yayar; ardından done yalnızca tam iş akışı imleci kaydedildikten sonra gelir. Akışla gelen çıktıyı done gerçekleşene kadar geçici olarak kabul edin. Yerel iş akışları legacy_wire_format=True öğesini desteklemez.

Ana makine, yanıtları güvenilen kullanıcı ve korumalı alan kapsamında tam olarak bekleyen denetim noktasına göre doğrular. Bir iş akışının bekleyen birden çok isteği varsa, isteklerin tümünü tek seferde yanıtlayın. Çalıştırılabilir ayrıştırıcı, türlendirilmiş ticket iş akışı, denetim noktası türü izin listesi ve JSON/SSE örnekleri için native Invocations iş akışı örneğine bakın.

Çağrı isteklerini ve yanıtlarını özelleştirme

Varsayılan olarak, message bir dize POST /invocations, isteğe bağlı bir options nesnesi ve isteğe bağlı bir Boole stream değeri içeren bir JSON nesnesini kabul eder. Uygulamaya özel bir yükü kabul etmek için, parse_request döndüren eşzamanlı ya da eşzamansız bir InvocationRun(messages, options, stream) geri çağırma işlevi iletin. prepare_options, aracı çalıştırmadan önce çağıran oluşturma seçeneklerinin bir kopyasını filtrelemek veya değiştirmek için kullanın.

Ana sistem, kanca çıktısını doğrular ve platform kimliği, depolama, sürdürme ve aracı yürütme kontrollerini reddeder. Çalışma zamanı seçeneklerini kabul etmeyen aracılar için unsupported_options değerini "warn" (varsayılan), "ignore" veya "error" olarak ayarlayın. Tam bir uygulama için Invocations ayrıştırıcısı örneğine bakın.

Akışsız başarı durumunda JSON, {"response": "..."} biçiminde döndürülür. Akış, sunucu tarafından gönderilen olayları kullanır: bir veya daha fazla event: delta çerçevesinin ardından, başarılı olursa event: done, başarısız olursa event: error gelir. Bir akış, bir hatadan önce delta gönderebilir; bu nedenle istemciler başarılı tamamlanma göstergesi olarak bir deltayı değil, done etiketini kabul etmelidir. Ana bilgisayar, yanıt akışını sonlandırıp AgentSession ögesini kalıcı olarak kaydettikten sonra done yayar. Bu session_id, serileştirilmiş AgentSession.session_id değil, platform korumalı alan rota kimliğidir.

legacy_wire_format=True ayarını yalnızca önceki düz metin yanıtını ve ham metin parçacığı akışını gerektiren mevcut istemcilerin geçişini yaparken kullanın. Bu uyumluluk modu kullanım dışıdır ve hataları başarılı metne dönüştürmez. Ana süreç, aynı oturumdaki istekleri yalnızca tek bir süreç içinde serileştirir; harici araçların etkilerinden sonra bile süreçler arası compare-and-swap çakışması yine de oluşabilir.

Ç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.get("FOUNDRY_MODEL") or 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 örneklerine veya C# örneklerine 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 bir örneğin azure.yaml dosyasını kullanarak ilklendirin. Bu kılavuz için kapsayıcı dağıtımını kullanın:

mkdir my-hosted-agent && cd my-hosted-agent
azd ai agent init -t <path-to-azure.yaml> --src . --deploy-mode container

Tip

azure.yaml değerini, örneğin örneğin <path-to-azure.yaml> proje belgesi için yerel bir yol veya desteklenen bir GitHub URL’si ile değiştirin.

Ortam değişkenlerini ayarlama

export FOUNDRY_PROJECT_ENDPOINT="https://<account>.services.ai.azure.com/api/projects/<project>"
export FOUNDRY_MODEL="<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 azd ai agent init sırasında yapılandırılan, azd tarafından yönetilen model dağıtım adı. Python kodu FOUNDRY_MODEL yerel olanı tercih edebilir ve bu barındırılan değere geri dönebilir.
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ı

  • Son güncelleştirme: