Tartós bővítmény

Az Microsoft Agent Framework durable bővítménye tartós végrehajtást biztosít az ügynököknek, a többügynök-vezényléseknek és Microsoft Agent Framework-munkafolyamatoknak. Használatával megőrizheti az ügynök-munkameneteket, az ellenőrzőpont-vezénylést és a munkafolyamat előrehaladását, helyreállíthatja a hibákat, és skálázhatja a feladatokat az elosztott gazdagépeken anélkül, hogy módosítaná az ügynök alapvető logikáját.

A bővítmény két üzemeltetési modellt támogat C# és Python:

  • Azure Functions felügyelt, kiszolgáló nélküli üzemeltetéshez a Azure Functions programozási modellel.
  • Saját számítási/ saját üzemeltetésű , tartós ügynökök és munkafolyamatok futtatásához saját feldolgozói folyamatban, szolgáltatásban, tárolóban, Kubernetes-környezetben vagy meglévő alkalmazásinfrastruktúra esetén.

Megjegyzés:

Hamarosan megjelenik a Durable Extension támogatása. A go-üzemeltetéssel kapcsolatban tekintse meg az A2A-üzemeltetést és az Agent Framework Go-adattárat.

Overview

A Tartós ügynökök az Ügynök keretrendszer programozási modelljét a Durable Task-infrastruktúrával, például a Durable Task Schedulerrel kombinálva olyan ügynököket hozhatnak létre, amelyek:

  • Állapot automatikus megőrzése kérések és feldolgozói végrehajtások között
  • Folytatás a hibák után a beszélgetési környezet elvesztése vagy a befejezett munka ismétlése nélkül
  • Skálázás elosztott, állapot nélküli feldolgozók között igény szerint
  • Többügynök-munkafolyamatok vezénylése megbízható végrehajtási garanciával
  • A gráfalapú munkafolyamat-modellel létrehozott Checkpoint Agent Framework-munkafolyamatok
  • Emberi bemeneti vagy külső események szüneteltetése számítási vagy modell jogkivonatok használata nélkül várakozás közben
  • A válaszok megbízható streamelése megbízhatóan, ha megbízható streamközvetítővel van konfigurálva, például Redis
  • Munkamenet életciklusának kezelése a munkamenet élettartamának (TTL) törlésével és irányítópult-alapú monitorozással

Mikor érdemes tartós ügynököket használni?

Szükség esetén válasszon tartós ügynököket:

  • Állandó beszélgetési állapot: Az ügynök munkamenetei túlélik a folyamat összeomlásait, újraindításait és vertikális felskálázási eseményeit
  • Összetett vezénylések: Több ügynök koordinálása determinisztikus, megbízható munkafolyamatokkal, amelyek napokig vagy hetekig futtathatók
  • Eseményvezérelt vezénylés: Integrálás eseményindítókkal, üzenetsorokkal, webhookokkal, időzítőkkel vagy meglévő alkalmazáseseményekkel
  • Automatikus beszélgetési állapot: Az ügynök beszélgetési előzményei automatikusan kezelhetők és megmaradnak anélkül, hogy explicit állapotkezelésre van szükség a kódban
  • Durable Agent Framework-munkafolyamatok: Gráfalapú Microsoft Agent Framework-munkafolyamatok tartóssá tétele az egyes lépések ellenőrzéséhez és folytatásához
  • Hosszú élettartamú munkamenetek: Az inaktív munkamenetek automatikus eltávolításához a munkamenetek élettartamának (TTL) törlése során elérhető maradnak a hasznos beszélgetések.
  • Megbízható valós idejű válaszok: A jogkivonat kimenetének folyamatos streamelése olyan alkalmazásokhoz, amelyek valós idejű UX-t igényelnek kézbesítési garanciával

Ez az üzemeltetési megközelítés eltér a felügyelt szolgáltatásalapú ügynökkezeléstől (például a Foundry Agent Service-től), amely teljes körűen felügyelt infrastruktúrát biztosít anélkül, hogy a feldolgozó gazdagépek üzembe helyezését vagy kezelését kellene megkövetelnie. A tartós ügynökök akkor ideálisak, ha a kód első üzembe helyezésének rugalmasságára és a tartós állapotkezelésre van szüksége.

Üzemeltetési modell kiválasztása

Futtatási modell Válassza ki, ha szükséges
Azure Functions Felügyelt, kiszolgáló nélküli üzemeltetési modell; beépített vertikális felskálázás és skálázás nullára; Azure Functions eseményindítók és kötések; A Functions programozási modell által létrehozott HTTP-végpontok; az MCP-kiszolgáló eseményindítója; és minimális gazdainfrastruktúra-kezelés.
Saját számítás /saját üzemeltetésű A gazdagépfolyamat, az üzembehelyezési környezet, a futtatókörnyezet életciklusa, az infrastruktúra, a hálózatkezelés, a hitelesítés vagy a meglévő alkalmazással vagy szolgáltatással való integráció további szabályozása. Használja ezt a modellt tárolókhoz, Kuberneteshez, hosszan futó feldolgozókhoz, konzolalkalmazásokhoz, egyéni szolgáltatásokhoz vagy nem Functions-alapú üzemeltetési környezetekhez.

Az Azure Functions Flex Consumption üzemeltetési csomagban üzemeltetett ügynökök több ezer példányra vagy nullára skálázhatók, amikor nincsenek használatban, így csak a szükséges számítási teljesítményért kell fizetnie. A saját üzemeltetésű forgatókönyvekben a saját gazdagépe szabályozza a folyamat élettartamát, a skálázást, a hálózatkezelést és az üzembe helyezést.

Kezdő lépések

Egy .NET projektben válassza ki az üzemeltetési modell csomagkészletét.

Azure Functions üzemeltetéshez adja hozzá a Azure Functions integrációs csomagot és a Functions feldolgozócsomagokat.

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

Megjegyzés:

Ezen csomagok mellett győződjön meg arról, hogy a projekt a Microsoft.Azure.Functions.Worker csomag 2.2.0-s vagy újabb verzióját használja.

Saját számítási üzemeltetés esetén adja hozzá az alapszintű Durable Task integrációs csomagot és a gazdagép által használt Durable Task Scheduler feldolgozó/ügyfélcsomagokat:

dotnet add package Microsoft.Agents.AI.DurableTask --prerelease
dotnet add package Microsoft.DurableTask.Client.AzureManaged
dotnet add package Microsoft.DurableTask.Worker.AzureManaged
dotnet add package Microsoft.Extensions.Hosting

Egy Python projektben válassza ki az üzemeltetési modellhez tartozó csomagot.

Az Azure Functions üzemeltetéshez telepítse a Azure Functions integrációs csomagot.

pip install azure-identity
pip install agent-framework-azurefunctions --pre

Saját számítási üzemeltetéshez telepítse a Durable Task integrációs csomagot.

pip install azure-identity
pip install agent-framework-durabletask --pre

Azure Functions üzemeltetés

A Durable Extension használatával üzembe helyezheti és üzemeltetheti Microsoft Agent Framework-ügynököket a Azure Functions beépített HTTP-végpontokkal és vezénylésalapú meghívással. Az Azure Functions eseményvezérelt, hívásonkénti fizetéses díjszabást biztosít automatikus skálázással és minimális infrastruktúra-kezeléssel.

Ha tartós ügynököt konfigurál a Azure Functions, a bővítmény automatikusan HTTP-végpontokat hoz létre az ügynök számára, és kezeli az alapul szolgáló infrastruktúrát a beszélgetési állapot tárolásához, az egyidejű kérések kezeléséhez és a többügynökös munkafolyamatok koordinálásához. A Azure Functions üzemeltetési integráció olyan funkciókra vonatkozó kényelmi funkciókat is biztosít, mint például az üzenetek küldéséhez, az állapot ellenőrzéséhez és a munkamenetek kezeléséhez létrehozott REST API-k, valamint az olyan eseményindítók, mint az MCP-kiszolgáló eseményindítója az ügynökök mcp-kiszolgálóként való üzemeltetéséhez eseményindító-ragasztó írása nélkül.

using System;
using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Hosting.AzureFunctions;
using Microsoft.Azure.Functions.Worker.Builder;
using Microsoft.Extensions.Hosting;

var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT");
var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT") ?? "gpt-4o-mini";

// Create an AI agent following the standard Microsoft Agent Framework pattern
AIAgent agent = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
    .AsAIAgent(
        model: deploymentName,
        instructions: "You are good at telling jokes.",
        name: "Joker");

