Sdílet prostřednictvím

Vyhodnoťte své agenty AI (Preview) (Classic)

Platí jenom pro:Portál Foundry (Classic). Tento článek není k dispozici pro nový portál Foundry. Přečtěte si další informace o novém portálu.

Poznámka:

Některé odkazy v tomto článku můžou otevřít obsah v nové dokumentaci Microsoft Foundry místo dokumentace Foundry (klasické), kterou si právě prohlížíte.

Důležité

Položky označené (Preview) v tomto článku jsou aktuálně ve verzi Public Preview. Tato verze Preview je poskytována bez smlouvy o úrovni služeb a nedoporučujeme ji pro produkční úlohy. Některé funkce se nemusí podporovat nebo mohou mít omezené možnosti. Další informace najdete v tématu Supplementální podmínky použití pro Microsoft Azure Preview.

Agenti umělé inteligence jsou výkonnými pomocníky pro produktivitu, kteří vytvářejí pracovní postupy pro obchodní potřeby. Pozorovatelnost je ale náročná kvůli složitým vzorcům interakce. V tomto článku se dozvíte, jak vyhodnotit agenty Microsoft Foundry nebo jiné agenty pomocí integrovaných vyhodnocovačů.

Aby vývojáři mohli vytvářet agentské aplikace připravené pro produkční prostředí a zajistit pozorovatelnost a transparentnost, potřebují nástroje k vyhodnocení nejen konečného výstupu pracovních postupů agenta, ale také kvality a efektivity pracovních postupů.

Událost, jako když se uživatel dotazuje na "počasí zítra," spouští pracovní postup agenta. K vytvoření konečné odpovědi pracovní postup zahrnuje analýzu záměrů uživatelů, volání nástrojů a použití generování s podporou vyhledávání.

Poznámka:

Sada Microsoft Foundry SDK pro vyhodnocení a portál Foundry je ve verzi Public Preview, ale rozhraní API jsou obecně dostupná pro vyhodnocení modelu a datové sady (vyhodnocení agenta zůstává ve verzi Public Preview). Sada SDK Azure pro vyhodnocení AI a vyhodnocovače označené jako (Preview) v tomto článku jsou aktuálně ve verzi Public Preview všude.

V tomto procesu je důležité vyhodnotit každý krok pracovního postupu a kvalitu a bezpečnost konečného výstupu. Tyto hodnotící aspekty jsou formulovány do následujících vyhodnocovačů pro agenty:

  • Řešení záměru: Měří, jestli agent správně identifikuje záměr uživatele.
  • Přesnost volání nástroje: Měří, jestli agent provedl správné volání nástroje funkce na žádost uživatele.
  • Dodržování úkolů: Měří, jestli konečná odpověď agenta dodržuje přiřazené úkoly podle systémové zprávy a předchozích kroků.

Vyhodnoťte další aspekty kvality a bezpečnosti vašich pracovních postupů agentů pomocí komplexní sady integrovaných vyhodnocovačů. Obecně agenti emitují zprávy agentů. Transformace zpráv agenta na správná vyhodnocovací data pro vyhodnocovače může být náročná. Pokud vytváříte agenta pomocí služby Foundry Agent Service, můžete ho bez problémů vyhodnotit prostřednictvím naší podpory převaděče. Pokud vytváříte agenta mimo službu Foundry Agent Service, můžete vyhodnocovače použít podle potřeby pro pracovní postup agenta parsováním zpráv agenta do požadovaných formátů dat. Podívejte se na příklady vyhodnocení jiných agentů.

Začínáme

Nainstalujte balíček vyhodnocovačů ze sady SDK pro vyhodnocení Azure AI:

pip install azure-ai-evaluation

Vyhodnocení agentů Microsoft Foundry

Pokud používáte službu Foundry Agent Service, můžete agenty bez problémů vyhodnotit pomocí podpory převaděče pro agenty Microsoft Foundry a agenty sémantického jádra. Následující vyhodnocovače podporují vyhodnocovací data vrácená převaděčem: IntentResolution, ToolCallAccuracy, TaskAdherence, Relevancea Groundedness.

Poznámka:

Pokud vytváříte další agenty s jiným schématem, převeďte je na obecné schéma zpráv agenta ve stylu OpenAI a použijte předchozí vyhodnocovače. Obecněji platí, že pokud můžete analyzovat zprávy agenta do požadovaných datových formátů, můžete použít také všechny naše vyhodnocovače.

Podpora modelů pro vyhodnocovače s asistencí umělé inteligence

Modely odůvodnění AzureOpenAI a OpenAI a modely bez odůvodnění podporují posouzení LLM v závislosti na vyhodnocovacích modelech:

Hodnotitelé Modely odůvodnění jako soudce (příklad: modely řad o-series z Azure OpenAI / OpenAI) Modely bez schopnosti logického usuzování jako soudce (příklad: gpt-4.1, gpt-4o atd.) Povolení
IntentResolution, TaskAdherence, ToolCallAccuracy, ResponseCompleteness, Coherence, Fluency, Similarity, Groundedness, Retrieval, Relevance Podporováno Podporováno Nastavení dalšího parametru is_reasoning_model=True při inicializaci vyhodnocovačů
Další vyhodnocovače Nepodporováno Podporováno --

Pro komplexní vyhodnocení, které vyžaduje propracované odůvodnění, použijte silný model pro odůvodňování, jako je 4.1-mini pro vyvážení výkonu odůvodňování a efektivity nákladů.

Podpora vyhodnocení volání nástroje

ToolCallAccuracyEvaluator podporuje hodnocení v aplikaci Microsoft Foundry Agent pro následující nástroje:

  • Hledání souborů
  • Azure AI Vyhledávač
  • Bing základ
  • Vlastní vyhledávání Bingu
  • Uzemnění SharePointu
  • Interpretátor kódu
  • Datový agent Fabric
  • OpenAPI
  • Function Tool (uživatelsky definované nástroje)

Pokud ale ve spuštění agenta použijete nepodporovaný nástroj, vyhodnocovací nástroj vypíše "pass" a důvod, proč vyhodnocení vyvolaných nástrojů není podporované, aby se tyto případy snadno odfiltrovaly. Pokud chcete povolit vyhodnocení, zabalte nepodporované nástroje jako uživatelem definované nástroje.

Tento příklad ukazuje, jak sestavit a vyhodnotit agenta Microsoft Foundry. Služba Foundry Agent Service, odděleně od vyhodnocení, vyžaduje pip install azure-ai-projects azure-identity, připojovací řetězec projektu Foundry a podporované modely.

Vytvoření vláken agenta a spuštění

Agenti můžou používat nástroje. Tady je příklad vytvoření vlastních nástrojů, které má agent použít (například pomocí simulované funkce počasí):

from azure.ai.projects.models import FunctionTool, ToolSet
from typing import Set, Callable, Any
import json

# Define a custom Python function.
def fetch_weather(location: str) -> str:
    """
    Fetches the weather information for the specified location.

    :param location (str): The location to fetch weather for.
    :return: Weather information as a JSON string.
    :rtype: str
    """
    # In a real-world scenario, you'd integrate with a weather API.
    # In the following code snippet, we mock the response.
    mock_weather_data = {"Seattle": "Sunny, 25°C", "London": "Cloudy, 18°C", "Tokyo": "Rainy, 22°C"}
    weather = mock_weather_data.get(location, "Weather data not available for this location.")
    weather_json = json.dumps({"weather": weather})
    return weather_json

user_functions: Set[Callable[..., Any]] = {
    fetch_weather,
}

# Add tools that the agent will use. 
functions = FunctionTool(user_functions)

toolset = ToolSet()
toolset.add(functions)

AGENT_NAME = "Seattle Tourist Assistant"

Pokud používáte Foundry (non-Hub) project, vytvořte agenta se sadou nástrojů následujícím způsobem:

Poznámka:

Pokud používáte projekt založený na Foundry Hub (který podporuje pouze nižší verze azure-ai-projects<1.0.0b10 a azure-ai-agents<1.0.0b10), migrujte na nejnovější klientskou knihovnu Python pro SDK služby Foundry Agent Service. Další informace najdete v tématu nastavení projektu Foundry pro zapisování výsledků dávkové evaluace.

