Agenten in Workflows

In deze zelfstudie ziet u hoe u AI-agents integreert in werkstromen met behulp van Agent Framework. Je leert werkstromen te creëren die van de kracht van gespecialiseerde AI-agents gebruikmaken voor het maken van content, beoordelen en andere samenwerkingstaken.

Wat je gaat bouwen

U maakt een werkstroom die:

  • Maakt gebruik van Azure Foundry Agent Service om intelligente agents te maken
  • Implementeert een Franse vertaalagent die invoer vertaalt naar het Frans
  • Implementeert een Spaanse vertaalagent die Frans naar spaans vertaalt
  • Implementeert een Engelse vertaalagent die Spaans weer vertaalt naar het Engels
  • Verbindt agents met elkaar in een sequentiële werkstroompijpleiding
  • Streamt realtime updates als agents aanvragen verwerken
  • Demonstreert het juiste opschonen van resources voor Azure Foundry-agents

Besproken concepten

Prerequisites

Stap 1: NuGet-pakketten installeren

Installeer eerst de vereiste pakketten voor uw .NET-project:

dotnet add package Microsoft.Agents.AI.Foundry --prerelease
dotnet add package Microsoft.Agents.AI.Workflows --prerelease

Stap 2: Azure Foundry-client instellen

Configureer de Azure Foundry-client met omgevingsvariabelen en -verificatie:

using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Foundry;
using Microsoft.Agents.AI.Workflows;
using Microsoft.Extensions.AI;

public static class Program
{
    private static async Task Main()
    {
        // Set up the Azure AI Project client
        var endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
            ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
        var deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-4o-mini";
        var aiProjectClient = new AIProjectClient(new Uri(endpoint), new AzureCliCredential());

Stap 3: Agent Factory-methode maken

Implementeer een helpermethode voor het maken van Azure Foundry-agents met specifieke instructies:

    /// <summary>
    /// Creates a translation agent for the specified target language.
    /// </summary>
    /// <param name="targetLanguage">The target language for translation</param>
    /// <param name="aiProjectClient">The AIProjectClient to create the agent</param>
    /// <param name="model">The model to use for the agent</param>
    /// <returns>A FoundryAgent configured for the specified language</returns>
    private static async Task<FoundryAgent> GetTranslationAgentAsync(
        string targetLanguage,
        AIProjectClient aiProjectClient,
        string model)
    {
        string agentName = $"{targetLanguage}Translator";
        var version = await aiProjectClient.AgentAdministrationClient.CreateAgentVersionAsync(
            agentName,
            new ProjectsAgentVersionCreationOptions(
                new DeclarativeAgentDefinition(model)
                {
                    Instructions = $"You are a translation assistant that translates the provided text to {targetLanguage}."
                }));

        return aiProjectClient.AsAIAgent(version);
    }
}

Stap 4: Gespecialiseerde Azure Foundry-agents maken

Maak drie vertaalagenten met behulp van de helpermethode:

        // Create agents
        AIAgent frenchAgent = await GetTranslationAgentAsync("French", aiProjectClient, deploymentName);
        AIAgent spanishAgent = await GetTranslationAgentAsync("Spanish", aiProjectClient, deploymentName);
        AIAgent englishAgent = await GetTranslationAgentAsync("English", aiProjectClient, deploymentName);

Stap 5: De werkstroom bouwen

Verbind de agents in een sequentiële werkstroom met behulp van WorkflowBuilder:

        // Build the workflow by adding executors and connecting them
        var workflow = new WorkflowBuilder(frenchAgent)
            .AddEdge(frenchAgent, spanishAgent)
            .AddEdge(spanishAgent, englishAgent)
            .Build();

Stap 6: Uitvoeren met streaming

Voer de werkstroom uit met streaming om realtime updates van alle agents te bekijken:

        // Execute the workflow
        await using StreamingRun run = await InProcessExecution.RunStreamingAsync(workflow, new ChatMessage(ChatRole.User, "Hello World!"));

        // Must send the turn token to trigger the agents.
        // The agents are wrapped as executors. When they receive messages,
        // they will cache the messages and only start processing when they receive a TurnToken.
        await run.TrySendMessageAsync(new TurnToken(emitEvents: true));
        await foreach (WorkflowEvent evt in run.WatchStreamAsync())
        {
            if (evt is AgentResponseUpdateEvent executorComplete)
            {
                Console.WriteLine($"{executorComplete.ExecutorId}: {executorComplete.Data}");
            }
        }

Stap 7: Opschonen van bronnen

Schoon de Azure Foundry-agents na gebruik correct op:

        // Cleanup the agents created for the sample.
        await aiProjectClient.AgentAdministrationClient.DeleteAgentAsync(frenchAgent.Name);
        await aiProjectClient.AgentAdministrationClient.DeleteAgentAsync(spanishAgent.Name);
        await aiProjectClient.AgentAdministrationClient.DeleteAgentAsync(englishAgent.Name);
    }

Hoe het werkt

  1. Installatie van Azure Foundry-client: Maakt gebruik van AIProjectClient met Azure CLI-referenties voor authenticatie
  2. Agent maken: Hiermee maakt u versiebeheeragents in Azure Foundry met specifieke instructies voor vertaling
  3. Sequentiële verwerking: Franse agent vertaalt eerst invoer, vervolgens Spaanse agent, vervolgens Engelse agent
  4. Turn Token Pattern: Agents cachen berichten en verwerken ze alleen wanneer zij een token ontvangen TurnToken
  5. Streaming updates: AgentResponseUpdateEvent biedt realtime token updates als agents antwoorden genereren
  6. Resourcebeheer: Juiste opschoning van Azure Foundry-agents met behulp van de Beheer-API

Belangrijkste concepten

  • Azure Foundry Agent Service: AI-agents in de cloud met geavanceerde redeneringsmogelijkheden
  • AIProjectClient: Client voor het maken en beheren van agents in Azure Foundry
  • WorkflowEvent: uitvoergebeurtenissen (type="output") bevatten uitvoergegevens van agents (AgentResponseUpdate voor streaming, AgentResponse voor niet-streaming)
  • TurnToken: Signaal dat agentverwerking activeert na berichtcaching
  • Sequentiële werkstroom: agents die zijn verbonden in een pijplijn, waarbij uitvoer van de ene naar de volgende stroomt

Implementatie voltooien

Voor de volledige werkende implementatie van deze Azure Foundry-agents workflow, zie het FoundryAgent-Program.cs voorbeeld in de agentframework-repository.

Wat je gaat bouwen

U maakt een werkstroom die:

  • Gebruikt FoundryChatClient om intelligente agents te maken
  • Hiermee wordt een Writer-agent geïmplementeerd waarmee inhoud wordt gemaakt op basis van prompts
  • Implementeert een revisoragent die feedback geeft over de inhoud
  • Verbindt agents met elkaar in een sequentiële werkstroompijpleiding
  • Streamt realtime updates als agents aanvragen verwerken

Besproken concepten

Prerequisites

  • Python 3.11 of hoger
  • Agent Framework geïnstalleerd: pip install agent-framework
  • Azure OpenAI-antwoorden geconfigureerd met de juiste omgevingsvariabelen
  • Azure CLI-verificatie: az login

Stap 1: Vereiste afhankelijkheden importeren

Begin met het importeren van de benodigde onderdelen voor werkstromen en Azure OpenAI-antwoordenagents:

import asyncio
import os

from agent_framework import AgentResponseUpdate, WorkflowBuilder
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential

Stap 2: Een Azure OpenAI-antwoordclient maken

Maak één gedeelde client die u kunt gebruiken om meerdere agents samen te stellen:

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

Stap 3: Gespecialiseerde agents maken

Maak twee gespecialiseerde agents voor het maken en controleren van inhoud:

    # Create a Writer agent that generates content
    writer_agent = client.as_agent(
        name="Writer",
        instructions=(
            "You are an excellent content writer. You create new content and edit contents based on the feedback."
        ),
    )

    # Create a Reviewer agent that provides feedback
    reviewer_agent = client.as_agent(
        name="Reviewer",
        instructions=(
            "You are an excellent content reviewer. "
            "Provide actionable feedback to the writer about the provided content. "
            "Provide the feedback in the most concise manner possible."
        ),
    )

Stap 4: De werkstroom bouwen

Verbind de agents in een sequentiële werkstroom met behulp van de opbouwfunctie:

        # Build the workflow with agents as executors
        workflow = WorkflowBuilder(start_executor=writer_agent).add_edge(writer_agent, reviewer_agent).build()

Stap 5: Uitvoeren met streaming

Voer de werkstroom uit met streaming om realtime updates van beide agents te bekijken:

    last_author: str | None = None

    events = workflow.run("Create a slogan for a new electric SUV that is affordable and fun to drive.", stream=True)
    async for event in events:
        if event.type == "output" and isinstance(event.data, AgentResponseUpdate):
            update = event.data
            author = update.author_name
            if author != last_author:
                if last_author is not None:
                    print()
                print(f"{author}: {update.text}", end="", flush=True)
                last_author = author
            else:
                print(update.text, end="", flush=True)

Stap 6: Hoofdfunctie voltooien