// Configure the function app to host the agent with durable thread management
// This automatically creates HTTP endpoints and manages state persistence
using IHost app = FunctionsApplication
    .CreateBuilder(args)
    .ConfigureFunctionsWebApplication()
    .ConfigureDurableAgents(options =>
        options.AddAIAgent(agent)
    )
    .Build();
app.Run();

Warning

DefaultAzureCredential a fejlesztéshez kényelmes, de a termelési környezetben gondos megfontolást igényel. Éles környezetben fontolja meg egy adott hitelesítő adat (pl. ManagedIdentityCredential) használatát a késési problémák elkerülése, a hitelesítő adatok nem szándékos próbálgatásának és a tartalék mechanizmusokból eredő esetleges biztonsági kockázatok elkerülése érdekében.

import os
from agent_framework.azure import AgentFunctionApp
from agent_framework.openai import OpenAIChatCompletionClient
from azure.identity import DefaultAzureCredential

endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
deployment_name = os.getenv("AZURE_OPENAI_CHAT_COMPLETION_MODEL", "gpt-4o-mini")
api_version = os.getenv("AZURE_OPENAI_API_VERSION")

# Create an AI agent following the standard Microsoft Agent Framework pattern
agent = OpenAIChatCompletionClient(
    azure_endpoint=endpoint,
    model=deployment_name,
    api_version=api_version,
    credential=DefaultAzureCredential()
).as_agent(
    instructions="You are good at telling jokes.",
    name="Joker"
)

# Configure the function app to host the agent with durable thread management
# This automatically creates HTTP endpoints and manages state persistence
app = AgentFunctionApp(agents=[agent])

Saját számítás / saját üzemeltetésű üzemeltetés

Használja a saját számítási üzemeltetést, ha a Durable Extension funkcióit a Azure Functions programozási modell használata nélkül szeretné használni. Ebben a modellben a folyamat elindít egy durable task workert, regisztrálja a tartós ügynököket vagy munkafolyamatokat, és csatlakozik egy tartós feladatütemező háttérrendszeréhez. Az ügyfélkód ugyanabban a folyamatban vagy egy külön szolgáltatásban futtatható.

A saját üzemeltetésű feldolgozók ugyanazokat az alapvető Durable Extension-képességeket használják, mint Azure Functions üzemeltetés: ellenőrzőpontok és újrakezdés, determinisztikus ügynökvezénylés, tartós ügynök-keretrendszer munkafolyamatok, human-in-the-loop várakozások, megbízható streamelés, inaktív munkamenetek törlése, irányítópult láthatósága és elosztott végrehajtás állapot nélküli feldolgozópéldányok között. A gazdagép feladata saját API-k, életciklus-kezelés, hálózatkezelés, hitelesítés és üzembe helyezési modell felfedése.

Konfigurálja a gazdagépet az alapszintű Durable Task integrációs csomaggal. A ConfigureDurableAgents használata tartós ügynökökhöz és ConfigureDurableWorkflows gráfalapú Microsoft Agent Framework-munkafolyamatokhoz.

string connectionString = Environment.GetEnvironmentVariable("DURABLE_TASK_SCHEDULER_CONNECTION_STRING")
    ?? "Endpoint=http://localhost:8080;TaskHub=default;Authentication=None";

IHost host = Host.CreateDefaultBuilder(args)
    .ConfigureServices(services =>
    {
        services.ConfigureDurableAgents(
            options => options.AddAIAgent(agent),
            workerBuilder: builder => builder.UseDurableTaskScheduler(connectionString),
            clientBuilder: builder => builder.UseDurableTaskScheduler(connectionString));
    })
    .Build();

await host.StartAsync();

Futtatható saját üzemeltetésű példákért tekintse meg a .NET Durable Agents konzolmintákat és .NET Durable Workflows konzolmintákat.

A Durable Task integrációs csomag használatával futtathat egy feldolgozói folyamatot, amely ügynököket regisztrál, és figyeli a kéréseket. Az ügyfélkód ugyanahhoz a Durable Task Scheduler feladatközponthoz csatlakozhat egy másik folyamatból.

from agent_framework.azure import DurableAIAgentWorker
from durabletask.azuremanaged.worker import DurableTaskSchedulerWorker

worker = DurableTaskSchedulerWorker(
    host_address="http://localhost:8080",
    secure_channel=False,
    taskhub="default",
)

agent_worker = DurableAIAgentWorker(worker)
agent_worker.add_agent(agent)

worker.start()

Tekintse meg a Python Durable Task-mintákat a feldolgozó-ügyfél példákhoz, beleértve az együgynök-üzemeltetést, a többügynökös útválasztást, a megbízható streamelést, a vezénylési láncolást, az egyidejűséget, a feltételes feltételeket és az emberi-in-the-loop mintákat.

Durable Agent Framework-munkafolyamatok

A tartósság nem korlátozódik a tartós vezénylésekre. Microsoft gráfalapú munkafolyamat-modellel létrehozott Agent Framework-munkafolyamatok is tartóssá tehetők. A Durable Extension ellenőrzőpontjai munkafolyamat-végrehajtást végeznek, így a végrehajtási és ügynöki lépések nem ismétlődnek a folyamat újraindítása vagy sikertelensége után.

Használjon tartós vezényléseket, ha kódalapú elágaztatással, időzítőkkel, tevékenységekkel és külső eseményekkel való imperatív koordinációt szeretne. Tartós Agent Framework-munkafolyamatokat akkor használjon, ha a végrehajtók és ügynökök deklaratív gráfját szeretné használni gépelt útválasztással, ki-ki-/ventilátor-in, feltételes élekkel, munkafolyamat-eseményekkel, megosztott állapottal, al-munkafolyamatokkal vagy emberi-in-the-loop kérésportokkal.

Megjegyzés:

A Durable Agent Framework munkafolyamatai eltérnek az ellenőrzőpont-tárolótól a standard munkafolyamatokban. A Checkpoint Storage segít folytatni a munkafolyamat-futtatást az Agent Framework futtatókörnyezetében. A Durable Extension a durable task infrastruktúrán futtatja a munkafolyamatot, így a munkafolyamat előrehaladása ellenőrizve van, és helyreáll az elosztott tartós feldolgozók között. A szokásos munkafolyamat-ellenőrzőpontokkal kapcsolatban lásd: Ellenőrzőpontok és folytatás.

Gráfalapú munkafolyamatok regisztrálása ConfigureDurableWorkflows saját üzemeltetésű alkalmazásokhoz vagy ConfigureDurableWorkflows a Functions alkalmazásszerkesztőben Azure Functions üzemeltetéshez.

Tekintse meg a .NET Durable Workflows Azure Functions mintákat és .NET Durable Workflows konzolmintákat.

Tartós munkafolyamat-minták érhetők el Azure Functions üzemeltetéshez, beleértve a megosztott állapotot, a megosztott állapot nélküli állapotot, a párhuzamos munkafolyamat-végrehajtást és az emberi munkafolyamatokat.

Tekintse meg a Python Azure Functions mintákat tartós ügynököt, vezénylést, MCP-kiszolgálót és munkafolyamat-példákat.

Samples

Nyelv Futtatási modell Samples
C# Azure Functions .NET Tartós ügynökök – Azure Functions, .NET Tartós munkafolyamatok – Azure Functions
C# Saját számítás /saját üzemeltetésű .NET Tartós ügynökök – Konzolalkalmazások, .NET Tartós munkafolyamatok – Konzolalkalmazások
Python Azure Functions Python Azure Functions minták
Python Saját számítás /saját üzemeltetésű Python Tartós feladatminták
Go Jelenleg nem támogatott A legújabb állapotot az Agent Framework Go-adattárában tekinthet meg.

Állapotalapú ügynökszálak beszélgetési előzményekkel

Az ügynökök állandó szálakat tartanak fenn, amelyek több interakciót is túlélnek. Minden szál egyedi szálazonosítóval van azonosítva, és a teljes beszélgetési előzményeket a Durable Task infrastruktúra által felügyelt tartós tárolóban tárolja, például a Durable Task Schedulerben.

Ez a minta lehetővé teszi a beszélgetés folytonosságát, ahol az ügynök állapota megmarad, még akkor is, ha a folyamat összeomlik vagy újraindul, így a felhasználói szálak között teljes mértékben megőrizhető a beszélgetés előzményei. A tartós tárterület biztosítja, hogy még akkor is zökkenőmentesen folytatódjon a beszélgetés, ha egy gazdagépfolyamat újraindul vagy egy másik feldolgozópéldányon folytatja a munkát.