Pomocí sady nástrojů vytvořte agenta následujícím způsobem:

import os
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
from dotenv import load_dotenv

load_dotenv()

# Create an Azure AI Client from an endpoint, copied from your Foundry project.
# You need to login to Azure subscription via Azure CLI and set the environment variables
# Foundry project endpoint, example: AZURE_AI_PROJECT=https://your-account.services.ai.azure.com/api/projects/your-project
project_endpoint = os.environ["AZURE_AI_PROJECT"]  # Ensure the PROJECT_ENDPOINT environment variable is set

# Create an AIProjectClient instance
project_client = AIProjectClient(
    endpoint=project_endpoint,
    credential=DefaultAzureCredential(),  # Use Azure Default Credential for authentication
)

# Create an agent with the toolset 
agent = project_client.agents.create_agent(
    model=os.environ["MODEL_DEPLOYMENT_NAME"],  # Model deployment name
    name="my-agent",  # Name of the agent
    instructions="You are a helpful agent",  # Instructions for the agent
    toolset=toolset
)
print(f"Created agent, ID: {agent.id}")

# Create a thread for communication
thread = project_client.agents.threads.create()
print(f"Created thread, ID: {thread.id}")

# Add a message to the thread
message = project_client.agents.messages.create(
    thread_id=thread.id,
    role="user",  # Role of the message sender
    content="What is the weather in Seattle today?",  # Message content
)
print(f"Created message, ID: {message['id']}")

# Create and process an agent run
run = project_client.agents.runs.create_and_process(thread_id=thread.id, agent_id=agent.id)
print(f"Run finished with status: {run.status}")

# Check if the run failed
if run.status == "failed":
    print(f"Run failed: {run.last_error}")

# Fetch and log all messages
messages = project_client.agents.messages.list(thread_id=thread.id)
for message in messages:
    print(f"Role: {message.role}, Content: {message.content}")

Vyhodnocení jednoho spuštění agenta

Po spuštění agenta pomocí převaděče transformujte data vlákna agenta Microsoft Foundry na požadovaná vyhodnocovací data, která vyhodnocovače můžou pochopit.

import json, os
from azure.ai.evaluation import AIAgentConverter, IntentResolutionEvaluator

# Initialize the converter for Microsoft Foundry agents.
converter = AIAgentConverter(project_client)

# Specify the thread and run ID.
thread_id = thread.id
run_id = run.id

converted_data = converter.convert(thread_id, run_id)

A je to! converted_data obsahuje všechny vstupy vyžadované pro tyto vyhodnocovače. Při analýze vstupů nemusíte číst vstupní požadavky pro každý vyhodnocovač nebo provádět žádnou práci. Vyberte svého hodnotitele a zavolejte ho při tomto jednom spuštění. V závislosti na posuzovatelích podporujeme modely Azure OpenAI nebo OpenAI modely uvažování a modely bez uvažování pro soudce.

Hodnotitelé Modely odůvodnění jako soudce (příklad: modely řad o-series z Azure OpenAI / OpenAI) Modely bez schopnosti logického usuzování jako soudce (příklad: gpt-4.1, gpt-4o atd.) Povolení
Všichni hodnotitelé kvality s výjimkou GroundednessProEvaluator Podporováno Podporováno Nastavení dalšího parametru is_reasoning_model=True při inicializaci vyhodnocovačů
GroundednessProEvaluator Uživatel nemusí podporovat model. Uživatel nemusí podporovat model. --

U složitých úloh, které vyžadují zdokonalené odůvodnění pro vyhodnocení, použijte silný model odůvodnění, jako je o3-mini nebo minimodely řady o-series, které byly následně vydány pro rovnováhu mezi výkonem odůvodnění a nákladovou efektivitou.

Nastavili jste seznam hodnotitelů kvality a bezpečnosti v quality_evaluators a safety_evaluators. Na ně odkazujete při vyhodnocování spuštění více agentů nebo vlákna.

