Representación de herramientas de back-end con AG-UI

En este tutorial se muestra cómo agregar herramientas de función a los agentes de AG-UI. Las herramientas de funciones son métodos personalizados de C# a los que el agente puede llamar para realizar tareas específicas, como recuperar datos, realizar cálculos o interactuar con sistemas externos. Con AG-UI, estas herramientas se ejecutan en el back-end y sus resultados se transmiten automáticamente al cliente.

Prerrequisitos

Antes de comenzar, asegúrese de que ha completado el tutorial de introducción y que tiene:

.NET 8.0 o posterior
Microsoft.Agents.AI.Hosting.AGUI.AspNetCore paquete instalado
Servicio OpenAI de Azure configurado
Conocimientos básicos de la configuración de cliente y servidor de AG-UI

¿Qué es el renderizado de herramientas de backend?

La representación de herramientas de backend se refiere a:

Las herramientas de función se definen en el servidor
El agente de IA decide cuándo llamar a estas herramientas
Las herramientas se ejecutan en el back-end (servidor)
Los eventos y los resultados de la llamada a la herramienta se transmiten al cliente en tiempo real
El cliente recibe actualizaciones sobre el progreso de la ejecución de la herramienta.

Creación de un servidor de AG-UI con herramientas de funciones

Esta es una implementación completa del servidor que muestra cómo registrar herramientas con tipos de parámetros complejos:

// 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();

Conceptos clave

Ejecución del lado del servidor: Las herramientas se ejecutan en el proceso del servidor
Streaming automático: las llamadas de herramientas y los resultados se transmiten a los clientes en tiempo real.

Importante

Al crear herramientas con tipos de parámetros complejos (objetos, matrices, etc.), debe proporcionar el serializerOptions parámetro a AIFunctionFactory.Create(). Las opciones del serializador se deben obtener de la aplicación configurada JsonOptions a través de IOptions<Microsoft.AspNetCore.Http.Json.JsonOptions> para garantizar la coherencia con el resto de la serialización JSON de la aplicación.

Ejecución del servidor

Establezca las variables de entorno y ejecute:

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

Observar llamadas de herramientas en el cliente

El cliente básico del tutorial "Guía de inicio" muestra la respuesta final del texto del agente. Sin embargo, puede ampliarlo para observar las llamadas a herramientas y los resultados a medida que se transmiten desde el servidor.

Mostrar detalles de ejecución de herramientas

Para ver las llamadas a herramientas y los resultados en tiempo real, amplíe el bucle de streaming del cliente para controlar FunctionCallContent y 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;
        }
    }
}

Resultado esperado con llamadas a herramientas

Cuando el agente llame a las herramientas de back-end, verá lo siguiente:

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]

Conceptos clave

FunctionCallContent: representa una herramienta a la que se llama con su Name y Arguments (pares clave-valor de parámetro)
FunctionResultContent: Contiene la Result o Exception de la herramienta, identificada por CallId

Pasos siguientes

Ahora que puede agregar herramientas de función, puede hacer lo siguiente:

Herramientas de front-end: agregar herramientas de front-end.

Prueba con Dojo: usar la aplicación Dojo de AG-UI para probar los agentes

Recursos adicionales

En este tutorial se muestra cómo agregar herramientas de función a los agentes de AG-UI. Las herramientas de funciones son funciones personalizadas de Python a las que el agente puede llamar para realizar tareas específicas, como recuperar datos, realizar cálculos o interactuar con sistemas externos. Con AG-UI, estas herramientas se ejecutan en el back-end y sus resultados se transmiten automáticamente al cliente.

Prerrequisitos

Antes de comenzar, asegúrese de que ha completado el tutorial de introducción y que tiene:

Python 3.10 o posterior
agent-framework-ag-ui Instalado
Servicio OpenAI de Azure configurado
Conocimientos básicos de la configuración de cliente y servidor de AG-UI

Nota:

Estos ejemplos usan DefaultAzureCredential para la autenticación. Asegúrese de que está autenticado con Azure (por ejemplo, a través de az login). Para más información, consulte la documentación de Azure Identity.

¿Qué es el renderizado de herramientas de backend?

La representación de herramientas de backend se refiere a:

Las herramientas de función se definen en el servidor
El agente de IA decide cuándo llamar a estas herramientas
Las herramientas se ejecutan en el back-end (servidor)
Los eventos y los resultados de la llamada a la herramienta se transmiten al cliente en tiempo real
El cliente recibe actualizaciones sobre el progreso de la ejecución de la herramienta.

Este enfoque proporciona:

Seguridad: las operaciones confidenciales permanecen en el servidor
Coherencia: todos los clientes usan las mismas implementaciones de herramientas
Transparencia: los clientes pueden mostrar el progreso de la ejecución de la herramienta
Flexibilidad: actualización de herramientas sin cambiar el código de cliente

Creación de herramientas de funciones

Herramienta de función básica

Puede convertir cualquier función de Python en una herramienta mediante el @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."

Conceptos clave

@tool decorador: marca una función como disponible para el agente
Anotaciones de tipo: proporcionar información de tipo para los parámetros.
Annotated y Field: se agregan descripciones para ayudar al agente a comprender los parámetros.
Docstring: describe lo que hace la función (ayuda al agente a decidir cuándo usarlo)
Valor devuelto: el resultado devuelto al agente (y transmitido al cliente)

Herramientas multifuncionales

Puede proporcionar varias herramientas para proporcionar al agente más 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},
        ],
    }

Creación de un servidor de AG-UI con herramientas de funciones

Esta es una implementación completa del servidor con herramientas de función:

"""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)

Comprensión de eventos de herramientas

Cuando el agente llama a una herramienta, el cliente recibe varios eventos:

Eventos de llamada de herramienta

# 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 mejorado para eventos de herramientas

Este es un cliente mejorado que utiliza AGUIChatClient para mostrar la ejecución de la herramienta.

"""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.get_new_thread()

    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_stream(message, thread=thread):
                # 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())

Interacción de ejemplo

Con el servidor mejorado y el cliente en ejecución:

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]

Procedimientos recomendados de implementación de herramientas

Tratamiento de errores

Maneje los errores de manera eficiente en las herramientas:

@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 enriquecidos

Devolver datos estructurados cuando corresponda:

@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,
        },
    }

Documentación descriptiva

Proporcione descripciones claras para ayudar al agente a comprender cuándo usar herramientas:

@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

Organización de herramientas con clases

En el caso de las herramientas relacionadas, organícelas en una clase:

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,
    ],
)

Pasos siguientes

Ahora que comprende la representación de herramientas de back-end, puede hacer lo siguiente:

Creación de herramientas avanzadas: Más información sobre la creación de herramientas de funciones con Agent Framework

Recursos adicionales

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2025-11-11

Compartir a través de

Representación de herramientas de back-end con AG-UI

Prerrequisitos

¿Qué es el renderizado de herramientas de backend?

Creación de un servidor de AG-UI con herramientas de funciones

Conceptos clave

Ejecución del servidor

Observar llamadas de herramientas en el cliente

Mostrar detalles de ejecución de herramientas

Resultado esperado con llamadas a herramientas

Conceptos clave

Pasos siguientes

Recursos adicionales

Prerrequisitos

¿Qué es el renderizado de herramientas de backend?

Creación de herramientas de funciones

Herramienta de función básica

Conceptos clave

Herramientas multifuncionales

Creación de un servidor de AG-UI con herramientas de funciones

Comprensión de eventos de herramientas

Eventos de llamada de herramienta

Cliente mejorado para eventos de herramientas

Interacción de ejemplo

Procedimientos recomendados de implementación de herramientas

Tratamiento de errores

Tipos de retorno enriquecidos

Documentación descriptiva

Organización de herramientas con clases

Pasos siguientes

Recursos adicionales

Comentarios

Recursos adicionales