Renderização de ferramenta de back-end com AG-UI

Este tutorial mostra como adicionar ferramentas de função aos seus agentes de AG-UI. As ferramentas de função são métodos C# personalizados que o agente pode chamar para executar tarefas específicas, como recuperar dados, executar cálculos ou interagir com sistemas externos. Com o AG-UI, essas ferramentas são executadas no back-end e seus resultados são transmitidos automaticamente para o cliente.

Pré-requisitos

Antes de começar, verifique se você concluiu o tutorial de Introdução e tenha:

.NET 8.0 ou posterior
Microsoft.Agents.AI.Hosting.AGUI.AspNetCore pacote instalado
Serviço Azure OpenAI configurado
Noções básicas sobre AG-UI configuração do servidor e do cliente

O que é renderização de ferramenta de back-end?

A renderização realizada por ferramentas de back-end significa:

As ferramentas de função são definidas no servidor
O agente de IA decide quando chamar essas ferramentas
Ferramentas executadas no back-end (lado do servidor)
Os eventos e os resultados da chamada de ferramenta são transmitidos para o cliente em tempo real
O cliente recebe atualizações sobre o progresso da execução da ferramenta

Criando um servidor AG-UI com ferramentas de função

Aqui está uma implementação completa do servidor que demonstra como registrar ferramentas com tipos de parâmetro complexos:

// Copyright (c) Microsoft. All rights reserved.

using System.ComponentModel;
using System.Text.Json.Serialization;
using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Hosting.AGUI.AspNetCore;
using Microsoft.Extensions.AI;
using Microsoft.Extensions.Options;
using OpenAI.Chat;

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
builder.Services.AddHttpClient().AddLogging();
builder.Services.ConfigureHttpJsonOptions(options =>
    options.SerializerOptions.TypeInfoResolverChain.Add(SampleJsonSerializerContext.Default));
builder.Services.AddAGUI();

WebApplication app = builder.Build();

string endpoint = builder.Configuration["AZURE_OPENAI_ENDPOINT"]
    ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
string deploymentName = builder.Configuration["AZURE_OPENAI_DEPLOYMENT_NAME"]
    ?? throw new InvalidOperationException("AZURE_OPENAI_DEPLOYMENT_NAME is not set.");

// Define request/response types for the tool
internal sealed class RestaurantSearchRequest
{
    public string Location { get; set; } = string.Empty;
    public string Cuisine { get; set; } = "any";
}

internal sealed class RestaurantSearchResponse
{
    public string Location { get; set; } = string.Empty;
    public string Cuisine { get; set; } = string.Empty;
    public RestaurantInfo[] Results { get; set; } = [];
}

internal sealed class RestaurantInfo
{
    public string Name { get; set; } = string.Empty;
    public string Cuisine { get; set; } = string.Empty;
    public double Rating { get; set; }
    public string Address { get; set; } = string.Empty;
}

// JSON serialization context for source generation
[JsonSerializable(typeof(RestaurantSearchRequest))]
[JsonSerializable(typeof(RestaurantSearchResponse))]
internal sealed partial class SampleJsonSerializerContext : JsonSerializerContext;

// Define the function tool
[Description("Search for restaurants in a location.")]
static RestaurantSearchResponse SearchRestaurants(
    [Description("The restaurant search request")] RestaurantSearchRequest request)
{
    // Simulated restaurant data
    string cuisine = request.Cuisine == "any" ? "Italian" : request.Cuisine;

    return new RestaurantSearchResponse
    {
        Location = request.Location,
        Cuisine = request.Cuisine,
        Results =
        [
            new RestaurantInfo
            {
                Name = "The Golden Fork",
                Cuisine = cuisine,
                Rating = 4.5,
                Address = $"123 Main St, {request.Location}"
            },
            new RestaurantInfo
            {
                Name = "Spice Haven",
                Cuisine = cuisine == "Italian" ? "Indian" : cuisine,
                Rating = 4.7,
                Address = $"456 Oak Ave, {request.Location}"
            },
            new RestaurantInfo
            {
                Name = "Green Leaf",
                Cuisine = "Vegetarian",
                Rating = 4.3,
                Address = $"789 Elm Rd, {request.Location}"
            }
        ]
    };
}

// Get JsonSerializerOptions from the configured HTTP JSON options
Microsoft.AspNetCore.Http.Json.JsonOptions jsonOptions = app.Services.GetRequiredService<IOptions<Microsoft.AspNetCore.Http.Json.JsonOptions>>().Value;