# This is specific to agentic workflows.
from azure.ai.evaluation import IntentResolutionEvaluator, TaskAdherenceEvaluator, ToolCallAccuracyEvaluator 
# Other quality, risk, and safety metrics:
from azure.ai.evaluation import RelevanceEvaluator, CoherenceEvaluator, CodeVulnerabilityEvaluator, ContentSafetyEvaluator, IndirectAttackEvaluator, FluencyEvaluator
from azure.identity import DefaultAzureCredential

import os
from dotenv import load_dotenv
load_dotenv()

model_config = {
    "azure_deployment": os.getenv("AZURE_DEPLOYMENT_NAME"),
    "api_key": os.getenv("AZURE_API_KEY"),
    "azure_endpoint": os.getenv("AZURE_ENDPOINT"),
    "api_version": os.getenv("AZURE_API_VERSION"),
}

# example config for a reasoning model
reasoning_model_config = {
    "azure_deployment": "o3-mini",
    "api_key": os.getenv("AZURE_API_KEY"),
    "azure_endpoint": os.getenv("AZURE_ENDPOINT"),
    "api_version": os.getenv("AZURE_API_VERSION"),
}

# Evaluators you might want to use with reasoning models 
quality_evaluators = {evaluator.__name__: evaluator(model_config=reasoning_model_config, is_reasoning_model=True) for evaluator in [IntentResolutionEvaluator, TaskAdherenceEvaluator, ToolCallAccuracyEvaluator]}

# Other evaluators you might NOT want to use with reasoning models 
quality_evaluators.update({ evaluator.__name__: evaluator(model_config=model_config) for evaluator in [CoherenceEvaluator, FluencyEvaluator, RelevanceEvaluator]})

## Using Foundry (non-Hub) project endpoint, example: AZURE_AI_PROJECT=https://your-account.services.ai.azure.com/api/projects/your-project
azure_ai_project = os.environ.get("AZURE_AI_PROJECT")

safety_evaluators = {evaluator.__name__: evaluator(azure_ai_project=azure_ai_project, credential=DefaultAzureCredential()) for evaluator in [ContentSafetyEvaluator, IndirectAttackEvaluator, CodeVulnerabilityEvaluator]}

# Reference the quality and safety evaluator list above.
quality_and_safety_evaluators = {**quality_evaluators, **safety_evaluators}

for name, evaluator in quality_and_safety_evaluators.items():
    result = evaluator(**converted_data)
    print(name)
    print(json.dumps(result, indent=4))

Výstupní formát

Vyhodnocovače kvality s asistencí umělé inteligence vrátí výsledek páru dotazů a odpovědí. Výsledkem je slovník, který obsahuje:

  • {metric_name}: Poskytuje číselné skóre na stupnici Likert (celé číslo 1 až 5) nebo plovák mezi 0 a 1.
  • {metric_name}_label: Poskytuje binární popisek, pokud metrika přirozeně vypíše binární skóre.
  • {metric_name}_reason: Vysvětluje, proč bylo pro každý datový bod zadané určité skóre nebo popisek.
  • details: Volitelný výstup obsahující ladicí informace o kvalitě jednoho běhu agenta.

Pro zlepšení jasnosti všechny vyhodnocovače přijímají binární prahovou hodnotu (pokud jejich výstupy nejsou již binární) a vygenerují dva nové klíče. Pro prahovou hodnotu binarizace je nastavena výchozí hodnota, kterou může uživatel přepsat. Dva nové klíče jsou:

  • {metric_name}_result: Řetězec "pass" nebo "fail" na základě prahové hodnoty binarizace.
  • {metric_name}_threshold: Prahová hodnota číselného binarizace nastavená ve výchozím nastavení nebo uživatelem.

Některé vyhodnocovače najdete v následujícím příkladu výstupu:

{
    "intent_resolution": 5.0, # likert scale: 1-5 integer 
    "intent_resolution_threshold": 3,
    "intent_resolution_result": "pass", # pass because 5 > 3 the threshold
    "intent_resolution_reason": "The assistant correctly understood the user's request to fetch the weather in Seattle. It used the appropriate tool to get the weather information and provided a clear and accurate response with the current weather conditions in Seattle. The response fully resolves the user's query with all necessary information."
}
{
    "task_adherence": 5.0, # likert scale: 1-5 integer 
    "task_adherence_threshold": 3,
    "task_adherence_result": "pass", # pass because 5 > 3 the threshold
    "task_adherence_reason": "The response accurately follows the instructions, fetches the correct weather information, and relays it back to the user without any errors or omissions."
}
{
    "tool_call_accuracy": 5,  # a score between 1-5, higher is better
    "tool_call_accuracy_threshold": 3,
    "tool_call_accuracy_result": "pass", # pass because 5 > 3 the threshold
    "details": { ... } # helpful details for debugging the tool calls made by the agent
}