A munkamenetek élettartamának (TTL) megtisztítása olyan számítási feladatokhoz, amelyek aktív használat közben tartós folytonosságot igényelnek, de automatikusan törlik az üresjárati beszélgetéseket. A TTL-alapú törlés megakadályozza, hogy a nem használt munkamenetek és beszélgetési előzmények határozatlan ideig halmozódtak fel az aktív munkamenet állapotának megőrzése mellett.

Az alábbi Azure Functions példa több HTTP-kérést mutat be ugyanahhoz a szálhoz, és bemutatja, hogyan tart fenn a beszélgetési környezet. A saját üzemeltetésű alkalmazásokban használja a Durable Task ügyfél API-kat a saját folyamatából vagy szolgáltatásából.

# First interaction - start a new thread
curl -X POST https://your-function-app.azurewebsites.net/api/agents/Joker/run \
  -H "Content-Type: text/plain" \
  -d "Tell me a joke about pirates"

# Response includes thread ID in x-ms-thread-id header and joke as plain text
# HTTP/1.1 200 OK
# Content-Type: text/plain
# x-ms-thread-id: @dafx-joker@263fa373-fa01-4705-abf2-5a114c2bb87d
#
# Why don't pirates shower before they walk the plank? Because they'll just wash up on shore later!

# Second interaction - continue the same thread with context
curl -X POST "https://your-function-app.azurewebsites.net/api/agents/Joker/run?thread_id=@dafx-joker@263fa373-fa01-4705-abf2-5a114c2bb87d" \
  -H "Content-Type: text/plain" \
  -d "Tell me another one about the same topic"

# Agent remembers the pirate context from the first message and responds with plain text
# What's a pirate's favorite letter? You'd think it's R, but it's actually the C!

Az ügynök állapotának tartós tárolása biztosított, lehetővé téve az elosztott végrehajtást több példányon. Bármely példány folytathatja az ügynök végrehajtását megszakítások vagy hibák után, biztosítva a folyamatos működést.

Megbízható streamelés

A Durable Extension támogatja a megbízható streamelést olyan alkalmazásokhoz, amelyek valós idejű jogkivonat-kézbesítést igényelnek tartós kézbesítési garanciával. A streamelés mindkét üzemeltetési modellben használható az alapbővítménnyel, de az elosztott gazdagépeknek megbízható streamközvetítőre van szükségük, például a Redisre, így a jogkivonat-streamek konzisztensen kézbesíthetők a folyamat újraindítása, az újracsatlakozások vagy a feldolgozói módosítások során.

Használjon megbízható streamelést, ha a felhasználói élmény növekményes válaszoktól függ, de a számítási feladatnak továbbra is tartós végrehajtási szemantikára van szüksége. Futtatható példákért tekintse meg a megbízható streamelési mintákat tartalmazó Python Durable Task-mintákat.

Determinisztikus többügynök-vezénylések

A Durable Extension olyan determinisztikus munkafolyamatokat támogat, amelyek több ügynököt koordinálnak a Durable Task vezénylésével. A Azure Functions ezek Durable Functions vezényléseket használnak; a saját számítási gazdagépeken a konfigurált Durable Task feldolgozón és ügyfélen keresztül futnak.

Az vezénylések olyan kódalapú munkafolyamatok, amelyek több műveletet (például ügynökhívásokat, külső API-hívásokat vagy időzítőket) koordinálnak megbízható módon. A determinisztikus azt jelenti, hogy a vezénylési kód ugyanúgy fut, amikor egy hiba után újrajátssza a munkafolyamatokat, megbízhatóvá és hibakeresővé téve – a vezénylés előzményeinek visszajátszásakor pontosan láthatja, hogy mi történt az egyes lépésekben.

A vezénylések megbízhatóan hajtanak végre, túlélik az ügynökhívások közötti hibákat, és kiszámítható és megismételhető folyamatokat biztosítanak. Így ideálisak olyan összetett többügynök-forgatókönyvekhez, ahol garantált végrehajtási sorrendre és hibatűrésre van szüksége.

Szekvenciális vezénylések

A szekvenciális többügynök-mintában a specializált ügynökök meghatározott sorrendben hajtanak végre, ahol az egyes ügynökök kimenete befolyásolhatja a következő ügynök végrehajtását. Ez a minta az ügynökválaszok alapján támogatja a feltételes logikát és az elágaztatást.

Ha ügynököket használ a vezénylésekben, az context.GetAgent() API-val kell lekérnie egy DurableAIAgent példányt, amely a szabványos AIAgent típus egy speciális alosztálya, amely az egyik regisztrált ügynököt burkolja. A DurableAIAgent burkoló biztosítja, hogy az ügynökhívásokat megfelelően nyomon kövesse és ellenőrizze a tartós vezénylési keretrendszer.

using Microsoft.Azure.Functions.Worker;
using Microsoft.DurableTask;
using Microsoft.Agents.AI.DurableTask;

[Function(nameof(SpamDetectionOrchestration))]
public static async Task<string> SpamDetectionOrchestration(
    [OrchestrationTrigger] TaskOrchestrationContext context)
{
    Email email = context.GetInput<Email>();

    // Check if the email is spam
    DurableAIAgent spamDetectionAgent = context.GetAgent("SpamDetectionAgent");
    AgentSession spamSession = await spamDetectionAgent.CreateSessionAsync();

    AgentResponse<DetectionResult> spamDetectionResponse = await spamDetectionAgent.RunAsync<DetectionResult>(
        message: $"Analyze this email for spam: {email.EmailContent}",
        session: spamSession);
    DetectionResult result = spamDetectionResponse.Result;

    if (result.IsSpam)
    {
        return await context.CallActivityAsync<string>(nameof(HandleSpamEmail), result.Reason);
    }

    // Generate response for legitimate email
    DurableAIAgent emailAssistantAgent = context.GetAgent("EmailAssistantAgent");
    AgentSession emailSession = await emailAssistantAgent.CreateSessionAsync();

    AgentResponse<EmailResponse> emailAssistantResponse = await emailAssistantAgent.RunAsync<EmailResponse>(
        message: $"Draft a professional response to: {email.EmailContent}",
        session: emailSession);

    return await context.CallActivityAsync<string>(nameof(SendEmail), emailAssistantResponse.Result.Response);
}

Ha ügynököket használ a vezénylésekben, a app.get_agent() módszerrel létre kell hoznia egy tartós ügynökpéldányt, amely programozási szempontból speciális burkoló az egyik regisztrált ügynök köré. A tartós ügynökburkoló biztosítja, hogy az ügynökhívásokat megfelelően nyomon kövesse és ellenőrizze a tartós vezénylési keretrendszer.

import azure.durable_functions as df
from typing import cast
from agent_framework.azure import AgentFunctionApp
from pydantic import BaseModel

class SpamDetectionResult(BaseModel):
    is_spam: bool
    reason: str

class EmailResponse(BaseModel):
    response: str

app = AgentFunctionApp(agents=[spam_detection_agent, email_assistant_agent])

@app.orchestration_trigger(context_name="context")
def spam_detection_orchestration(context: df.DurableOrchestrationContext):
    email = context.get_input()

    # Check if the email is spam
    spam_agent = app.get_agent(context, "SpamDetectionAgent")
    spam_thread = spam_agent.create_session()

    spam_result_raw = yield spam_agent.run(
        messages=f"Analyze this email for spam: {email['content']}",
        session=spam_thread,
        options={"response_format": SpamDetectionResult},
    )
    spam_result = cast(SpamDetectionResult, spam_result_raw.get("structured_response"))

    if spam_result.is_spam:
        result = yield context.call_activity("handle_spam_email", spam_result.reason)
        return result

    # Generate response for legitimate email
    email_agent = app.get_agent(context, "EmailAssistantAgent")
    email_thread = email_agent.create_session()

    email_response_raw = yield email_agent.run(
        messages=f"Draft a professional response to: {email['content']}",
        session=email_thread,
        options={"response_format": EmailResponse},
    )
    email_response = cast(EmailResponse, email_response_raw.get("structured_response"))

    result = yield context.call_activity("send_email", email_response.response)
    return result

A vezénylések több ügynök munkáját koordinálják, és túlélik az ügynökhívások közötti hibákat. A vezénylési környezet metódusokat biztosít a vezényléseken belüli üzemeltetett ügynökök lekérésére és azokkal való interakcióra.

Párhuzamos vezénylések