// Create tool with serializer options
AITool[] tools =
[
    AIFunctionFactory.Create(
        SearchRestaurants,
        serializerOptions: jsonOptions.SerializerOptions)
];

// Create the AI agent with tools
ChatClient chatClient = new AzureOpenAIClient(
        new Uri(endpoint),
        new DefaultAzureCredential())
    .GetChatClient(deploymentName);

ChatClientAgent agent = chatClient.AsIChatClient().AsAIAgent(
    name: "AGUIAssistant",
    instructions: "You are a helpful assistant with access to restaurant information.",
    tools: tools);

// Map the AG-UI agent endpoint
app.MapAGUI("/", agent);

await app.RunAsync();

Conceitos Principais

Execução no lado do servidor: ferramentas executadas no processo do servidor
Streaming automático: as chamadas e os resultados da ferramenta são transmitidos para clientes em tempo real

Importante

Ao criar ferramentas com tipos de parâmetro complexos (objetos, matrizes etc.), você deve fornecer o serializerOptions parâmetro para AIFunctionFactory.Create(). As opções de serializador devem ser obtidas do aplicativo configurado JsonOptions por meio IOptions<Microsoft.AspNetCore.Http.Json.JsonOptions> para garantir a consistência com o restante da serialização JSON do aplicativo.

Executando o servidor

Defina variáveis de ambiente e execute:

export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"
export AZURE_OPENAI_DEPLOYMENT_NAME="gpt-4o-mini"
dotnet run --urls http://localhost:8888

Observando chamadas de ferramenta no cliente

O cliente básico no tutorial 'Começando' exibe a resposta final de texto do agente. No entanto, você pode estendê-lo para observar as chamadas de ferramenta e os resultados conforme eles são transmitidos do servidor.

Exibindo detalhes de execução da ferramenta

Para ver chamadas de ferramenta e resultados em tempo real, estenda o loop de streaming do cliente para manipular FunctionCallContent e FunctionResultContent:

// Inside the streaming loop from getting-started.md
await foreach (AgentResponseUpdate update in agent.RunStreamingAsync(messages, session))
{
    ChatResponseUpdate chatUpdate = update.AsChatResponseUpdate();

    // ... existing run started code ...

    // Display streaming content
    foreach (AIContent content in update.Contents)
    {
        switch (content)
        {
            case TextContent textContent:
                Console.ForegroundColor = ConsoleColor.Cyan;
                Console.Write(textContent.Text);
                Console.ResetColor();
                break;

            case FunctionCallContent functionCallContent:
                Console.ForegroundColor = ConsoleColor.Green;
                Console.WriteLine($"\n[Function Call - Name: {functionCallContent.Name}]");

                // Display individual parameters
                if (functionCallContent.Arguments != null)
                {
                    foreach (var kvp in functionCallContent.Arguments)
                    {
                        Console.WriteLine($"  Parameter: {kvp.Key} = {kvp.Value}");
                    }
                }
                Console.ResetColor();
                break;

            case FunctionResultContent functionResultContent:
                Console.ForegroundColor = ConsoleColor.Magenta;
                Console.WriteLine($"\n[Function Result - CallId: {functionResultContent.CallId}]");

                if (functionResultContent.Exception != null)
                {
                    Console.WriteLine($"  Exception: {functionResultContent.Exception}");
                }
                else
                {
                    Console.WriteLine($"  Result: {functionResultContent.Result}");
                }
                Console.ResetColor();
                break;

            case ErrorContent errorContent:
                Console.ForegroundColor = ConsoleColor.Red;
                Console.WriteLine($"\n[Error: {errorContent.Message}]");
                Console.ResetColor();
                break;
        }
    }
}

Saída esperada com chamadas de ferramenta

Quando o agente acessar ferramentas de backend, você verá:

User (:q or quit to exit): What's the weather like in Amsterdam?

[Run Started - Thread: thread_abc123, Run: run_xyz789]

[Function Call - Name: SearchRestaurants]
  Parameter: Location = Amsterdam
  Parameter: Cuisine = any

[Function Result - CallId: call_def456]
  Result: {"Location":"Amsterdam","Cuisine":"any","Results":[...]}

The weather in Amsterdam is sunny with a temperature of 22°C. Here are some 
great restaurants in the area: The Golden Fork (Italian, 4.5 stars)...
[Run Finished - Thread: thread_abc123]

Conceitos Principais

FunctionCallContent: representa uma ferramenta que está sendo chamada com seus Name e Arguments (pares chave-valor)
FunctionResultContent: contém a ferramenta Result ou Exception, identificada por CallId

Próximas etapas