Vyhodnocení více běhů agentů nebo vláken

Pokud chcete vyhodnotit více spuštění nebo vláken agenta, použijte dávkové evaluate() rozhraní API pro asynchronní vyhodnocení. Nejprve pomocí podpory převaděče převeďte data vlákna agenta na soubor:

import json
from azure.ai.evaluation import AIAgentConverter

# Initialize the converter.
converter = AIAgentConverter(project_client)

# Specify a file path to save the agent output (evaluation input data) to.
filename = os.path.join(os.getcwd(), "evaluation_input_data.jsonl")

evaluation_data = converter.prepare_evaluation_data(thread_ids=thread_id, filename=filename) 

print(f"Evaluation data saved to {filename}")

Přípravou dat pro vyhodnocení jedním řádkem kódu můžete zvolit hodnotitele k posouzení kvality agenta a následně spustit dávkovou evaluaci. V následujícím příkladu použijte stejný seznam vyhodnocovačů kvality a bezpečnosti v části Vyhodnocení jednoho spuštěníquality_and_safety_evaluators agenta:

import os
from dotenv import load_dotenv
load_dotenv()

# Batch evaluation API (local):
from azure.ai.evaluation import evaluate

response = evaluate(
    data=filename,
    evaluation_name="agent demo - batch run",
    evaluators=quality_and_safety_evaluators,
    # optionally, log your results to your Foundry project for rich visualization 
    azure_ai_project=os.environ.get("AZURE_AI_PROJECT"),  # example: https://your-account.services.ai.azure.com/api/projects/your-project
)
# Inspect the average scores at a high level.
print(response["metrics"])
# Use the URL to inspect the results on the UI.
print(f'Foundry URL: {response.get("studio_url")}')

Po výběru adresy URL budete přesměrováni na Foundry. Prohlédněte si výsledky vyhodnocení ve vašem projektu Foundry a nalaďte aplikaci. Použijte důvodová pole a výsledky úspěšnosti/neúspěšnosti k vyhodnocení kvality a bezpečnosti vašich aplikací. Můžete spouštět a porovnávat více spuštění a testovat regresi nebo vylepšení.

Pomocí klientské knihovny sady Azure AI Evaluation SDK můžete vyhodnotit agenty Microsoft Foundry s podporou převaděče, což umožňuje pozorovatelnost a transparentnost pracovních postupů agentů.

Vyhodnocení dalších agentů

Pokud používáte agenty mimo službu agenta, můžete je přesto vyhodnotit tak, že připravíte správná data pro vyhodnocovače podle vašeho výběru.

Agenti obvykle odesílají zprávy pro interakci s uživatelem nebo jinými agenty. Předdefinované vyhodnocovače přijímají jednoduché datové typy, jako jsou řetězce v query, responsea ground_truth v závislosti na požadavcích na vstup dat s jedním otočením. Extrakce těchto jednoduchých datových typů ze zpráv agenta ale může být náročná kvůli složitým vzorcům interakce agentů a rozdílů v rozhraní. Například jeden uživatelský dotaz může aktivovat dlouhý seznam zpráv agenta, obvykle s vyvolánými několika voláními nástroje.

Jak je znázorněno v následujícím příkladu, můžete povolit podporu zpráv agenta pro následující předdefinované vyhodnocovače k vyhodnocení těchto aspektů pracovního postupu agentů. Při vyhodnocování agentů můžou tyto vyhodnocovače převzít tool_calls nebo tool_definitions jako parametry jedinečné pro agenty.