A párhuzamos többügynök-mintában egyszerre több ügynököt kell végrehajtania, majd összesítenie az eredményeket. Ez a minta hasznos lehet különböző perspektívák összegyűjtéséhez vagy független altevékenységek egyidejű feldolgozásához.

using Microsoft.Azure.Functions.Worker;
using Microsoft.DurableTask;
using Microsoft.Agents.AI.DurableTask;

[Function(nameof(ResearchOrchestration))]
public static async Task<string> ResearchOrchestration(
    [OrchestrationTrigger] TaskOrchestrationContext context)
{
    string topic = context.GetInput<string>();

    // Execute multiple research agents in parallel
    DurableAIAgent technicalAgent = context.GetAgent("TechnicalResearchAgent");
    DurableAIAgent marketAgent = context.GetAgent("MarketResearchAgent");
    DurableAIAgent competitorAgent = context.GetAgent("CompetitorResearchAgent");

    // Start all agent runs concurrently
    Task<AgentResponse<TextResponse>> technicalTask = 
        technicalAgent.RunAsync<TextResponse>($"Research technical aspects of {topic}");
    Task<AgentResponse<TextResponse>> marketTask = 
        marketAgent.RunAsync<TextResponse>($"Research market trends for {topic}");
    Task<AgentResponse<TextResponse>> competitorTask = 
        competitorAgent.RunAsync<TextResponse>($"Research competitors in {topic}");

    // Wait for all tasks to complete
    await Task.WhenAll(technicalTask, marketTask, competitorTask);

    // Aggregate results
    string allResearch = string.Join("\n\n", 
        technicalTask.Result.Result.Text,
        marketTask.Result.Result.Text,
        competitorTask.Result.Result.Text);

    DurableAIAgent summaryAgent = context.GetAgent("SummaryAgent");
    AgentResponse<TextResponse> summaryResponse = 
        await summaryAgent.RunAsync<TextResponse>($"Summarize this research:\n{allResearch}");

    return summaryResponse.Result.Text;
}

import azure.durable_functions as df
from agent_framework.azure import AgentFunctionApp

app = AgentFunctionApp(agents=[technical_agent, market_agent, competitor_agent, summary_agent])

@app.orchestration_trigger(context_name="context")
def research_orchestration(context: df.DurableOrchestrationContext):
    topic = context.get_input()

    # Execute multiple research agents in parallel
    technical_agent = app.get_agent(context, "TechnicalResearchAgent")
    market_agent = app.get_agent(context, "MarketResearchAgent")
    competitor_agent = app.get_agent(context, "CompetitorResearchAgent")

    technical_task = technical_agent.run(messages=f"Research technical aspects of {topic}")
    market_task = market_agent.run(messages=f"Research market trends for {topic}")
    competitor_task = competitor_agent.run(messages=f"Research competitors in {topic}")

    # Wait for all tasks to complete
    results = yield context.task_all([technical_task, market_task, competitor_task])

    # Aggregate results
    all_research = "\n\n".join([r.get('response', '') for r in results])

    summary_agent = app.get_agent(context, "SummaryAgent")
    summary = yield summary_agent.run(messages=f"Summarize this research:\n{all_research}")

    return summary.get('response', '')

A párhuzamos végrehajtás a tevékenységek listájával lesz nyomon követve. Az automatikus ellenőrzőpont-beállítás biztosítja, hogy a befejezett ügynökvégrehajtások ne ismétlődzenek vagy vesszenek el, ha hiba történik az összesítés során.

Human-in-the-loop vezénylések

A determinisztikus ügynökvezérlések szüneteltethetők az emberi bemenet, jóváhagyás vagy felülvizsgálat várakozása közben, anélkül, hogy számítási erőforrásokat fogyasztanának. A tartós végrehajtás lehetővé teszi a vezénylések számára, hogy napokig vagy akár hetekig várják az emberi válaszokat. Kiszolgáló nélküli üzemeltetéssel kombinálva a rendszer a várakozási időszak alatt az összes számítási erőforrást lefuttatja, így kiküszöböli a számítási költségeket, amíg az ember meg nem adja a bemenetét.

using Microsoft.Azure.Functions.Worker;
using Microsoft.DurableTask;
using Microsoft.Agents.AI.DurableTask;

[Function(nameof(ContentApprovalWorkflow))]
public static async Task<string> ContentApprovalWorkflow(
    [OrchestrationTrigger] TaskOrchestrationContext context)
{
    string topic = context.GetInput<string>();

    // Generate content using an agent
    DurableAIAgent contentAgent = context.GetAgent("ContentGenerationAgent");
    AgentResponse<GeneratedContent> contentResponse = 
        await contentAgent.RunAsync<GeneratedContent>($"Write an article about {topic}");
    GeneratedContent draftContent = contentResponse.Result;

    // Send for human review
    await context.CallActivityAsync(nameof(NotifyReviewer), draftContent);

    // Wait for approval with timeout
    HumanApprovalResponse approvalResponse;
    try
    {
        approvalResponse = await context.WaitForExternalEvent<HumanApprovalResponse>(
            eventName: "ApprovalDecision",
            timeout: TimeSpan.FromHours(24));
    }
    catch (OperationCanceledException)
    {
        // Timeout occurred - escalate for review
        return await context.CallActivityAsync<string>(nameof(EscalateForReview), draftContent);
    }

    if (approvalResponse.Approved)
    {
        return await context.CallActivityAsync<string>(nameof(PublishContent), draftContent);
    }

    return "Content rejected";
}

import azure.durable_functions as df
from datetime import timedelta
from agent_framework.azure import AgentFunctionApp

app = AgentFunctionApp(agents=[content_agent])

@app.orchestration_trigger(context_name="context")
def content_approval_workflow(context: df.DurableOrchestrationContext):
    topic = context.get_input()

    # Generate content using an agent
    content_agent = app.get_agent(context, "ContentGenerationAgent")
    draft_content = yield content_agent.run(
        messages=f"Write an article about {topic}"
    )

    # Send for human review
    yield context.call_activity("notify_reviewer", draft_content)

    # Wait for approval with timeout
    approval_task = context.wait_for_external_event("ApprovalDecision")
    timeout_task = context.create_timer(
        context.current_utc_datetime + timedelta(hours=24)
    )

    winner = yield context.task_any([approval_task, timeout_task])

    if winner == approval_task:
        timeout_task.cancel()
        approval_data = approval_task.result
        if approval_data.get("approved"):
            result = yield context.call_activity("publish_content", draft_content)
            return result
        return "Content rejected"

    # Timeout occurred - escalate for review
    result = yield context.call_activity("escalate_for_review", draft_content)
    return result

A determinisztikus ügynökvezénylések megvárhatják a külső eseményeket, tartósan megőrizhetik állapotukat, miközben emberi visszajelzésekre, túlélt hibákra, újraindításokra és hosszabb várakozási időszakokra várnak. Amikor az emberi válasz megérkezik, az orchestráció automatikusan folytatódik a teljes beszélgetés kontextusával és a végrehajtási állapot érintetlen megőrzésével.

Emberi bemenet biztosítása

Ha jóváhagyást vagy bemenetet szeretne küldeni egy várakozási vezényléshez, küldjön egy külső eseményt a vezénylési példánynak a Durable Task ügyféloldali SDK vagy a Azure Functions Durable bővítményvégpontok használatával. A véleményezők például egy olyan webes űrlapon keresztül hagyhatják jóvá a tartalmat, amely meghívja a következőt:

await client.RaiseEventAsync(instanceId, "ApprovalDecision", new HumanApprovalResponse 
{ 
    Approved = true,
    Feedback = "Looks great!"
});

approval_data = {
    "approved": True,
    "feedback": "Looks great!"
}
await client.raise_event(instance_id, "ApprovalDecision", approval_data)

Költséghatékonyság

Az emberi közreműködésű munkafolyamatok tartós ügynökökkel rendkívül költséghatékonyak, ha az Azure Functions Flex Consumption csomagban üzemeltetik. Ha egy munkafolyamat 24 órát vár a jóváhagyásra, csak néhány másodpercig kell fizetnie a végrehajtási időért (a tartalom létrehozásához, az értesítés küldéséhez és a válasz feldolgozásához) – nem a 24 órás várakozásért. A várakozási időszak alatt a rendszer nem használ számítási erőforrásokat.

Megfigyelhetőség a Durable Task Schedulerrel