Verpakt alles in de hoofdfunctie met de juiste asynchrone uitvoering:

if __name__ == "__main__":
    asyncio.run(main())

Hoe het werkt

  1. Clientinstallatie: gebruikt één FoundryChatClient met Azure CLI-referenties voor authenticatie.
  2. Agent maken: hiermee maakt u schrijf- en revisoragents op basis van dezelfde clientconfiguratie.
  3. Sequentiële verwerking: de schrijveragent genereert eerst inhoud en geeft deze vervolgens door aan de revisoragent.
  4. Streaming-updates: uitvoergebeurtenissen (type="output") met AgentResponseUpdate gegevens bieden realtime token-updates terwijl agenten antwoorden genereren.

Belangrijkste concepten

  • FoundryChatClient: Gedeelde client die wordt gebruikt voor het maken van werkstroomagents met consistente configuratie.
  • WorkflowEvent: uitvoergebeurtenissen (type="output") bevatten uitvoergegevens van agents (AgentResponseUpdate voor streaming, AgentResponse voor niet-streaming).
  • Sequentiële werkstroom: agents die zijn verbonden in een pijplijn, waarbij uitvoer van het ene naar het andere stroomt.

Implementatie voltooien

Zie azure_ai_agents_streaming.py in de agentframeworkopslagplaats voor de volledige werkimplementatie.

Wat je gaat bouwen

U maakt een werkstroom die:

  • Gebruikt Microsoft Foundry modeluitrolagents als werkstroomexecutors
  • Implementeert een Franse vertaalagent
  • Implementeert een Spaanse vertaalagent
  • Implementeert een Engelse vertaalagent
  • Verbindt agents met elkaar in een sequentiële werkstroompijpleiding
  • Streamt realtime updates als agents aanvragen verwerken

Besproken concepten

Prerequisites

  • Go 1.26 of hoger
  • Microsoft Foundry-projecteindpunt en -modelimplementatie geconfigureerd
  • Azure CLI-authenticatie of een andere bron voor Azure-aanmeldingsgegevens

Initialiseer in een nieuwe map een Go-module en installeer Agent Framework:

go mod init example.com/agent-workflow
go get github.com/microsoft/agent-framework-go

Stel het projecteindpunt en de naam van het geïmplementeerde model in:

$env:FOUNDRY_PROJECT_ENDPOINT = "https://<resource>.services.ai.azure.com/api/projects/<project>"
$env:FOUNDRY_MODEL = "<deployment-name>"

Stap 1: Configuratie van Foundry instellen

In de volgende secties wordt de runExample functie in de volledige implementatie gebouwd. Begin met de import en configuratie:

import (
    "context"
    "errors"
    "fmt"
    "log"
    "os"
    "strings"

    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
    "github.com/microsoft/agent-framework-go/agent"
    "github.com/microsoft/agent-framework-go/message"
    "github.com/microsoft/agent-framework-go/provider/foundryprovider"
    "github.com/microsoft/agent-framework-go/workflow"
    "github.com/microsoft/agent-framework-go/workflow/agentworkflow"
    "github.com/microsoft/agent-framework-go/workflow/inproc"
)

endpoint := strings.TrimSpace(os.Getenv("FOUNDRY_PROJECT_ENDPOINT"))
if endpoint == "" {
    return fmt.Errorf("set FOUNDRY_PROJECT_ENDPOINT")
}
model := strings.TrimSpace(os.Getenv("FOUNDRY_MODEL"))
if model == "" {
    return fmt.Errorf("set FOUNDRY_MODEL to your model deployment name")
}

token, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
    return err
}

Warning

azidentity.NewDefaultAzureCredential is handig voor ontwikkeling, maar vereist zorgvuldige overwegingen in de productieomgeving. In productie kunt u overwegen om een specifieke referentie te gebruiken, zoals azidentity.NewManagedIdentityCredential, om latentieproblemen, onbedoelde referentieprobing en potentiële beveiligingsrisico's van terugvalmechanismen te voorkomen.

Stap 2: Agent Factory-functie maken

Agents maken met specifieke vertaalinstructies:

newTranslationAgent := func(language string) *agent.Agent {
    return foundryprovider.NewAgent(endpoint, token, foundryprovider.ModelDeployment(model), foundryprovider.AgentConfig{
        Instructions: fmt.Sprintf(
            "Translate the user's text to %s. Return only the translation.",
            language,
        ),
        Config: agent.Config{Name: language + "Agent"},
    })
}

Stap 3: Gespecialiseerde Foundry-agents maken

frenchAgent := newTranslationAgent("French")
spanishAgent := newTranslationAgent("Spanish")
englishAgent := newTranslationAgent("English")