Hodnotitel query response tool_calls tool_definitions
IntentResolutionEvaluator Požadovaný: Union[str, list[Message]] Požadovaný: Union[str, list[Message]] Nevztahuje se Volitelný: list[ToolCall]
ToolCallAccuracyEvaluator Požadovaný: Union[str, list[Message]] Volitelný: Union[str, list[Message]] Volitelný: Union[dict, list[ToolCall]] Požadovaný: list[ToolDefinition]
TaskAdherenceEvaluator Požadovaný: Union[str, list[Message]] Požadovaný: Union[str, list[Message]] Nevztahuje se Volitelný: list[ToolCall]
GroundednessEvaluator Požadovaný: Union[str, list[Message]] Požadovaný: Union[str, list[Message]] Nevztahuje se Požadovaný: list[ToolCall]
  • Message: dict Zpráva ve stylu OpenAI, která popisuje interakce agenta s uživatelem, kde query musí obsahovat systémovou zprávu jako první zprávu.
  • ToolCall: dict určuje volání nástrojů vyvolaná během interakcí agenta s uživatelem.
  • ToolDefinition: dict popisuje nástroje dostupné pro agenta.

Pro ToolCallAccuracyEvaluator, musíte poskytnout buď response nebo tool_calls.

GroundednessEvaluator vyžaduje tool_definitions vyhodnotit, jak dobře jsou odpovědi agenta založeny ve vztahu k výstupům nástroje, které agent obdrží.

Následující příklady ukazují dva formáty dat: jednoduchá data agenta a zprávy agenta. Vzhledem k jedinečným požadavkům těchto vyhodnocovačů se ale podívejte na ukázkové poznámkové bloky, které ilustrují možné vstupní cesty pro každý vyhodnocovací modul.

Všechny integrované vyhodnocovače kvality s asistencí umělé inteligence vypíší úspěch nebo selhání pro každý vstup.

Jednoduchá data agenta

Ve formátu dat jednoduchého agenta jsou query a response jednoduché řetězce Pythonu. Například:

import os
import json
from azure.ai.evaluation import AzureOpenAIModelConfiguration
from azure.identity import DefaultAzureCredential
from azure.ai.evaluation import IntentResolutionEvaluator, ResponseCompletenessEvaluator
  
model_config = AzureOpenAIModelConfiguration(
    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
    api_key=os.environ["AZURE_OPENAI_API_KEY"],
    api_version=os.environ["AZURE_OPENAI_API_VERSION"],
    azure_deployment=os.environ["MODEL_DEPLOYMENT_NAME"],
)
 
intent_resolution_evaluator = IntentResolutionEvaluator(model_config)

# Evaluate the query and response as strings.
# The following is a positive example. Intent is identified and understood and the response correctly resolves user intent.
result = intent_resolution_evaluator(
    query="What are the opening hours of the Eiffel Tower?",
    response="Opening hours of the Eiffel Tower are 9:00 AM to 11:00 PM.",
)
print(json.dumps(result, indent=4))

Podrobnosti najdete v následujícím výstupu (podrobnosti najdete ve výstupním formátu ):

{
    "intent_resolution": 5.0,
    "intent_resolution_result": "pass",
    "intent_resolution_threshold": 3,
    "intent_resolution_reason": "The response provides the opening hours of the Eiffel Tower, which directly addresses the user's query. The information is clear, accurate, and complete, fully resolving the user's intent.",
}

Volání a definice nástroje agenta

Podívejte se na následující příklady tool_calls a tool_definitions pro ToolCallAccuracyEvaluator:

import json 

query = "How is the weather in Seattle?"
tool_calls = [{
                    "type": "tool_call",
                    "tool_call_id": "call_CUdbkBfvVBla2YP3p24uhElJ",
                    "name": "fetch_weather",
                    "arguments": {
                        "location": "Seattle"
                    }
            },
            {
                    "type": "tool_call",
                    "tool_call_id": "call_CUdbkBfvVBla2YP3p24uhElJ",
                    "name": "fetch_weather",
                    "arguments": {
                        "location": "London"
                    }
            }]

tool_definitions = [{
                    "name": "fetch_weather",
                    "description": "Fetches the weather information for the specified location.",
                    "parameters": {
                        "type": "object",
                        "properties": {
                            "location": {
                                "type": "string",
                                "description": "The location to fetch weather for."
                            }
                        }
                    }
                }]