A Durable Task Scheduler (DTS) a tartós ügynökök számára ajánlott tartós háttérrendszer, amely a legjobb teljesítményt, teljes körűen felügyelt infrastruktúrát és beépített megfigyelhetőséget kínálja egy felhasználói felület irányítópultján keresztül. Azure Functions alkalmazások más tárolási háttérrendszereket is használhatnak (például Azure Storage), de a DTS kifejezetten tartós számítási feladatokhoz van optimalizálva, és kiváló teljesítményt és monitorozási képességeket biztosít. A saját üzemeltetésű dolgozók a DTS-t is használják a tartós ütemezéshez, az állapothoz és az irányítópult láthatóságához.

Ügynök munkamenet-elemzések

  • Beszélgetési előzmények: Az egyes ügynök-munkamenetek teljes csevegési előzményeinek megtekintése, beleértve az összes üzenetet, eszközhívást és beszélgetési környezetet bármikor
  • Feladat időzítése: Az adott tevékenységek és ügynökök közötti interakciók befejezésének monitorozása

Képernyőkép a Durable Task Scheduler irányítópultjáról, amelyen az ügynök csevegési előzményei láthatók beszélgetési szálakkal és üzenetekkel.

Vezénylési megállapítások

  • Többügynök-vizualizáció: Több specializált ügynök meghívásának végrehajtási folyamata párhuzamos végrehajtások és feltételes elágaztatások vizuális ábrázolásával
  • Végrehajtási előzmények: Részletes végrehajtási naplók elérése
  • Valós idejű monitorozás: Az aktív vezénylések, a várólistán lévő munkaelemek és az ügynökállapotok nyomon követése az üzembe helyezés során
  • Teljesítménymetrikák: Az ügynök válaszidejének, a tokenhasználatnak és a vezénylés időtartamának monitorozása

Képernyőkép a Durable Task Scheduler irányítópultjáról, amelyen a vezénylési vizualizáció látható több ügynök-interakcióval és munkafolyamat-végrehajtással.

Hibakeresési képességek

  • Strukturált ügynökkimenetek és eszközhívások eredményeinek megtekintése
  • Nyomkövetési eszközhívások és azok eredményei
  • Külső eseménykezelés monitorozása emberi beavatkozást igénylő helyzetekben

Az irányítópult segítségével pontosan megismerheti az ügynökök működését, gyorsan diagnosztizálhatja a problémákat, és valós végrehajtási adatok alapján optimalizálhatja a teljesítményt.

Oktatóanyag: Tartós ügynök létrehozása és futtatása Azure Functions

Ez az oktatóanyag bemutatja, hogyan hozhat létre és futtathat tartós AI-ügynököt a Durable Extension Azure Functions üzemeltetési modelljével. Létrehozhat egy Azure Functions-alkalmazást, amely beépített HTTP-végpontokkal rendelkező állapotalapú ügynököt üzemeltet, és megtudhatja, hogyan monitorozhatja azt a Durable Task Scheduler irányítópultján. A saját üzemeltetésű ügynökökkel kapcsolatban lásd a mintákat.

Prerequisites

Mielőtt hozzákezdene, győződjön meg arról, hogy rendelkezik a következő előfeltételekkel:

Megjegyzés:

A Microsoft Agent Framework a .NET összes aktívan támogatott verziójával támogatott. A minta alkalmazásában a .NET 9 SDK-t vagy egy újabb verziót javasoljuk.

A gyorsútmutató-projekt letöltése

Az Azure Developer CLI használatával inicializálhat egy új projektet a tartós ügynökök gyorsútmutató sablonjának használatával.

  1. Hozzon létre egy új könyvtárat a projekthez, és lépjen be abba:

    mkdir MyDurableAgent
cd MyDurableAgent

  1. A projekt inicializálása a sablonból:

    azd init --template durable-agents-quickstart-dotnet

    Amikor a rendszer környezeti nevet kér, adjon meg egy hasonló my-durable-agentnevet.

Ez letölti a beindítási projektet az összes szükséges fájllal, beleértve az Azure Functions konfigurációját, az ügynökkódot, és az infrastruktúrát kódként megvalósító sablonokat.

  1. Hozzon létre egy új könyvtárat a projekthez, és lépjen be abba:

    mkdir MyDurableAgent
cd MyDurableAgent

  1. A projekt inicializálása a sablonból:

    azd init --template durable-agents-quickstart-python

    Amikor a rendszer környezeti nevet kér, adjon meg egy hasonló my-durable-agentnevet.

  2. Virtuális környezet létrehozása és aktiválása:

    uv venv .venv
source .venv/bin/activate

Megjegyzés:

python3 -m venv .venv is működik, de egy ismert ensurepip probléma miatt határozatlan ideig lefagyhat Windows Microsoft Store Python. Ezt uv venv .venv elkerülheti.

  1. Telepítse a szükséges csomagokat:

    python -m pip install -r requirements.txt

Ez letölti a beindítási projektet az összes szükséges fájllal, beleértve az Azure Functions konfigurációját, az ügynökkódot, és az infrastruktúrát kódként megvalósító sablonokat. Emellett előkészít egy virtuális környezetet a szükséges függőségekkel.

Azure-erőforrások kiépítése

Az Azure Developer CLI használatával hozza létre a szükséges Azure-erőforrásokat a tartós ügynökhöz.

  1. Az infrastruktúra kiépítése:

    azd provision

    Ez a parancs a következőket hozza létre:

    • Azure OpenAI-szolgáltatás gpt-4o-mini üzembe helyezéssel
    • Azure Functions-alkalmazás Flex Consumption üzemeltetési csomaggal
    • Azure Storage-fiók az Azure Functions-futtatókörnyezethez és a tartós tároláshoz
    • Tartós feladatütemező-példány (használati terv) az ügynökállapot kezeléséhez
    • Szükséges hálózati és identitáskonfigurációk

  2. Amikor a rendszer kéri, válassza ki az Azure-előfizetését, és válassza ki az erőforrások helyét.

A kiépítési folyamat néhány percet vesz igénybe. Miután elkészült, az azd tárolja a létrehozott erőforrás-információkat a környezetben.

Az ügynökkód áttekintése

Most nézzük meg a tartós szolgáltatási ügynököt meghatározó kódot.

Nyissa meg Program.cs az ügynök konfigurációjának megtekintéséhez:

using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Hosting.AzureFunctions;
using Microsoft.Azure.Functions.Worker.Builder;
using Microsoft.Extensions.Hosting;

var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") 
    ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT environment variable is not set");
var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT") ?? "gpt-4o-mini";

// Create an AI agent following the standard Microsoft Agent Framework pattern
AIAgent agent = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
    .AsAIAgent(
        model: deploymentName,
        instructions: "You are a helpful assistant that can answer questions and provide information.",
        name: "MyDurableAgent");

using IHost app = FunctionsApplication
    .CreateBuilder(args)
    .ConfigureFunctionsWebApplication()
    .ConfigureDurableAgents(options => options.AddAIAgent(agent))
    .Build();
app.Run();

Ez a kód:

  1. Lekéri az Azure OpenAI-konfigurációt a környezeti változókból.
  2. Azure OpenAI-ügyfelet hoz létre azure-beli hitelesítő adatokkal.
  3. Létrehoz egy AI-ügynököt utasítások és név alapján.
  4. Konfigurálja az Azure Functions alkalmazást az ügynök megbízható szálkezeléssel történő üzemeltetésére.

Nyissa meg function_app.py az ügynök konfigurációjának megtekintéséhez:

import os
from agent_framework.azure import AgentFunctionApp
from agent_framework.openai import OpenAIChatCompletionClient
from azure.identity import DefaultAzureCredential

endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
if not endpoint:
    raise ValueError("AZURE_OPENAI_ENDPOINT is not set.")
deployment_name = os.getenv("AZURE_OPENAI_CHAT_COMPLETION_MODEL", "gpt-4o-mini")
api_version = os.getenv("AZURE_OPENAI_API_VERSION")

# Create an AI agent following the standard Microsoft Agent Framework pattern
agent = OpenAIChatCompletionClient(
    azure_endpoint=endpoint,
    model=deployment_name,
    api_version=api_version,
    credential=DefaultAzureCredential()
).as_agent(
    instructions="You are a helpful assistant that can answer questions and provide information.",
    name="MyDurableAgent"
)

# Configure the function app to host the agent with durable thread management
app = AgentFunctionApp(agents=[agent])

Ez a kód:

  • Lekéri az Azure OpenAI-konfigurációt a környezeti változókból.
  • Azure OpenAI-ügyfelet hoz létre azure-beli hitelesítő adatokkal.
  • Létrehoz egy AI-ügynököt utasítások és név alapján.
  • Konfigurálja az Azure Functions alkalmazást az ügynök megbízható szálkezeléssel történő üzemeltetésére.