Agora que você pode adicionar ferramentas de função, você pode:

Ferramentas de front-end: adicionar ferramentas de front-end.

Testar com o Dojo: usar o aplicativo Dojo da interface do usuário do AG para testar seus agentes

Recursos adicionais

Este tutorial mostra como adicionar ferramentas de função aos seus agentes de AG-UI. As ferramentas de função são funções personalizadas do Python que o agente pode chamar para executar tarefas específicas, como recuperar dados, executar cálculos ou interagir com sistemas externos. Com o AG-UI, essas ferramentas são executadas no back-end e seus resultados são transmitidos automaticamente para o cliente.

Pré-requisitos

Antes de começar, verifique se você concluiu o tutorial de Introdução e tenha:

Python 3.10 ou posterior
agent-framework-ag-ui Instalado
Serviço Azure OpenAI configurado
Noções básicas sobre AG-UI configuração do servidor e do cliente

Observação

Esses exemplos usam DefaultAzureCredential para autenticação. Verifique se você está autenticado com o Azure (por exemplo, via az login). Para obter mais informações, consulte a documentação da Identidade do Azure.

O que é renderização de ferramenta de back-end?

A renderização realizada por ferramentas de back-end significa:

As ferramentas de função são definidas no servidor
O agente de IA decide quando chamar essas ferramentas
Ferramentas executadas no back-end (lado do servidor)
Os eventos e os resultados da chamada de ferramenta são transmitidos para o cliente em tempo real
O cliente recebe atualizações sobre o progresso da execução da ferramenta

Essa abordagem fornece:

Segurança: as operações confidenciais permanecem no servidor
Consistência: todos os clientes usam as mesmas implementações de ferramenta
Transparência: os clientes podem exibir o progresso da execução da ferramenta
Flexibilidade: atualizar ferramentas sem alterar o código do cliente

Criando ferramentas de funções

Ferramenta de Função Básica

Você pode transformar qualquer função python em uma ferramenta usando o @tool decorador:

from typing import Annotated
from pydantic import Field
from agent_framework import tool


@tool
def get_weather(
    location: Annotated[str, Field(description="The city")],
) -> str:
    """Get the current weather for a location."""
    # In a real application, you would call a weather API
    return f"The weather in {location} is sunny with a temperature of 22°C."

Conceitos Principais

@tool decorador: marca uma função como disponível para o agente
Anotações de tipo: fornecer informações de tipo para parâmetros
Annotated e Field: adicionar descrições para ajudar o agente a entender os parâmetros
Docstring: descreve o que a função faz (ajuda o agente a decidir quando usá-la)
Valor retornado: o resultado retornado ao agente (e transmitido para o cliente)

Ferramentas Multifuncionais

Você pode fornecer várias ferramentas para dar ao agente mais funcionalidades:

from typing import Any
from agent_framework import tool


@tool
def get_weather(
    location: Annotated[str, Field(description="The city.")],
) -> str:
    """Get the current weather for a location."""
    return f"The weather in {location} is sunny with a temperature of 22°C."


@tool
def get_forecast(
    location: Annotated[str, Field(description="The city.")],
    days: Annotated[int, Field(description="Number of days to forecast")] = 3,
) -> dict[str, Any]:
    """Get the weather forecast for a location."""
    return {
        "location": location,
        "days": days,
        "forecast": [
            {"day": 1, "weather": "Sunny", "high": 24, "low": 18},
            {"day": 2, "weather": "Partly cloudy", "high": 22, "low": 17},
            {"day": 3, "weather": "Rainy", "high": 19, "low": 15},
        ],
    }

Criando um servidor AG-UI com ferramentas de função

Aqui está uma implementação completa do servidor com ferramentas de função:

"""AG-UI server with backend tool rendering."""

import os
from typing import Annotated, Any

from agent_framework import Agent, tool
from agent_framework.azure import AzureOpenAIChatClient
from agent_framework_ag_ui import add_agent_framework_fastapi_endpoint
from azure.identity import AzureCliCredential
from fastapi import FastAPI
from pydantic import Field


# Define function tools
@tool
def get_weather(
    location: Annotated[str, Field(description="The city")],
) -> str:
    """Get the current weather for a location."""
    # Simulated weather data
    return f"The weather in {location} is sunny with a temperature of 22°C."