Stap 4: De werkstroom bouwen

Agents kunnen worden gebruikt als uitvoerders van workflows, waardoor door AI aangestuurde workflowstappen mogelijk zijn.

Bind elke agent als een werkstroomexecutor en verbind vervolgens de uitvoerders met randen:

cfg := agentworkflow.Config{ForwardIncomingMessages: new(false)}
french := agentworkflow.New(frenchAgent, cfg)
spanish := agentworkflow.New(spanishAgent, cfg)
english := agentworkflow.New(englishAgent, cfg)

wf, err := workflow.NewBuilder(french).
    AddEdge(french, spanish).
    AddEdge(spanish, english).
    WithIntermediateOutputFrom(french, spanish).
    WithOutputFrom(english).
    Build()
if err != nil {
    return err
}

ForwardIncomingMessages: new(false) geeft het antwoord van elke agent downstream door zonder ook de invoer van die agent door te sturen. Elke gehoste executor beheert een eigen agentsessie.

Registreer Frans en Spaans als tussenliggende uitvoerbronnen, zodat bellers alle drie de agents kunnen observeren. Engels blijft de bron van de terminaluitvoer. Uitvoerbenaming bepaalt wat de aanroeper ziet, niet welke berichten langs de verbindingen stromen.

Stap 5: Uitvoeren met streaming

Voer de workflow uit en schakel update-gebeurtenissen in met een workflow.TurnToken. Werkstroomfouten en fouten van de gebeurtenis-iterator afhandelen:

run, err := inproc.Default.RunStreaming(ctx, wf, message.NewText("Hello World"))
if err != nil {
    return err
}
defer func() {
    err = errors.Join(err, run.Close(context.WithoutCancel(ctx)))
}()

emitEvents := true
if accepted, err := run.TrySendMessage(ctx, workflow.TurnToken{EmitEvents: &emitEvents}); err != nil {
    return err
} else if !accepted {
    return fmt.Errorf("workflow doesn't accept turn tokens")
}

lastExecutorID := ""
for evt, streamErr := range run.WatchStream(ctx) {
    if streamErr != nil {
        return streamErr
    }
    switch event := evt.(type) {
    case workflow.OutputEvent:
        update, ok := event.Output.(*agent.ResponseUpdate)
        if !ok || update.String() == "" {
            continue
        }
        if event.ExecutorID != lastExecutorID {
            if lastExecutorID != "" {
                fmt.Println()
            }
            fmt.Printf("%s: ", event.ExecutorID)
            lastExecutorID = event.ExecutorID
        }
        fmt.Print(update.String())
    case workflow.ErrorEvent:
        return event.Error
    case workflow.ExecutorFailedEvent:
        return fmt.Errorf("executor %q failed: %w",
            event.ExecutorID, event.Error)
    }
}
if lastExecutorID != "" {
    fmt.Println()
}

De uitvoer bevat Franse, Spaanse en Engelse vertalingen, gegroepeerd op uitvoerder. Het volledige voorbeeld keert terug van runExample voordat een fatale fout wordt gelogd, zodat het opschonen van de werkstroom nog steeds wordt uitgevoerd.

In tegenstelling tot het C#-voorbeeld maakt dit Go-voorbeeld geen opgeslagen agentversies die moeten worden verwijderd in Foundry.

Hoe het werkt

  1. Clientconfiguratie: maakt gebruik van een Foundry-projecteindpunt, modelimplementatie en Azure-aanmeldingsgegevens.
  2. Agent maken: Hiermee maakt u gespecialiseerde agents met taalspecifieke instructies.
  3. Agenthosting: Gebruikt agentworkflow.New om elke agent te koppelen als workflowuitvoerder.
  4. Sequentiële verwerking: De Franse executor wordt eerst uitgevoerd, vervolgens Spaans en vervolgens Engels.
  5. Turn-tokenpatroon: Gehoste agents bufferen berichten en worden uitgevoerd wanneer ze een workflow.TurnToken ontvangen.
  6. Streamingupdates: registraties van tussenliggende en einduitvoer maken updates van alle drie de agents beschikbaar.
  7. Foutafhandeling: de host controleert ErrorEvent en ExecutorFailedEvent en sluit de werkstroomuitvoering voordat er een fout wordt gerapporteerd.

Belangrijkste concepten

  • Foundry-agent: Een agent.Agent agent die wordt ondersteund door een Foundry-modelimplementatie.
  • agentworkflow. Nieuw: Hiermee past u een agent aan voor gebruik als werkstroomexecutor.
  • Workflow. TurnToken: Signaal dat gehoste agents activeert om gebufferde berichten te verwerken.
  • Workflow OutputEvent: voert antwoordupdates van agents en uiteindelijke werkstroomuitvoer uit.
  • Sequentiële werkstroom: agents die zijn verbonden in een pijplijn, waarbij uitvoer van het ene naar het andere stroomt.