Az ügynök készen áll az Azure Functionsben való üzemeltetésre. A tartós feladatbővítmény automatikusan HTTP-végpontokat hoz létre az ügynökkel való interakcióhoz, és több kérésen keresztül kezeli a beszélgetés állapotát.

Helyi beállítások konfigurálása

Hozzon létre egy local.settings.json fájlt a helyi fejlesztéshez a projektben található mintafájl alapján.

  1. Másolja ki a mintabeállításokat tartalmazó fájlt:

    cp local.settings.sample.json local.settings.json

  1. Az Azure OpenAI-végpont lekérése a kiépített erőforrásokból:

    azd env get-value AZURE_OPENAI_ENDPOINT

  2. Nyissa meg local.settings.json és cserélje le <your-resource-name> az AZURE_OPENAI_ENDPOINT értékben az előző parancs végpontjával.

A local.settings.json következőhöz hasonlóan kell kinéznie:

{
  "IsEncrypted": false,
  "Values": {
    // ... other settings ...
    "AZURE_OPENAI_ENDPOINT": "https://your-openai-resource.openai.azure.com",
    "AZURE_OPENAI_DEPLOYMENT": "gpt-4o-mini",
    "TASKHUB_NAME": "default"
  }
}

Megjegyzés:

A local.settings.json fájl csak helyi fejlesztéshez használható, és nincs üzembe helyezve az Azure-ban. Éles környezetek esetén ezeket a beállításokat az infrastruktúrasablonok automatikusan konfigurálják az Azure Functions-alkalmazásban.

Helyi fejlesztési függőségek indítása

A tartós ügynökök helyi futtatásához két szolgáltatást kell elindítania:

  • Azurite: Az Azure Storage-szolgáltatásokat emulálja (az Azure Functions az eseményindítók és a belső állapot kezelésére használja).
  • Durable Task Scheduler (DTS) emulátor: Kezeli a tartós állapotot (beszélgetési előzmények, vezénylési állapot) és az ügynökök ütemezését

Az Azurite indítása

Az Azurite helyileg emulálja az Azure Storage-szolgáltatásokat. Az Azure Functions a belső állapot kezelésére használja. Ezt egy új terminálablakban kell futtatnia, és futtatnia kell a tartós ügynök fejlesztése és tesztelése során.

  1. Nyisson meg egy új terminálablakot, és húzza le az Azurite Docker-rendszerképet:

    docker pull mcr.microsoft.com/azure-storage/azurite

  2. Indítsa el az Azurite-t egy terminálablakban:

    docker run -p 10000:10000 -p 10001:10001 -p 10002:10002 mcr.microsoft.com/azure-storage/azurite

    Az Azurite elindítja és figyeli a Blob (10000), a Queue (10001) és a Table (10002) szolgáltatások alapértelmezett portját.

A tartós ügynök fejlesztése és tesztelése során tartsa nyitva ezt a terminálablakot.

Tip

További információ az Azurite-ról, beleértve az alternatív telepítési módszereket is: Az Azurite emulator használata a helyi Azure Storage-fejlesztéshez.

A Durable Task Scheduler emulátor indítása

A DTS emulátor tartós háttérszolgáltatást biztosít az ügynökök állapotának és folyamatvezérléseinek kezeléséhez. Tárolja a beszélgetési előzményeket, és biztosítja, hogy az ügynök állapota megőrződjön újraindítások után is. Emellett tartós vezényléseket és ügynököket is aktivál. Ezt egy külön új terminálablakban kell futtatnia, és folyamatosan futtatva kell tartania a tartós ügynök fejlesztése és tesztelése során.

  1. Nyisson meg egy másik új terminálablakot, és húzza le a DTS emulátor Docker-lemezképét:

    docker pull mcr.microsoft.com/dts/dts-emulator:latest

  2. Futtassa a DTS emulátort:

    docker run -p 8080:8080 -p 8082:8082 mcr.microsoft.com/dts/dts-emulator:latest

    Ez a parancs elindítja az emulátort, és elérhetővé teszi a következőt:

    • 8080-s port: A Durable Task Scheduler gRPC-végpontja (amelyet a Functions-alkalmazás használ)
    • 8082-s port: A felügyeleti irányítópult

  3. Az irányítópult a következő címen http://localhost:8082lesz elérhető: .

A tartós ügynök fejlesztése és tesztelése során tartsa nyitva ezt a terminálablakot.

Tip

Ha többet szeretne megtudni a DTS-emulátorról, beleértve a több feladatközpont konfigurálását és az irányítópult elérését, olvassa el a Fejlesztés tartós feladatütemezővel című témakört.

A függvényalkalmazás futtatása

Most már készen áll az Azure Functions-alkalmazás durable agenttel való futtatására.

  1. Egy új terminálablakban (az Azurite és a DTS emulátor külön ablakban futva) keresse meg a projektkönyvtárat.

  2. Indítsa el az Azure Functions-futtatókörnyezetet:

    func start

  3. A kimenet azt jelzi, hogy a függvényalkalmazás fut, beleértve az ügynök HTTP-végpontjait is:

    Functions:
     http-MyDurableAgent: [POST] http://localhost:7071/api/agents/MyDurableAgent/run
     dafx-MyDurableAgent: entityTrigger

Ezek a végpontok automatikusan kezelik a beszélgetés állapotát – nem kell saját maga létrehoznia vagy kezelnie a szálobjektumokat.

Tesztelje az ügynököt helyben

Mostantól HTTP-kérések használatával léphet kapcsolatba a tartós ügynökével. Az ügynök több kérelem esetén is fenntartja a beszélgetés állapotát, így lehetővé teszi a többfordulós beszélgetéseket.

Új beszélgetés indítása

Hozzon létre egy új szálat, és küldje el az első üzenetet:

curl -i -X POST http://localhost:7071/api/agents/MyDurableAgent/run \
  -H "Content-Type: text/plain" \
  -d "What are three popular programming languages?"

Mintaválasz (vegye figyelembe, hogy a x-ms-thread-id fejléc tartalmazza a szálazonosítót):

HTTP/1.1 200 OK
Content-Type: text/plain
x-ms-thread-id: @dafx-mydurableagent@263fa373-fa01-4705-abf2-5a114c2bb87d
Content-Length: 189

Three popular programming languages are Python, JavaScript, and Java. Python is known for its simplicity and readability, JavaScript powers web interactivity, and Java is widely used in enterprise applications.

Mentse a szálazonosítót a x-ms-thread-id fejlécből (például @dafx-mydurableagent@263fa373-fa01-4705-abf2-5a114c2bb87d) a következő kéréshez.

A beszélgetés folytatása

Küldjön egy követő üzenetet ugyanarra a szálra a szálazonosító lekérdezési paraméterként való hozzáadásával:

curl -X POST "http://localhost:7071/api/agents/MyDurableAgent/run?thread_id=@dafx-mydurableagent@263fa373-fa01-4705-abf2-5a114c2bb87d" \
  -H "Content-Type: text/plain" \
  -d "Which one is best for beginners?"

Cserélje le @dafx-mydurableagent@263fa373-fa01-4705-abf2-5a114c2bb87d az előző válasz x-ms-thread-id fejlécéből származó tényleges szálazonosítóra.

Mintaválasz:

Python is often considered the best choice for beginners among those three. Its clean syntax reads almost like English, making it easier to learn programming concepts without getting overwhelmed by complex syntax. It's also versatile and widely used in education.

Figyelje meg, hogy az ügynök emlékszik az előző üzenet kontextusára (a három programozási nyelvre), anélkül, hogy újra meg kellene adnia őket. Mivel a tartós feladatütemező tartósan tárolja a beszélgetés állapotát, ez az előzmények akkor is megmaradnak, ha újraindítja a függvényalkalmazást, vagy egy másik példány folytatja a beszélgetést.

Monitorozás a Durable Task Scheduler irányítópulttal

A Durable Task Scheduler beépített irányítópultot biztosít a tartós ügynökök monitorozásához és hibakereséséhez. Az irányítópult részletes betekintést nyújt az ügynökműveletekbe, a beszélgetések előzményeibe és a végrehajtási folyamatokba.

Az irányítópult elérése

  1. Nyissa meg a helyi DTS-emulátor http://localhost:8082 irányítópultját a webböngészőben.

  2. Válassza ki az alapértelmezett tevékenységközpontot a listából annak részleteinek megtekintéséhez.

  3. A beállítások megnyitásához válassza a fogaskerék ikont a jobb felső sarokban, és győződjön meg arról, hogy az Ügynökoldalak engedélyezése lehetőség be van jelölve az Előzetes verziójú funkciók csoportban.

