Backend-Tool-Rendering mit AG-UI

Back-End-Tools verwenden die normale MAF-Toolpipeline. AG-UI fügt Transportereignisse hinzu, damit ein Client den Aufruf und das Ergebnis beobachten kann; es führt keine separate Toolstraktion ein.

Hinzufügen eines Back-End-Tools

Definieren und registrieren Sie das Tool wie für jeden MAF-Agent:

using System.ComponentModel;
using Microsoft.Extensions.AI;

[Description("Get the weather for a location.")]
static string GetWeather(
    [Description("The city to look up.")] string location) =>
    $"The weather in {location} is sunny.";

AITool getWeather = AIFunctionFactory.Create(GetWeather, name: "get_weather");
AIAgent agent = chatClient.AsAIAgent(tools: [getWeather]);

app.MapAGUIServer("/", agent);

Konfigurieren Sie für komplexe Anforderungs- oder Antworttypen dasselbe JsonSerializerOptions für ASP.NET Core und AIFunctionFactory.Create.

Informationen zu Toolschemas, Abhängigkeitseinfügung, Fehlerbehandlung und allgemeinem Toolentwurf finden Sie unter Verwenden von Funktionstools mit einem Agent.

AG-UI Ereigniszuordnung

Wenn der Agent das Tool aufruft:

• FunctionCallContent wird als AG-UI-TOOL_CALL_START-, TOOL_CALL_ARGS- und TOOL_CALL_END-Ereignisse ausgegeben.
• FunctionResultContent wird als TOOL_CALL_RESULT Ereignis ausgegeben.
• Text und andere Inhalte des Agenten werden weiterhin wie gewohnt übertragen.

Ein .NET Client erhält den übersetzten Inhalt als FunctionCallContent undFunctionResultContent:

await foreach (AgentResponseUpdate update in agent.RunStreamingAsync(messages, session))
{
    foreach (AIContent content in update.Contents)
    {
        if (content is FunctionCallContent call)
        {
            Console.WriteLine($"Calling {call.Name}");
        }
        else if (content is FunctionResultContent result)
        {
            Console.WriteLine($"Result: {result.Result}");
        }
    }
}

Toolergebnisse sind für das Modell bestimmte Werte, die AG-UI auch dem Client zur Verfügung stellt. Verwenden Sie die expliziten Zuordnungen, die unter Zustandsverwaltung beschrieben sind, um zusätzlich zu einem Toolergebnis gemeinsam genutzten UI-Zustand auszugeben.

Nächste Schritte

In diesem Lernprogramm erfahren Sie, wie Sie Ihren AG-UI Agents Funktionstools hinzufügen. Funktionstools sind benutzerdefinierte Python-Funktionen, die der Agent aufrufen kann, um bestimmte Aufgaben wie das Abrufen von Daten, das Ausführen von Berechnungen oder die Interaktion mit externen Systemen auszuführen. Mit AG-UI werden diese Tools im Back-End ausgeführt, und ihre Ergebnisse werden automatisch an den Client gestreamt.

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass Sie das Lernprogramm " Erste Schritte " abgeschlossen haben und folgendes haben:

• Python 3.10 oder höher
• agent-framework-ag-ui installiert
• Azure OpenAI-Dienst konfiguriert
• Grundlegendes Verständnis von AG-UI Server- und Clientsetup

Was ist Backend-Tool-Rendering?

Das Rendering des Backend-Tools bedeutet:

• Funktionstools werden auf dem Server definiert.
• Der KI-Agent entscheidet, wann diese Tools aufgerufen werden sollen.
• Tools werden im Back-End ausgeführt (serverseitig)
• Toolaufrufereignisse und Ergebnisse werden in Echtzeit an den Client gestreamt.
• Der Client empfängt Updates zum Fortschritt der Toolausführung.

Dieser Ansatz bietet Folgendes:

• Sicherheit: Vertrauliche Vorgänge bleiben auf dem Server
• Konsistenz: Alle Clients verwenden dieselben Toolimplementierungen
• Transparenz: Clients können den Fortschritt der Toolausführung anzeigen
• Flexibilität: Aktualisieren von Tools ohne Ändern von Clientcode

Erstellen von Funktionstools

Grundlegendes Funktionstool