from azure.ai.evaluation import ToolCallAccuracyEvaluator

tool_call_accuracy = ToolCallAccuracyEvaluator(model_config) # reuse the config defined above
response = tool_call_accuracy(query=query, tool_calls=tool_calls, tool_definitions=tool_definitions)
print(json.dumps(response, indent=4))

Podrobnosti najdete v následujícím výstupu (podrobnosti najdete v referenčním formátu výstupu ):

{
    "tool_call_accuracy": 3,  # a score between 1-5, higher is better
    "tool_call_accuracy_result": "fail",
    "tool_call_accuracy_threshold": 4,
    "details": { ... } # helpful details for debugging the tool calls made by the agent
}

Schéma zpráv agenta

Ve formátu zprávy agenta, jsou query a response seznamy zpráv ve stylu OpenAI. Konkrétně obsahuje předchozí interakce mezi agentem a uživatelem, které vedou k poslednímu dotazu uživatele query a je nutné, aby systémová zpráva (od agenta) byla v horní části seznamu. response nese poslední zprávu od agenta v reakci na poslední dotaz uživatele.

Očekávaný vstupní formát vyhodnocovačů je seznam zpráv Pythonu následujícím způsobem:

[
  {
    "role": "system" | "user" | "assistant" | "tool",
    "createdAt": "ISO 8601 timestamp",     // Optional for 'system'
    "run_id": "string",                    // Optional, only for assistant/tool in tool call context
    "tool_call_id": "string",              // Optional, only for tool/tool_result
    "name": "string",                      // Present if it's a tool call
    "arguments": { ... },                  // Parameters passed to the tool (if tool call)
    "content": [
      {
        "type": "text" | "tool_call" | "tool_result",
        "text": "string",                  // if type == text
        "tool_call_id": "string",         // if type == tool_call
        "name": "string",                 // tool name if type == tool_call
        "arguments": { ... },             // tool args if type == tool_call
        "tool_result": { ... }            // result if type == tool_result
      }
    ]
  }
]

Ukázkové objekty dotazů a odpovědí:

query = [
    {
        "role": "system",
        "content": "You are an AI assistant interacting with Azure Maps services to serve user requests."
    },
    {
        "createdAt": "2025-04-25T23:55:43Z",
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": "Find the address for coordinates 41.8781,-87.6298."
            }
        ]
    },
    {
        "createdAt": "2025-04-25T23:55:45Z",
        "run_id": "run_DGE8RWPS8A9SmfCg61waRx9u",
        "role": "assistant",
        "content": [
            {
                "type": "tool_call",
                "tool_call_id": "call_nqNyhOFRw4FmF50jaCCq2rDa",
                "name": "azure_maps_reverse_address_search",
                "arguments": {
                    "lat": "41.8781",
                    "lon": "-87.6298"
                }
            }
        ]
    },
    {
        "createdAt": "2025-04-25T23:55:47Z",
        "run_id": "run_DGE8RWPS8A9SmfCg61waRx9u",
        "tool_call_id": "call_nqNyhOFRw4FmF50jaCCq2rDa",
        "role": "tool",
        "content": [
            {
                "type": "tool_result",
                "tool_result": {
                    "address": "300 South Federal Street, Chicago, IL 60604",
                    "position": {
                        "lat": "41.8781",
                        "lon": "-87.6298"
                    }
                }
            }
        ]
    },
    {
        "createdAt": "2025-04-25T23:55:48Z",
        "run_id": "run_DGE8RWPS8A9SmfCg61waRx9u",
        "role": "assistant",
        "content": [
            {
                "type": "text",
                "text": "The address for the coordinates 41.8781, -87.6298 is 300 South Federal Street, Chicago, IL 60604."
            }
        ]
    },
    {
        "createdAt": "2025-04-25T23:55:50Z",
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": "What timezone corresponds to 41.8781,-87.6298?"
            }
        ]
    },
]

