Etapa 7: Hospede seu agente

Hospedagem no ASP.NET Core

O Agent Framework fornece bibliotecas de hospedagem que permitem integrar agentes de IA a aplicativos ASP.NET Core. Essas bibliotecas simplificam o registro, a configuração e a exposição de agentes por meio de vários protocolos.

Conforme descrito em Agentes, AIAgent é a abstração de agente fundamental no Agent Framework. Ele define um "wrapper LLM" que processa as entradas do usuário, toma decisões, chama ferramentas e realiza o trabalho adicional para executar as ações e gerar respostas. Expor agentes de IA de seu aplicativo ASP.NET Core não é trivial. As bibliotecas de hospedagem resolvem isso registrando agentes de IA em um contêiner de injeção de dependência, permitindo que você resolva e use-as em seus serviços de aplicativo. Eles também permitem que você gerencie dependências de agente, como ferramentas e armazenamento de sessão, do mesmo contêiner. Os agentes podem ser hospedados junto com sua infraestrutura de aplicativo, independentemente dos protocolos que eles usam. Da mesma forma, os fluxos de trabalho podem ser hospedados e aproveitar a infraestrutura comum do aplicativo.

Biblioteca de hospedagem principal

A Microsoft.Agents.AI.Hosting biblioteca é a base para hospedar agentes de IA no ASP.NET Core. Ele fornece extensões para IHostApplicationBuilder registrar e configurar agentes de IA e fluxos de trabalho. No ASP.NET Core, IHostApplicationBuilder é o tipo fundamental que representa o construtor para aplicativos e serviços hospedados, gerenciando a configuração, o registro em log, o tempo de vida e muito mais.

Antes de configurar agentes ou fluxos de trabalho, registre um IChatClient no contêiner de injeção de dependência. Nos exemplos a seguir, está registrado como um singleton identificado por chave com o nome chat-model:

// endpoint is your Microsoft Foundry project endpoint
// deploymentName is 'gpt-4o-mini' for example

IChatClient chatClient = new AIProjectClient(
        new Uri(endpoint),
        new DefaultAzureCredential())
    .GetProjectOpenAIClient()
    .GetProjectResponsesClient()
    .AsIChatClient(deploymentName);
builder.Services.AddSingleton(chatClient);

AddAIAgent

Registre um agente de IA com injeção de dependência:

var pirateAgent = builder.AddAIAgent(
    "pirate",
    instructions: "You are a pirate. Speak like a pirate",
    description: "An agent that speaks like a pirate.",
    chatClientServiceKey: "chat-model");

O AddAIAgent() método retorna um IHostedAgentBuilder, que fornece métodos de extensão para configurar o agente. Por exemplo, você pode adicionar ferramentas ao agente:

var pirateAgent = builder.AddAIAgent("pirate", instructions: "You are a pirate. Speak like a pirate")
    .WithAITool(new MyTool()); // MyTool is a custom type derived from AITool

Você também pode configurar o repositório de sessão (armazenamento para dados de conversa):

var pirateAgent = builder.AddAIAgent("pirate", instructions: "You are a pirate. Speak like a pirate")
    .WithInMemorySessionStore();

AddWorkflow

Registre fluxos de trabalho que coordenam vários agentes. Um fluxo de trabalho é essencialmente um "gráfico" em que cada nó é um AIAgent e os agentes se comunicam entre si.

Neste exemplo, dois agentes funcionam sequencialmente. A entrada do usuário é enviada primeiro para agent-1, o que produz uma resposta e a envia para agent-2. Em seguida, o fluxo de trabalho gera a resposta final. Há também um BuildConcurrent método que cria um fluxo de trabalho de agente simultâneo.

builder.AddAIAgent("agent-1", instructions: "you are agent 1!");
builder.AddAIAgent("agent-2", instructions: "you are agent 2!");

var workflow = builder.AddWorkflow("my-workflow", (sp, key) =>
{
    var agent1 = sp.GetRequiredKeyedService<AIAgent>("agent-1");
    var agent2 = sp.GetRequiredKeyedService<AIAgent>("agent-2");
    return AgentWorkflowBuilder.BuildSequential(key, [agent1, agent2]);
});

Expor o fluxo de trabalho como AIAgent

Para usar integrações de protocolo (como A2A ou OpenAI) com um fluxo de trabalho, converta-o em um agente autônomo. Atualmente, os fluxos de trabalho não fornecem recursos de integração semelhantes por conta própria, portanto, essa etapa de conversão é necessária:

var workflowAsAgent = builder
    .AddWorkflow("science-workflow", (sp, key) => { ... })
    .AddAsAIAgent();  // Now the workflow can be used as an agent

Detalhes da implementação

As bibliotecas de hospedagem atuam como adaptadores de protocolo que fazem a ponte entre os protocolos de comunicação externa e a implementação interna AIAgent do Agent Framework. Quando você usa uma biblioteca de integração de hospedagem, a biblioteca recupera o registrado AIAgent da injeção de dependência, encapsula-o com middleware específico do protocolo para traduzir as solicitações recebidas e as respostas enviadas e invoca AIAgent para processar as solicitações. Essa arquitetura mantém a implementação do agente indiferente ao protocolo.

Por exemplo, usando a biblioteca de hospedagem do ASP.NET Core com o adaptador de protocolo A2A:

// Register the agent
var pirateAgent = builder.AddAIAgent("pirate",
    instructions: "You are a pirate. Speak like a pirate",
    description: "An agent that speaks like a pirate.");

// Expose via a protocol (e.g. A2A)
builder.Services.AddA2AServer();
var app = builder.Build();
app.MapA2AServer();
app.Run();

Microsoft Foundry Hosted Agents é a principal opção de hospedagem gerenciada. Conclua os pré-requisitos dos Agentes Hospedados da Foundry, incluindo a extensão do agente de IA da CLI do Desenvolvedor do Azure e o login na CLI do Azure.

O exemplo de introdução cria um agente com o armazenamento de modelos do lado do servidor desabilitado e inicia um ResponsesHostServer:

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient, ResponsesHostServer
from azure.identity import DefaultAzureCredential


def main() -> None:
    agent = Agent(
        client=FoundryChatClient(
            project_endpoint="https://your-account.services.ai.azure.com/api/projects/your-project",
            model="gpt-6-luna",
            credential=DefaultAzureCredential(),
        ),
        instructions="You are a friendly assistant. Keep your answers brief.",
        default_options={"store": False},
    )
    ResponsesHostServer(agent=agent, history_source="agent_server").run()


if __name__ == "__main__":
    main()

Substitua o ponto de extremidade do projeto codificado e o nome de implantação do modelo e execute o exemplo PEP 723 localmente na raiz do repositório do Agent Framework:

uv run python/samples/01-get-started/07_hosting.py

Para implantar um projeto completo de agente hospedado, inicialize-o a partir do manifesto de hospedagem mantido:

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

Execute o host do agente:

azd ai agent run

Em outro terminal, invoque o agente local:

azd ai agent invoke --local "Hello!"

Hospedagem com o Protocolo A2A

A porta do Go oferece hospedagem A2A por meio de a2aprovider, que encapsula um agente em um manipulador HTTP compatível com o protocolo Agent-to-Agent.

Criar um agente:

import (
    "github.com/microsoft/agent-framework-go/agent"
    "github.com/microsoft/agent-framework-go/provider/a2aprovider"
    "github.com/microsoft/agent-framework-go/provider/foundryprovider"

    "github.com/a2aproject/a2a-go/v2/a2a"
    "github.com/a2aproject/a2a-go/v2/a2asrv"
)

a := foundryprovider.NewAgent(endpoint, token, foundryprovider.ModelDeployment(model), foundryprovider.AgentConfig{
    Instructions: "You are a helpful assistant.",
    Config: agent.Config{
    },
})

Exponha o agente por meio de A2A:

url := "http://localhost:5000"
card := &a2a.AgentCard{
    Name:               "MyAgent",
    Description:        "A helpful assistant.",
    Version:            "1.0.0",
    DefaultInputModes:  []string{"text"},
    DefaultOutputModes: []string{"text"},
    Capabilities:       a2a.AgentCapabilities{Streaming: false},
    SupportedInterfaces: []*a2a.AgentInterface{
        a2a.NewAgentInterface(url, a2a.TransportProtocolJSONRPC),
    },
}

mux := http.NewServeMux()
requestHandler := a2asrv.NewHandler(
    a2aprovider.NewExecutor(a, a2aprovider.ExecutorConfig{}),
    a2asrv.WithExtendedAgentCard(card),
)
mux.Handle("/", a2asrv.NewJSONRPCHandler(requestHandler))
mux.Handle(a2asrv.WellKnownAgentCardPath, a2asrv.NewStaticAgentCardHandler(card))

log.Println("A2A server listening on :5000")
http.ListenAndServe(":5000", mux)