@tool
def search_restaurants(
    location: Annotated[str, Field(description="The city to search in")],
    cuisine: Annotated[str, Field(description="Type of cuisine")] = "any",
) -> dict[str, Any]:
    """Search for restaurants in a location."""
    # Simulated restaurant data
    return {
        "location": location,
        "cuisine": cuisine,
        "results": [
            {"name": "The Golden Fork", "rating": 4.5, "price": "$$"},
            {"name": "Bella Italia", "rating": 4.2, "price": "$$$"},
            {"name": "Spice Garden", "rating": 4.7, "price": "$$"},
        ],
    }


# Read required configuration
endpoint = os.environ.get("AZURE_OPENAI_ENDPOINT")
deployment_name = os.environ.get("AZURE_OPENAI_DEPLOYMENT_NAME")

if not endpoint:
    raise ValueError("AZURE_OPENAI_ENDPOINT environment variable is required")
if not deployment_name:
    raise ValueError("AZURE_OPENAI_DEPLOYMENT_NAME environment variable is required")

chat_client = AzureOpenAIChatClient(
    credential=AzureCliCredential(),
    endpoint=endpoint,
    deployment_name=deployment_name,    
)

# Create agent with tools
agent = Agent(
    name="TravelAssistant",
    instructions="You are a helpful travel assistant. Use the available tools to help users plan their trips.",
    chat_client=chat_client,
    tools=[get_weather, search_restaurants],
)

# Create FastAPI app
app = FastAPI(title="AG-UI Travel Assistant")
add_agent_framework_fastapi_endpoint(app, agent, "/")

if __name__ == "__main__":
    import uvicorn

    uvicorn.run(app, host="127.0.0.1", port=8888)

Compreender Eventos da Ferramenta

Quando o agente chama uma ferramenta, o cliente recebe vários eventos:

Eventos de ativação de ferramenta

# 1. TOOL_CALL_START - Tool execution begins
{
    "type": "TOOL_CALL_START",
    "toolCallId": "call_abc123",
    "toolCallName": "get_weather"
}

# 2. TOOL_CALL_ARGS - Tool arguments (may stream in chunks)
{
    "type": "TOOL_CALL_ARGS",
    "toolCallId": "call_abc123",
    "delta": "{\"location\": \"Paris, France\"}"
}

# 3. TOOL_CALL_END - Arguments complete
{
    "type": "TOOL_CALL_END",
    "toolCallId": "call_abc123"
}

# 4. TOOL_CALL_RESULT - Tool execution result
{
    "type": "TOOL_CALL_RESULT",
    "toolCallId": "call_abc123",
    "content": "The weather in Paris, France is sunny with a temperature of 22°C."
}

Cliente aprimorado para eventos de ferramenta

Aqui está um cliente aprimorado usando AGUIChatClient que exibe a execução da ferramenta:

"""AG-UI client with tool event handling."""

import asyncio
import os

from agent_framework import Agent, ToolCallContent, ToolResultContent
from agent_framework_ag_ui import AGUIChatClient


async def main():
    """Main client loop with tool event display."""
    server_url = os.environ.get("AGUI_SERVER_URL", "http://127.0.0.1:8888/")
    print(f"Connecting to AG-UI server at: {server_url}\n")

    # Create AG-UI chat client
    chat_client = AGUIChatClient(server_url=server_url)

    # Create agent with the chat client
    agent = Agent(
        name="ClientAgent",
        chat_client=chat_client,
        instructions="You are a helpful assistant.",
    )

    # Get a thread for conversation continuity
    thread = agent.create_session()

    try:
        while True:
            message = input("\nUser (:q or quit to exit): ")
            if not message.strip():
                continue

            if message.lower() in (":q", "quit"):
                break

            print("\nAssistant: ", end="", flush=True)
            async for update in agent.run(message, session=thread, stream=True):
                # Display text content
                if update.text:
                    print(f"\033[96m{update.text}\033[0m", end="", flush=True)

                # Display tool calls and results
                for content in update.contents:
                    if isinstance(content, ToolCallContent):
                        print(f"\n\033[95m[Calling tool: {content.name}]\033[0m")
                    elif isinstance(content, ToolResultContent):
                        result_text = content.result if isinstance(content.result, str) else str(content.result)
                        print(f"\033[94m[Tool result: {result_text}]\033[0m")

            print("\n")

    except KeyboardInterrupt:
        print("\n\nExiting...")
    except Exception as e:
        print(f"\n\033[91mError: {e}\033[0m")


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

Interação de exemplo

Com o servidor e o cliente aprimorados em execução:

User (:q or quit to exit): What's the weather like in Paris and suggest some Italian restaurants?