Sie können jede Python-Funktion in ein Tool umwandeln, indem Sie den @tool Dekorateur verwenden:

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

Wichtige Konzepte

• @tool Dekorateur: Kennzeichnet eine Funktion als verfügbar für den Agent
• Typanmerkungen: Bereitstellen von Typinformationen für Parameter
• Annotated und Field: Hinzufügen von Beschreibungen, die dem Agent helfen, Parameter zu verstehen
• Docstring: Beschreibt, was die Funktion tut (hilft dem Agent zu entscheiden, wann sie verwendet werden soll)
• Rückgabewert: Das an den Agent zurückgegebene Ergebnis (und wird an den Client gestreamt)

Tools für mehrere Funktionen

Sie können mehrere Tools bereitstellen, um dem Agent mehr Funktionen zu bieten:

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

Erstellen eines AG-UI Servers mit Funktionstools

Hier ist eine vollständige Serverimplementierung mit Funktionstools:

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

import os
from typing import Annotated, Any

from agent_framework import Agent, tool
from agent_framework.openai import OpenAIChatCompletionClient
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_CHAT_COMPLETION_MODEL")

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

chat_client = OpenAIChatCompletionClient(
    model=deployment_name,
    azure_endpoint=endpoint,
    api_version=os.getenv("AZURE_OPENAI_API_VERSION"),
    credential=AzureCliCredential(),
)

# 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.",
    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)

Grundlegendes zu Toolereignissen

Wenn der Agent ein Tool aufruft, empfängt der Client mehrere Ereignisse:

Ereignisse bei Toolaufrufen

# 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."
}

Erweiterter Client für Toolereignisse

Hier ist ein erweiterter Client, der mit AGUIChatClient die Ausführung von Tools anzeigt.

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

import asyncio
import os

from agent_framework import Agent
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(endpoint=server_url)

    # Create agent with the chat client
    agent = Agent(
        name="ClientAgent",
        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 content.type == "function_call":
                        print(f"\n\033[95m[Calling tool: {content.name}]\033[0m")
                    elif content.type == "function_result":
                        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())

Beispielinteraktion

Mit dem erweiterten Server und dem Client, auf dem Folgendes ausgeführt wird:

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]

Bewährte Methoden für die Toolimplementierung

Fehlerbehandlung

Behandeln Sie Fehler ordentlich in Ihren Tools:

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

Rich-Rückgabetypen

Geben Sie bei Bedarf strukturierte Daten zurück:

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

Beschreibende Dokumentation

Stellen Sie klare Beschreibungen bereit, mit denen der Agent verstehen kann, wann Tools verwendet werden:

@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

Toolorganisation mit Klassen

Ordnen Sie die zugehörigen Werkzeuge in einer Klasse an.

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.",
    client=OpenAIChatCompletionClient(...),
    tools=[
        weather_tools.get_current_weather,
        weather_tools.get_forecast,
    ],
)

Nächste Schritte

Nachdem Sie nun mit dem Rendern von Back-End-Tools vertraut sind, haben Sie folgende Möglichkeiten:

• Erstellen erweiterter Tools: Weitere Informationen zum Erstellen von Funktionstools mit Agent Framework

Zusätzliche Ressourcen

• AG-UI Übersicht
• Erste Schritte mit AG-UI
• Lernprogramm zu Funktionstools

Go-AG-UI-Server können normale Funktionstools des Agent Frameworks bereitstellen. Erstellen Sie Tools mit tool/functool, fügen Sie sie an den gehosteten Agent an, und bedienen Sie den Agent mit aguiprovider.NewJSONHTTPHandler.

searchRestaurants := functool.MustNew(functool.Config{
    Name:        "search_restaurants",
    Description: "Search for restaurants in a location.",
}, func(ctx context.Context, in restaurantSearchRequest) (restaurantSearchResponse, error) {
    return restaurantSearchResponse{
        Location: in.Location,
        Cuisine:  in.Cuisine,
        Results:  []restaurantInfo{{Name: "The Golden Fork", Cuisine: in.Cuisine}},
    }, nil
})

a := foundryprovider.NewAgent(endpoint, token, foundryprovider.ModelDeployment(model), foundryprovider.AgentConfig{
    Config: agent.Config{
        Tools: []tool.Tool{searchRestaurants},
    },
})