response = [
    {
        "createdAt": "2025-04-25T23:55:52Z",
        "run_id": "run_DmnhUGqYd1vCBolcjjODVitB",
        "role": "assistant",
        "content": [
            {
                "type": "tool_call",
                "tool_call_id": "call_qi2ug31JqzDuLy7zF5uiMbGU",
                "name": "azure_maps_timezone",
                "arguments": {
                    "lat": 41.878100000000003,
                    "lon": -87.629800000000003
                }
            }
        ]
    },
    {
        "createdAt": "2025-04-25T23:55:54Z",
        "run_id": "run_DmnhUGqYd1vCBolcjjODVitB",
        "tool_call_id": "call_qi2ug31JqzDuLy7zF5uiMbGU",
        "role": "tool",
        "content": [
            {
                "type": "tool_result",
                "tool_result": {
                    "ianaId": "America/Chicago",
                    "utcOffset": None,
                    "abbreviation": None,
                    "isDaylightSavingTime": None
                }
            }
        ]
    },
    {
        "createdAt": "2025-04-25T23:55:55Z",
        "run_id": "run_DmnhUGqYd1vCBolcjjODVitB",
        "role": "assistant",
        "content": [
            {
                "type": "text",
                "text": "The timezone for the coordinates 41.8781, -87.6298 is America/Chicago."
            }
        ]
    }
]

Poznámka:

Vyhodnocovač zobrazí upozornění, pokud dotaz (historie konverzací až do aktuálního spuštění) nebo odpověď agenta (odpověď na dotaz) není v očekávaném formátu.

Příklad vyhodnocení zpráv agenta pomocí:ToolCallAccuracyEvaluator

import json

# The user asked a question.
query = [
    {
        "role": "system",
        "content": "You are a friendly and helpful customer service agent."
    },
    # Past interactions are omitted. 
    # ...
    {
        "createdAt": "2025-03-14T06:14:20Z",
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": "Hi, I need help with the last 2 orders on my account #888. Could you please update me on their status?"
            }
        ]
    }
]
# The agent emits multiple messages to fulfill the request.
response = [
    {
        "createdAt": "2025-03-14T06:14:30Z",
        "run_id": "0",
        "role": "assistant",
        "content": [
            {
                "type": "text",
                "text": "Hello! Let me quickly look up your account details."
            }
        ]
    },
    {
        "createdAt": "2025-03-14T06:14:35Z",
        "run_id": "0",
        "role": "assistant",
        "content": [
            {
                "type": "tool_call",
                "tool_call_id": "tool_call_20250310_001",
                "name": "get_orders",
                "arguments": {
                    "account_number": "888"
                }
            }
        ]
    },
    # Many more messages are omitted. 
    # ...
    # Here is the agent's final response:
    {
        "createdAt": "2025-03-14T06:15:05Z",
        "run_id": "0",
        "role": "assistant",
        "content": [
            {
                "type": "text",
                "text": "The order with ID 123 has been shipped and is expected to be delivered on March 15, 2025. However, the order with ID 124 is delayed and should now arrive by March 20, 2025. Is there anything else I can help you with?"
            }
        ]
    }
]

# An example of tool definitions available to the agent:
tool_definitions = [
    {
        "name": "get_orders",
        "description": "Get the list of orders for a given account number.",
        "parameters": {
            "type": "object",
            "properties": {
                "account_number": {
                    "type": "string",
                    "description": "The account number to get the orders for."
                }
            }
        }
    },
    # Other tool definitions are omitted. 
    # ...
]

result = tool_call_accuracy(
    query=query,
    response=response,
    tool_definitions=tool_definitions 
)
print(json.dumps(result, indent=4))

Podrobnosti najdete v následujícím výstupu (podrobnosti najdete v referenčním formátu výstupu ):

{
    "tool_call_accuracy": 2,  # a score between 1-5, higher is better
    "tool_call_accuracy_result": "fail",
    "tool_call_accuracy_threshold": 3,
    "details": { ... } # helpful details for debugging the tool calls made by the agent
}

Toto schéma vyhodnocení pomáhá analyzovat data agenta mimo službu agenta, což umožňuje použití integrovaných vyhodnocovačů pro podporu pozorovatelnosti v pracovních postupech agenta.

Ukázkové notebooky

Vyzkoušejte ukázku pro každý z těchto vyhodnocovačů:

Související obsah

  • Last updated on