Ügynökbeszélgetések felfedezése

  1. Az irányítópulton lépjen az Ügynökök lapra.

  2. Válassza ki a tartós agent szálat (például mydurableagent - 263fa373-fa01-4705-abf2-5a114c2bb87d) a listából.

    Látni fogja az ügynökszál részletes nézetét, beleértve a teljes beszélgetési előzményeket az összes üzenettel és válaszsal.

    Képernyőkép a Durable Task Scheduler irányítópultjáról, amelyen egy ügynökszál beszélgetési előzményei láthatók.

Az irányítópult ütemterv nézetet biztosít, amely segít megérteni a beszélgetés folyamatát. A legfontosabb információk a következők:

  • Időbélyegek és időtartam az egyes interakciókhoz
  • Üzenet- és választartalom
  • Használt tokenek száma

Tip

A DTS-irányítópult valós idejű frissítéseket biztosít, így megfigyelheti az ügynök viselkedését, miközben a HTTP-végpontokon keresztül kommunikál vele.

Telepítés az Azure-ra

Miután helyileg letesztelte a tartós ügynököt, telepítse az Azure-ba.

  1. Az alkalmazás üzembe helyezése:

    azd deploy

    Ez a parancs csomagolja az alkalmazást, és üzembe helyezi a kiépítés során létrehozott Azure Functions-alkalmazásban.

  2. Várjon, amíg az üzembe helyezés befejeződik. A kimenet megerősíti, hogy az ügynök aktívan fut az Azure-ban.

Az üzembe helyezett ügynök tesztelése

Az üzembe helyezés után tesztelje az Azure-ban futó ügynököt.

A függvénykulcs lekérése

Az Azure Functionshez API-kulcs szükséges a HTTP útján aktivált függvényekhez termelésben.

API_KEY=`az functionapp function keys list --name $(azd env get-value AZURE_FUNCTION_NAME) --resource-group $(azd env get-value AZURE_RESOURCE_GROUP) --function-name http-MyDurableAgent --query default -o tsv`

Új beszélgetés indítása az Azure-ban

Hozzon létre egy új szálat, és küldje el az első üzenetet az üzembe helyezett ügynöknek:

curl -i -X POST "https://$(azd env get-value AZURE_FUNCTION_NAME).azurewebsites.net/api/agents/MyDurableAgent/run?code=$API_KEY" \
  -H "Content-Type: text/plain" \
  -d "What are three popular programming languages?"

Jegyezze fel a válaszfejlécben visszaadott szálazonosítót x-ms-thread-id .

A beszélgetés folytatása az Azure-ban

Küldjön egy követő üzenetet ugyanabban a szálban. Cserélje le <thread-id> az előző válaszból származó szálazonosítóval:

THREAD_ID="<thread-id>"
curl -X POST "https://$(azd env get-value AZURE_FUNCTION_NAME).azurewebsites.net/api/agents/MyDurableAgent/run?code=$API_KEY&thread_id=$THREAD_ID" \
  -H "Content-Type: text/plain" \
  -d "Which is easiest to learn?"

Az ügynök ugyanúgy tartja karban a beszélgetési környezetet az Azure-ban, mint a helyi környezetben, bemutatva az ügynök állapotának tartósságát.

Az üzembe helyezett ügynök figyelése

Az üzembe helyezett ügynököt az Azure Durable Task Scheduler irányítópultján figyelheti.

  1. A Durable Task Scheduler-példány nevének lekérése:

    azd env get-value DTS_NAME

  2. Nyissa meg az Azure Portalt , és keresse meg a Durable Task Scheduler nevét az előző lépésben.

  3. A Durable Task Scheduler erőforrás áttekintési paneljén válassza ki az alapértelmezett tevékenységközpontot a listából.

  4. A figyelési irányítópult megnyitásához válassza a Tevékenységközpont lap tetején található Irányítópult megnyitása lehetőséget.

  5. Az ügynök beszélgetéseit ugyanúgy tekintheti meg, mint a helyi emulátort.

Az Azure által üzemeltetett irányítópult ugyanazokat a hibakeresési és monitorozási képességeket biztosítja, mint a helyi emulátor, így megvizsgálhatja a beszélgetési előzményeket, nyomon követheti az eszközhívásokat, és elemezheti a teljesítményt az éles környezetben.

Oktatóanyag: Tartós ügynökök vezényléssel Azure Functions

Ez az oktatóanyag bemutatja, hogyan vezényelhet több tartós AI-ügynököt a Azure Functions üzemeltetési modell és a ventilátor-ki/ventilátor minta használatával. Az előző oktatóanyagból kiterjesztheti a tartós ügynököt egy olyan többügynökös rendszer létrehozására, amely feldolgozza a felhasználó kérdését, majd egyszerre több nyelvre fordítja le a választ. A saját üzemeltetésű vezénylési példákért tekintse meg a mintákat.

A vezénylési minta ismertetése

Az általad felépítendő orkestráció a következő folyamatot követi:

  1. Felhasználói bevitel – A felhasználó kérdése vagy üzenete
  2. Fő ügynök – Az MyDurableAgent első oktatóanyag feldolgozza a kérdést
  3. Kifújás – A főügynök válaszát egyidejűleg küldi el a rendszer mindkét fordítóügynöknek
  4. Fordítóügynökök - Két specializált ügynök lefordítja a választ (francia és spanyol)
  5. Fan-in – Az eredmények egyetlen JSON-válaszba vannak összesítve az eredeti válaszsal és fordításokkal

Ez a minta lehetővé teszi az egyidejű feldolgozást, ami csökkenti a válaszidőt a szekvenciális fordításhoz képest.

Ügynökök regisztrálása indításkor

Az ügynökök tartós vezénylésekben való megfelelő használatához regisztrálja őket az alkalmazás indításakor. Ezek a vezénylési végrehajtások során használhatók.

Frissítse a Program.cs annak érdekében, hogy a fordítóügynökök a meglévő MyDurableAgent mellett legyenek regisztrálva.

using System;
using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Hosting.AzureFunctions;
using Microsoft.Azure.Functions.Worker.Builder;
using Microsoft.Extensions.Hosting;

// Get the Azure OpenAI configuration
string endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")
    ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
string deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT")
    ?? "gpt-4o-mini";

// Create the Microsoft Foundry client
AIProjectClient client = new(new Uri(endpoint), new DefaultAzureCredential());

// Create the main agent from the first tutorial
AIAgent mainAgent = client.AsAIAgent(
    model: deploymentName,
    instructions: "You are a helpful assistant that can answer questions and provide information.",
    name: "MyDurableAgent");

// Create translation agents
AIAgent frenchAgent = client.AsAIAgent(
    model: deploymentName,
    instructions: "You are a translator. Translate the following text to French. Return only the translation, no explanations.",
    name: "FrenchTranslator");

AIAgent spanishAgent = client.AsAIAgent(
    model: deploymentName,
    instructions: "You are a translator. Translate the following text to Spanish. Return only the translation, no explanations.",
    name: "SpanishTranslator");

// Build and configure the Functions host
using IHost app = FunctionsApplication
    .CreateBuilder(args)
    .ConfigureFunctionsWebApplication()
    .ConfigureDurableAgents(options =>
    {
        // Register all agents for use in orchestrations and HTTP endpoints
        options.AddAIAgent(mainAgent);
        options.AddAIAgent(frenchAgent);
        options.AddAIAgent(spanishAgent);
    })
    .Build();

app.Run();

Frissítse a function_app.py annak érdekében, hogy a fordítóügynökök a meglévő MyDurableAgent mellett legyenek regisztrálva.

import os
from azure.identity import DefaultAzureCredential
from agent_framework.azure import AgentFunctionApp
from agent_framework.openai import OpenAIChatCompletionClient

# Get the Azure OpenAI configuration
endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
if not endpoint:
    raise ValueError("AZURE_OPENAI_ENDPOINT is not set.")
deployment_name = os.getenv("AZURE_OPENAI_CHAT_COMPLETION_MODEL", "gpt-4o-mini")
api_version = os.getenv("AZURE_OPENAI_API_VERSION")

# Create the Azure OpenAI client
chat_client = OpenAIChatCompletionClient(
    azure_endpoint=endpoint,
    model=deployment_name,
    api_version=api_version,
    credential=DefaultAzureCredential()
)

