Passo 7: Aloje o seu agente

Alojamento no ASP.NET Core

O Agent Framework fornece bibliotecas de alojamento que permitem integrar agentes de IA nas ASP.NET aplicações Core. Estas bibliotecas simplificam o registo, configuração e exposição de agentes através de vários protocolos.

Como descrito em Agentes, AIAgent é a abstração fundamental de agentes no Agent Framework. Define um "wrapper LLM" que processa as entradas do utilizador, toma decisões, chama ferramentas e realiza trabalho adicional para executar ações e gerar respostas. Expor agentes de IA da sua aplicação ASP.NET Core não é trivial. As bibliotecas de alojamento resolvem isto registando agentes de IA num contentor de injeção de dependências, permitindo-lhe resolvê-los e usá-los nos seus serviços de aplicação. Também permitem gerir dependências de agentes, como ferramentas e armazenamento de sessões, a partir do mesmo contentor. Os agentes podem ser alojados juntamente com a infraestrutura da sua aplicação, independentemente dos protocolos que utilizam. De forma semelhante, os fluxos de trabalho podem ser alojados e tirar partido da infraestrutura comum da sua aplicação.

Biblioteca Principal de Alojamento

A Microsoft.Agents.AI.Hosting biblioteca é a base para alojar agentes de IA no ASP.NET Core. Fornece extensões para IHostApplicationBuilder registar e configurar agentes e fluxos de trabalho de IA. No contexto do ASP.NET Core, IHostApplicationBuilder é o tipo fundamental que representa o construtor para aplicações e serviços alojados, gerindo configuração, registos, ciclo de vida e muito mais.

Antes de configurar agentes ou fluxos de trabalho, regista um IChatClient no contentor de injeção de dependências. Nos exemplos abaixo, está registado como um singleton chaveado sob 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);

Adicionar Agente de IA

Registar 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 devolve um IHostedAgentBuilder, que fornece métodos de extensão para configurar o agente. Por exemplo, 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

Também pode configurar o armazenamento de sessões (armazenamento para dados de conversa):

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

AddWorkflow

Registar fluxos de trabalho que coordenam múltiplos agentes. Um fluxo de trabalho é essencialmente um "grafo" onde cada nó é um AIAgent, e os agentes comunicam entre si.

Neste exemplo, dois agentes funcionam sequencialmente. A entrada do utilizador é enviada primeiro para agent-1, que produz uma resposta e envia-a para agent-2. O fluxo de trabalho depois gera a resposta final. Existe também um BuildConcurrent método que cria um fluxo de trabalho de agente concorrente.

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 Workflow como AIAgent

Para usar integrações de protocolos (como A2A ou OpenAI) com um fluxo de trabalho, converta-o num agente autónomo. Atualmente, os fluxos de trabalho não oferecem capacidades de integração semelhantes por si só, pelo que este passo de conversão é necessário:

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 alojamento atuam como adaptadores de protocolo que ligam protocolos de comunicação externos e a implementação interna AIAgent do Agent Framework. Quando usa uma biblioteca de integração de alojamento, a biblioteca obtém o registo AIAgent da injeção de dependências, envolve-o com middleware específico do protocolo para traduzir pedidos recebidos e respostas de saída, e invoca o AIAgent para processar pedidos. Esta arquitetura mantém a implementação do seu agente independente do protocolo.

Por exemplo, usando a biblioteca de alojamento 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();

Os Microsoft Foundry Hosted Agents são a principal opção de alojamento gerido. Complete os pré-requisitos para Foundry Hosted Agents, incluindo a extensão do agente AI para CLI do Azure Developer e o login do CLI do Azure.

O exemplo get-start cria um agente com o armazenamento do modelo do lado do servidor desativado e inicia um agente 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 endpoint do projeto codificado e o nome da implementação do modelo, depois execute localmente a amostra PEP 723 a partir da raiz do repositório Agent Framework:

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

Para implementar um projeto completo de agente alojado, 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

Executar o anfitrião do agente:

azd ai agent run

Noutro terminal, invoque o agente local:

azd ai agent invoke --local "Hello!"

Hospedagem com o Protocolo A2A

A porta Go fornece alojamento A2A através de a2aprovider, que envolve um agente num handler HTTP compatível com o protocolo Agente-para-Agente.

Crie 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 via 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)