Implementatie voltooien

Sla dit voorbeeld op als main.go in uw Go-module:

package main

import (
    "context"
    "errors"
    "fmt"
    "log"
    "os"
    "strings"

    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
    "github.com/microsoft/agent-framework-go/agent"
    "github.com/microsoft/agent-framework-go/message"
    "github.com/microsoft/agent-framework-go/provider/foundryprovider"
    "github.com/microsoft/agent-framework-go/workflow"
    "github.com/microsoft/agent-framework-go/workflow/agentworkflow"
    "github.com/microsoft/agent-framework-go/workflow/inproc"
)

func main() {
    if err := runExample(context.Background()); err != nil {
        log.Fatal(err)
    }
}

func runExample(ctx context.Context) (err error) {
    endpoint := strings.TrimSpace(os.Getenv("FOUNDRY_PROJECT_ENDPOINT"))
    if endpoint == "" {
        return fmt.Errorf("set FOUNDRY_PROJECT_ENDPOINT")
    }
    model := strings.TrimSpace(os.Getenv("FOUNDRY_MODEL"))
    if model == "" {
        return fmt.Errorf("set FOUNDRY_MODEL to your model deployment name")
    }

    token, err := azidentity.NewDefaultAzureCredential(nil)
    if err != nil {
        return err
    }

    newTranslationAgent := func(language string) *agent.Agent {
        return foundryprovider.NewAgent(
            endpoint,
            token,
            foundryprovider.ModelDeployment(model),
            foundryprovider.AgentConfig{
                Instructions: fmt.Sprintf(
                    "Translate the user's text to %s. Return only the translation.",
                    language,
                ),
                Config: agent.Config{Name: language + "Agent"},
            },
        )
    }

    cfg := agentworkflow.Config{ForwardIncomingMessages: new(false)}
    french := agentworkflow.New(newTranslationAgent("French"), cfg)
    spanish := agentworkflow.New(newTranslationAgent("Spanish"), cfg)
    english := agentworkflow.New(newTranslationAgent("English"), cfg)

    wf, err := workflow.NewBuilder(french).
        AddEdge(french, spanish).
        AddEdge(spanish, english).
        WithIntermediateOutputFrom(french, spanish).
        WithOutputFrom(english).
        Build()
    if err != nil {
        return err
    }

    run, err := inproc.Default.RunStreaming(ctx, wf, message.NewText("Hello World"))
    if err != nil {
        return err
    }
    defer func() {
        err = errors.Join(err, run.Close(context.WithoutCancel(ctx)))
    }()

    emitEvents := true
    if accepted, err := run.TrySendMessage(ctx, workflow.TurnToken{EmitEvents: &emitEvents}); err != nil {
        return err
    } else if !accepted {
        return fmt.Errorf("workflow doesn't accept turn tokens")
    }

    lastExecutorID := ""
    for evt, streamErr := range run.WatchStream(ctx) {
        if streamErr != nil {
            return streamErr
        }
        switch event := evt.(type) {
        case workflow.OutputEvent:
            update, ok := event.Output.(*agent.ResponseUpdate)
            if !ok || update.String() == "" {
                continue
            }
            if event.ExecutorID != lastExecutorID {
                if lastExecutorID != "" {
                    fmt.Println()
                }
                fmt.Printf("%s: ", event.ExecutorID)
                lastExecutorID = event.ExecutorID
            }
            fmt.Print(update.String())
        case workflow.ErrorEvent:
            return event.Error
        case workflow.ExecutorFailedEvent:
            return fmt.Errorf("executor %q failed: %w",
                event.ExecutorID, event.Error)
        }
    }
    if lastExecutorID != "" {
        fmt.Println()
    }
    return nil
}

Voer het voorbeeld uit:

go run .

Warning

azidentity.NewDefaultAzureCredential is handig voor ontwikkeling, maar vereist zorgvuldige overwegingen in de productieomgeving. In productie kunt u overwegen om een specifieke referentie te gebruiken, zoals azidentity.NewManagedIdentityCredential, om latentieproblemen, onbedoelde referentieprobing en potentiële beveiligingsrisico's van terugvalmechanismen te voorkomen.

Tip

Zie het voorbeeld van agents in workflows voor een andere uitvoerbare vertaalpijplijn.

Volgende stappen

Human-in-the-Loop

  • Laatst bijgewerkt om