[Run Started]
[Tool Call: get_weather]
[Tool Result: The weather in Paris, France is sunny with a temperature of 22°C.]
[Tool Call: search_restaurants]
[Tool Result: {"location": "Paris", "cuisine": "Italian", "results": [...]}]
Based on the current weather in Paris (sunny, 22°C) and your interest in Italian cuisine,
I'd recommend visiting Bella Italia, which has a 4.2 rating. The weather is perfect for
outdoor dining!
[Run Finished]

Práticas recomendadas de implementação de ferramentas

Tratamento de erros

Manipule erros de forma elegante em suas ferramentas.

@tool
def get_weather(
    location: Annotated[str, Field(description="The city.")],
) -> str:
    """Get the current weather for a location."""
    try:
        # Call weather API
        result = call_weather_api(location)
        return f"The weather in {location} is {result['condition']} with temperature {result['temp']}°C."
    except Exception as e:
        return f"Unable to retrieve weather for {location}. Error: {str(e)}"

Tipos de retorno avançados

Retornar dados estruturados quando apropriado:

@tool
def analyze_sentiment(
    text: Annotated[str, Field(description="The text to analyze")],
) -> dict[str, Any]:
    """Analyze the sentiment of text."""
    # Perform sentiment analysis
    return {
        "text": text,
        "sentiment": "positive",
        "confidence": 0.87,
        "scores": {
            "positive": 0.87,
            "neutral": 0.10,
            "negative": 0.03,
        },
    }

Documentação descritiva

Forneça descrições claras para ajudar o agente a entender quando usar ferramentas:

@tool
def book_flight(
    origin: Annotated[str, Field(description="Departure city and airport code, e.g., 'New York, JFK'")],
    destination: Annotated[str, Field(description="Arrival city and airport code, e.g., 'London, LHR'")],
    date: Annotated[str, Field(description="Departure date in YYYY-MM-DD format")],
    passengers: Annotated[int, Field(description="Number of passengers")] = 1,
) -> dict[str, Any]:
    """
    Book a flight for specified passengers from origin to destination.

    This tool should be used when the user wants to book or reserve airline tickets.
    Do not use this for searching flights - use search_flights instead.
    """
    # Implementation
    pass

Organização de ferramentas com classes

Para ferramentas relacionadas, organize-as em uma classe:

from agent_framework import tool


class WeatherTools:
    """Collection of weather-related tools."""

    def __init__(self, api_key: str):
        self.api_key = api_key

    @tool
    def get_current_weather(
        self,
        location: Annotated[str, Field(description="The city.")],
    ) -> str:
        """Get current weather for a location."""
        # Use self.api_key to call API
        return f"Current weather in {location}: Sunny, 22°C"

    @tool
    def get_forecast(
        self,
        location: Annotated[str, Field(description="The city.")],
        days: Annotated[int, Field(description="Number of days")] = 3,
    ) -> dict[str, Any]:
        """Get weather forecast for a location."""
        # Use self.api_key to call API
        return {"location": location, "forecast": [...]}


# Create tools instance
weather_tools = WeatherTools(api_key="your-api-key")

# Create agent with class-based tools
agent = Agent(
    name="WeatherAgent",
    instructions="You are a weather assistant.",
    chat_client=AzureOpenAIChatClient(...),
    tools=[
        weather_tools.get_current_weather,
        weather_tools.get_forecast,
    ],
)

Próximas etapas

Agora que você entende a renderização da ferramenta de back-end, você pode:

Criar ferramentas avançadas: saiba mais sobre como criar ferramentas de função com o Agent Framework

Recursos adicionais

Comentários

Esta página foi útil?

Last updated on 2025-11-11

Compartilhar via

Renderização de ferramenta de back-end com AG-UI

Pré-requisitos

O que é renderização de ferramenta de back-end?

Criando um servidor AG-UI com ferramentas de função

Conceitos Principais

Executando o servidor

Observando chamadas de ferramenta no cliente

Exibindo detalhes de execução da ferramenta

Saída esperada com chamadas de ferramenta

Conceitos Principais

Próximas etapas

Recursos adicionais

Pré-requisitos

O que é renderização de ferramenta de back-end?

Criando ferramentas de funções

Ferramenta de Função Básica

Conceitos Principais

Ferramentas Multifuncionais

Criando um servidor AG-UI com ferramentas de função

Compreender Eventos da Ferramenta

Eventos de ativação de ferramenta

Cliente aprimorado para eventos de ferramenta

Interação de exemplo

Práticas recomendadas de implementação de ferramentas

Tratamento de erros

Tipos de retorno avançados

Documentação descritiva

Organização de ferramentas com classes

Próximas etapas

Recursos adicionais

Comentários

Recursos adicionais