# Create the main agent from the first tutorial
main_agent = chat_client.as_agent(
    instructions="You are a helpful assistant that can answer questions and provide information.",
    name="MyDurableAgent"
)

# Create translation agents
french_agent = chat_client.as_agent(
    instructions="You are a translator. Translate the following text to French. Return only the translation, no explanations.",
    name="FrenchTranslator"
)

spanish_agent = chat_client.as_agent(
    instructions="You are a translator. Translate the following text to Spanish. Return only the translation, no explanations.",
    name="SpanishTranslator"
)

# Create the function app and register all agents
app = AgentFunctionApp(agents=[main_agent, french_agent, spanish_agent])

Vezénylési függvény létrehozása

A vezénylési függvény koordinálja a munkafolyamatot több ügynök között. Lekéri a regisztrált ügynököket a perzisztens környezetből, és megszervezi a végrehajtásukat: először meghívja a főügynököt, majd egyidejűleg kiterjeszti a fordító ügynökökre.

Hozzon létre egy új fájlt AgentOrchestration.cs a projektkönyvtárban:

using System.Collections.Generic;
using System.Threading.Tasks;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.DurableTask;
using Microsoft.Azure.Functions.Worker;
using Microsoft.DurableTask;

namespace MyDurableAgent;

public static class AgentOrchestration
{
    // Define a strongly-typed response structure for agent outputs
    public sealed record TextResponse(string Text);

    [Function("agent_orchestration_workflow")]
    public static async Task<Dictionary<string, string>> AgentOrchestrationWorkflow(
        [OrchestrationTrigger] TaskOrchestrationContext context)
    {
        var input = context.GetInput<string>() ?? throw new ArgumentNullException(nameof(context), "Input cannot be null");

        // Step 1: Get the main agent's response
        DurableAIAgent mainAgent = context.GetAgent("MyDurableAgent");
        AgentResponse<TextResponse> mainResponse = await mainAgent.RunAsync<TextResponse>(input);
        string agentResponse = mainResponse.Result.Text;

        // Step 2: Fan out - get the translation agents and run them concurrently
        DurableAIAgent frenchAgent = context.GetAgent("FrenchTranslator");
        DurableAIAgent spanishAgent = context.GetAgent("SpanishTranslator");

        Task<AgentResponse<TextResponse>> frenchTask = frenchAgent.RunAsync<TextResponse>(agentResponse);
        Task<AgentResponse<TextResponse>> spanishTask = spanishAgent.RunAsync<TextResponse>(agentResponse);

        // Step 3: Wait for both translation tasks to complete (fan-in)
        await Task.WhenAll(frenchTask, spanishTask);

        // Get the translation results
        TextResponse frenchResponse = (await frenchTask).Result;
        TextResponse spanishResponse = (await spanishTask).Result;

        // Step 4: Combine results into a dictionary
        var result = new Dictionary<string, string>
        {
            ["original"] = agentResponse,
            ["french"] = frenchResponse.Text,
            ["spanish"] = spanishResponse.Text
        };

        return result;
    }
}

Adja hozzá a vezénylési függvényt a function_app.py fájlhoz:

import azure.durable_functions as df

@app.orchestration_trigger(context_name="context")
def agent_orchestration_workflow(context: df.DurableOrchestrationContext):
    """
    Orchestration function that coordinates multiple agents.
    Returns a dictionary with the original response and translations.
    """
    input_text = context.get_input()

    # Step 1: Get the main agent's response
    main_agent = app.get_agent(context, "MyDurableAgent")
    main_response = yield main_agent.run(input_text)
    agent_response = main_response.text

    # Step 2: Fan out - get the translation agents and run them concurrently
    french_agent = app.get_agent(context, "FrenchTranslator")
    spanish_agent = app.get_agent(context, "SpanishTranslator")

    parallel_tasks = [
        french_agent.run(agent_response),
        spanish_agent.run(agent_response)
    ]

    # Step 3: Wait for both translation tasks to complete (fan-in)
    translations = yield context.task_all(parallel_tasks) # type: ignore

    # Step 4: Combine results into a dictionary
    result = {
        "original": agent_response,
        "french": translations[0].text,
        "spanish": translations[1].text
    }

    return result

Megjegyzés:

A funkció Go-támogatása hamarosan érkezik. A legújabb állapotot az Agent Framework Go-adattárában tekinthet meg.

Az orchestráció tesztelése

Győződjön meg arról, hogy az első oktatóanyagban szereplő helyi fejlesztési függőségek továbbra is futnak:

  • Azurite egy terminálablakban
  • Durable Task Scheduler emulator egy másik terminálablakban

Miután a helyi fejlesztési függőségek működnek:

  1. Indítsa el az Azure Functions-alkalmazást egy új terminálablakban:

    func start

  2. A Durable Functions bővítmény automatikusan létrehoz beépített HTTP-végpontokat a vezénylések kezeléséhez. Indítsa el a vezénylést a beépített API-t használva:

    curl -X POST http://localhost:7071/runtime/webhooks/durabletask/orchestrators/agent_orchestration_workflow \
  -H "Content-Type: application/json" \
  -d '"\"What are three popular programming languages?\""'

  1. A válasz URL-eket tartalmaz az orchestration példány kezeléséhez.

    {
  "id": "abc123def456",
  "statusQueryGetUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123def456",
  "sendEventPostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123def456/raiseEvent/{eventName}",
  "terminatePostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123def456/terminate",
  "purgeHistoryDeleteUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123def456"
}

  2. Lekérdezheti a vezénylés állapotát a statusQueryGetUri (cserélje ki erre: abc123def456, az aktuális példányazonosítójára).

    curl http://localhost:7071/runtime/webhooks/durabletask/instances/abc123def456

  1. Kérdezze le az állapotvégpontot, amíg az runtimeStatus nem lesz Completed. Ha elkészült, meg fog jelenni az orkesktrációs kimenet a központi ügynök válaszával és annak fordításaival.

    {
  "name": "agent_orchestration_workflow",
  "instanceId": "abc123def456",
  "runtimeStatus": "Completed",
  "output": {
    "original": "Three popular programming languages are Python, JavaScript, and Java. Python is known for its simplicity...",
    "french": "Trois langages de programmation populaires sont Python, JavaScript et Java. Python est connu pour sa simplicité...",
    "spanish": "Tres lenguajes de programación populares son Python, JavaScript y Java. Python es conocido por su simplicidad..."
  }
}

A vezérlés monitorozása az irányítópulton

A Durable Task Scheduler irányítópultja betekintést nyújt a vezénylésbe:

  1. Nyissa meg a http://localhost:8082 oldalt a böngészőben.

  2. Válassza ki az "alapértelmezett" tevékenységközpontot.

  3. Válassza a „Vezénylések” lapot.

  4. Keresse meg az orkesztrációs példányt a listában.

  5. Válassza ki az példányt megtekintéséhez:

    • Az orchesztráció idővonala
    • Fő ügynök végrehajtása, amelyet egyidejű fordítóügynökök követnek
    • Minden egyes ügynök futtatása (MyDurableAgent, majd a francia és spanyol fordítók)
    • Kisugárzási és összevonási minták vizualizációja
    • Az egyes lépések időzítése és időtartama

A vezénylés üzembe helyezése az Azure-ban

A frissített alkalmazás üzembe helyezése az Azure Developer CLI használatával:

azd deploy

Ezzel üzembe helyezi a frissített kódot az új vezénylési függvénnyel és további ügynökökkel az első oktatóanyagban létrehozott Azure Functions-alkalmazásban.

Az üzembe helyezett orchesztráció tesztelése

Az üzembe helyezés után tesztelje az Azure-ban futó vezénylést.

  1. Szerezze be a tartós bővítmény rendszerkulcsát:

    SYSTEM_KEY=$(az functionapp keys list --name $(azd env get-value AZURE_FUNCTION_NAME) --resource-group $(azd env get-value AZURE_RESOURCE_GROUP) --query "systemKeys.durabletask_extension" -o tsv)

  1. Indítsa el a vezénylést a beépített API-t használva:

    curl -X POST "https://$(azd env get-value AZURE_FUNCTION_NAME).azurewebsites.net/runtime/webhooks/durabletask/orchestrators/agent_orchestration_workflow?code=$SYSTEM_KEY" \
  -H "Content-Type: application/json" \
  -d '"\"What are three popular programming languages?\""'
  1. statusQueryGetUri A válaszból lekérdezheti a befejezést állapotát, és fordításokkal együtt tekintheti meg az eredményeket.

Következő lépések

OpenAI-Compatible végpontok

További források:

  • Last updated on