Freigeben über

Verwenden von Funktionsaufrufen mit Microsoft Foundry-Agents

Microsoft Foundry Agents unterstützen Funktionsaufrufe, mit denen Sie Agents mit benutzerdefinierten Funktionen erweitern können. Definieren Sie eine Funktion mit dem Namen, den Parametern und der Beschreibung, und der Agent kann Ihre App auffordern, sie aufzurufen. Ihre App führt die Funktion aus und gibt die Ausgabe zurück. Der Agent verwendet dann das Ergebnis, um die Unterhaltung mit genauen Echtzeitdaten aus Ihren Systemen fortzusetzen.

Von Bedeutung

Läuft 10 Minuten nach der Erstellung ab. Übermitteln Sie Ihre Tool-Ausgaben, bevor sie ablaufen.

Sie können Agents mit Funktionstools im Microsoft Foundry-Portal ausführen. Das Portal unterstützt jedoch das Hinzufügen, Entfernen oder Aktualisieren von Funktionsdefinitionen für einen Agent nicht. Verwenden Sie das SDK oder die REST-API, um Funktionstools zu konfigurieren.

Nutzungssupport

✔️ (GA) gibt die allgemeine Verfügbarkeit an, ✔️ (Vorschau) gibt die öffentliche Vorschau an, und ein Gedankenstrich (-) gibt an, dass das Feature nicht verfügbar ist.

Microsoft Foundry-Support Python SDK C# SDK JavaScript SDK Java-SDK REST API Basic-Agent-Setup Standard-Agent-Setup
✔️ ✔️ (Vorschau) ✔️ (Vorschau) ✔️ (Vorschau) - ✔️ (GA) ✔️ ✔️

Hinweis

Das Java SDK unterstützt derzeit keinen Funktionsaufruf mit den neuen Agent-APIs (azure-ai-projects Paket). Java-Unterstützung ist nur für die klassischen Agent-APIs verfügbar. Beispiele für Java-Funktionsaufrufe mit klassischen Agents finden Sie in der Dokumentation zum klassischen Agent.

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass Sie folgendes haben:

  • Eine grundlegende oder Standard-Agent-Umgebung.

  • Ein Foundry-Projekt und ein bereitgestelltes Modell.

  • Das neueste Vorabversions-SDK-Paket für Ihre Sprache:

    • Python: azure-ai-projects>=2.0.0b4
    • .NET: Azure.AI.Projects.OpenAI (Vorabrelease)
    • TypeScript: @azure/ai-projects (neueste Betaversion)

    Installations- und Authentifizierungsschritte finden Sie in der Schnellstartanleitung.

Umgebungsvariablen

Jede Sprache verwendet unterschiedliche Namen von Umgebungsvariablen. Verwenden Sie ein Set konsequent.

Language Projektendpunkt Modellbereitstellungsname
Python FOUNDRY_PROJECT_ENDPOINT FOUNDRY_MODEL_DEPLOYMENT_NAME
C# FOUNDRY_PROJECT_ENDPOINT FOUNDRY_MODEL_DEPLOYMENT_NAME
TypeScript FOUNDRY_PROJECT_ENDPOINT FOUNDRY_MODEL_DEPLOYMENT_NAME
REST API FOUNDRY_PROJECT_ENDPOINT (verwenden Sie das Anforderungstextfeld)

Tipp

Wenn Sie DefaultAzureCredential verwenden, melden Sie sich über az login an, bevor Sie die Beispiele ausführen.

Schnelle Überprüfung

Wenn Sie nicht sicher sind, dass Ihre Authentifizierung und Ihr Endpunkt ordnungsgemäß eingerichtet sind, führen Sie zuerst den folgenden Codeausschnitt aus.

import os

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

load_dotenv()

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"], credential=credential) as project_client,
):
    print("Connected to project.")

Erstellen eines Agents mit Funktionstools

Funktionsaufrufe folgen diesem Muster:

  1. Definieren von Funktionstools – Beschreiben des Namens, der Parameter und des Zwecks der einzelnen Funktionen.
  2. Erstellen Sie einen Agent – Registrieren Sie den Agent mit Ihren Funktionsdefinitionen.
  3. Senden Sie eine Eingabe – Der Agent analysiert die Eingabe und fordert bei Bedarf Funktionsaufrufe an.
  4. Ausführen und Zurückgeben – Ihre App führt die Funktion aus und sendet die Ausgabe an den Agent zurück.
  5. Abrufen der endgültigen Antwort – Der Agent verwendet Ihre Funktionsausgabe, um die Antwort abzuschließen.

Hinweis

Sie benötigen das neueste Vorabpaket. Weitere Informationen finden Sie im Schnellstart.

Verwenden Sie das folgende Codebeispiel, um einen Agent zu erstellen, einen Funktionsaufruf zu verarbeiten und die Ausgabe des Tools zurück an den Agent zurückzugeben.

import os
import json
from dotenv import load_dotenv
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition, Tool, FunctionTool
from azure.identity import DefaultAzureCredential
from openai.types.responses.response_input_param import FunctionCallOutput, ResponseInputParam

load_dotenv()

def get_horoscope(sign: str) -> str:
    """Generate a horoscope for the given astrological sign."""
    return f"{sign}: Next Tuesday you will befriend a baby otter."

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
    project_client.get_openai_client() as openai_client,
):

    # Define a function tool for the model to use
    func_tool = FunctionTool(
        name="get_horoscope",
        parameters={
            "type": "object",
            "properties": {
                "sign": {
                    "type": "string",
                    "description": "An astrological sign like Taurus or Aquarius",
                },
            },
            "required": ["sign"],
            "additionalProperties": False,
        },
        description="Get today's horoscope for an astrological sign.",
        strict=True,
    )

    tools: list[Tool] = [func_tool]

    agent = project_client.agents.create_version(
        agent_name="MyAgent",
        definition=PromptAgentDefinition(
            model=os.environ["FOUNDRY_MODEL_DEPLOYMENT_NAME"],
            instructions="You are a helpful assistant that can use function tools.",
            tools=tools,
        ),
    )

    # Prompt the model with tools defined
    response = openai_client.responses.create(
        input="What is my horoscope? I am an Aquarius.",
        extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
    )
    print(f"Response output: {response.output_text}")

    input_list: ResponseInputParam = []
    # Process function calls
    for item in response.output:
        if item.type == "function_call":
            if item.name == "get_horoscope":
                # Execute the function logic for get_horoscope
                horoscope = get_horoscope(**json.loads(item.arguments))

                # Provide function call results to the model
                input_list.append(
                    FunctionCallOutput(
                        type="function_call_output",
                        call_id=item.call_id,
                        output=json.dumps({"horoscope": horoscope}),
                    )
                )

    print("Final input:")
    print(input_list)

    response = openai_client.responses.create(
        input=input_list,
        previous_response_id=response.id,
        extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
    )

    print(f"Agent response: {response.output_text}")

    print("\nCleaning up...")
    project_client.agents.delete_version(agent_name=agent.name, agent_version=agent.version)
    print("Agent deleted")

Erwartete Ausgabe

Das folgende Beispiel zeigt die erwartete Ausgabe:

Response output: 
Final input:
[FunctionCallOutput(type='function_call_output', call_id='call_abc123', output='{"horoscope": "Aquarius: Next Tuesday you will befriend a baby otter."}')]

Verwenden von Agents mit Funktionen (Beispiel)

In diesem Beispiel verwenden Sie lokale Funktionen mit Agents. Verwenden Sie die Funktionen, um dem Agent spezifische Informationen als Reaktion auf eine Benutzerfrage zu geben. Der Code in diesem Beispiel ist synchron. Ein asynchrones Beispiel finden Sie im Beispielcodebeispiel im Azure SDK für .NET-Repository auf GitHub.

class FunctionCallingDemo
{
    // Define three functions:
    //   1. GetUserFavoriteCity always returns "Seattle, WA".
    //   2. GetCityNickname handles only "Seattle, WA"
    //      and throws an exception for other city names.
    //   3. GetWeatherAtLocation returns the weather in Seattle, WA.

    /// Example of a function that defines no parameters but
    /// returns the user's favorite city.
    private static string GetUserFavoriteCity() => "Seattle, WA";

    /// <summary>
    /// Example of a function with a single required parameter
    /// </summary>
    /// <param name="location">The location to get nickname for.</param>
    /// <returns>The city nickname.</returns>
    /// <exception cref="NotImplementedException"></exception>
    private static string GetCityNickname(string location) => location switch
    {
        "Seattle, WA" => "The Emerald City",
        _ => throw new NotImplementedException(),
    };

    /// <summary>
    /// Example of a function with one required and one optional, enum parameter
    /// </summary>
    /// <param name="location">Get weather for location.</param>
    /// <param name="temperatureUnit">"c" or "f"</param>
    /// <returns>The weather in selected location.</returns>
    /// <exception cref="NotImplementedException"></exception>
    public static string GetWeatherAtLocation(string location, string temperatureUnit = "f") => location switch
    {
        "Seattle, WA" => temperatureUnit == "f" ? "70f" : "21c",
        _ => throw new NotImplementedException()
    };

    // For each function, create FunctionTool, which defines the function name, description, and parameters.
    public static readonly FunctionTool getUserFavoriteCityTool = ResponseTool.CreateFunctionTool(
        functionName: "getUserFavoriteCity",
        functionDescription: "Gets the user's favorite city.",
        functionParameters: BinaryData.FromString("{}"),
        strictModeEnabled: false
    );

    public static readonly FunctionTool getCityNicknameTool = ResponseTool.CreateFunctionTool(
        functionName: "getCityNickname",
        functionDescription: "Gets the nickname of a city, e.g. 'LA' for 'Los Angeles, CA'.",
        functionParameters: BinaryData.FromObjectAsJson(
            new
            {
                Type = "object",
                Properties = new
                {
                    Location = new
                    {
                        Type = "string",
                        Description = "The city and state, e.g. San Francisco, CA",
                    },
                },
                Required = new[] { "location" },
            },
            new JsonSerializerOptions() { PropertyNamingPolicy = JsonNamingPolicy.CamelCase }
        ),
        strictModeEnabled: false
    );

    private static readonly FunctionTool getCurrentWeatherAtLocationTool = ResponseTool.CreateFunctionTool(
        functionName: "getCurrentWeatherAtLocation",
        functionDescription: "Gets the current weather at a provided location.",
        functionParameters: BinaryData.FromObjectAsJson(
             new
             {
                 Type = "object",
                 Properties = new
                 {
                     Location = new
                     {
                         Type = "string",
                         Description = "The city and state, e.g. San Francisco, CA",
                     },
                     Unit = new
                     {
                         Type = "string",
                         Enum = new[] { "c", "f" },
                     },
                 },
                 Required = new[] { "location" },
             },
            new JsonSerializerOptions() { PropertyNamingPolicy = JsonNamingPolicy.CamelCase }
        ),
        strictModeEnabled: false
    );

    // Create the method GetResolvedToolOutput.
    // It runs the preceding functions and wraps the output in a ResponseItem object.
    private static FunctionCallOutputResponseItem GetResolvedToolOutput(FunctionCallResponseItem item)
    {
        if (item.FunctionName == getUserFavoriteCityTool.FunctionName)
        {
            return ResponseItem.CreateFunctionCallOutputItem(item.CallId, GetUserFavoriteCity());
        }
        using JsonDocument argumentsJson = JsonDocument.Parse(item.FunctionArguments);
        if (item.FunctionName == getCityNicknameTool.FunctionName)
        {
            string locationArgument = argumentsJson.RootElement.GetProperty("location").GetString();
            return ResponseItem.CreateFunctionCallOutputItem(item.CallId, GetCityNickname(locationArgument));
        }
        if (item.FunctionName == getCurrentWeatherAtLocationTool.FunctionName)
        {
            string locationArgument = argumentsJson.RootElement.GetProperty("location").GetString();
            if (argumentsJson.RootElement.TryGetProperty("unit", out JsonElement unitElement))
            {
                string unitArgument = unitElement.GetString();
                return ResponseItem.CreateFunctionCallOutputItem(item.CallId, GetWeatherAtLocation(locationArgument, unitArgument));
            }
            return ResponseItem.CreateFunctionCallOutputItem(item.CallId, GetWeatherAtLocation(locationArgument));
        }
        return null;
    }

    public static void Main() 
    {
        // Create project client and read the environment variables that will be used in the next steps.
        var projectEndpoint = System.Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT");
        var modelDeploymentName = System.Environment.GetEnvironmentVariable("FOUNDRY_MODEL_DEPLOYMENT_NAME");
        AIProjectClient projectClient = new(endpoint: new Uri(projectEndpoint), tokenProvider: new DefaultAzureCredential());
        // Create an agent version with the defined functions as tools.
        PromptAgentDefinition agentDefinition = new(model: modelDeploymentName)
        {
            Instructions = "You are a weather bot. Use the provided functions to help answer questions. "
                    + "Customize your responses to the user's preferences as much as possible and use friendly "
                    + "nicknames for cities whenever possible.",
            Tools = { getUserFavoriteCityTool, getCityNicknameTool, getCurrentWeatherAtLocationTool }
        };
        AgentVersion agentVersion = projectClient.Agents.CreateAgentVersion(
            agentName: "myAgent",
            options: new(agentDefinition));

        // If the local function call is required, the response item is of type FunctionCallResponseItem.
        // It contains the function name needed by the Agent. In this case, use the helper method
        // GetResolvedToolOutput to get the FunctionCallOutputResponseItem with the function call result.
        // To provide the right answer, supply all the response items to the CreateResponse call.
        // At the end, output the function's response.
        ResponsesClient responseClient = projectClient.OpenAI.GetProjectResponsesClientForAgent(agentVersion.Name);

        ResponseItem request = ResponseItem.CreateUserMessageItem("What's the weather like in my favorite city?");
        var inputItems = new List<ResponseItem> { request };
        string previousResponseId = null;
        bool functionCalled = false;
        ResponseResult response;
        do
        {
            response = responseClient.CreateResponse(
                previousResponseId: previousResponseId,
                inputItems: inputItems);
            previousResponseId = response.Id;
            inputItems.Clear();
            functionCalled = false;
            foreach (ResponseItem responseItem in response.OutputItems)
            {
                inputItems.Add(responseItem);
                if (responseItem is FunctionCallResponseItem functionToolCall)
                {
                    Console.WriteLine($"Calling {functionToolCall.FunctionName}...");
                    inputItems.Add(GetResolvedToolOutput(functionToolCall));
                    functionCalled = true;
                }
            }
        } while (functionCalled);
        Console.WriteLine(response.GetOutputText());

        // Remove all the resources created in this sample.
        projectClient.Agents.DeleteAgentVersion(agentName: agentVersion.Name, agentVersion: agentVersion.Version);
    }
}

Erwartete Ausgabe

Das folgende Beispiel zeigt die erwartete Ausgabe:

Calling getUserFavoriteCity...
Calling getCityNickname...
Calling getCurrentWeatherAtLocation...
Your favorite city, Seattle, WA, is also known as The Emerald City. The current weather there is 70f.

Es gibt zwei Möglichkeiten zum Verwenden von Funktionsaufrufen im Foundry Agent Service.

  1. Erstellen Sie eine response. Wenn Sie den Agent zum erneuten Aufrufen von Funktionen benötigen, erstellen Sie eine weitere response.
  2. Erstellen Sie ein conversation, und erstellen Sie dann mehrere Konversationselemente. Jedes Gesprächselement entspricht einem response.

Legen Sie die folgenden Umgebungsvariablen fest, bevor Sie die Beispiele ausführen:

export AGENT_TOKEN=$(az account get-access-token --scope "https://ai.azure.com/.default" --query accessToken -o tsv)

Definieren einer Funktion, die Ihr Agent aufrufen soll

Definieren Sie zunächst eine Funktion für ihren Agent, die aufgerufen werden soll. Wenn Sie eine Funktion für einen Agent zum Aufrufen erstellen, beschreiben Sie die Struktur und alle erforderlichen Parameter in einer Docstring-Datei. Beispielfunktionen finden Sie in den anderen SDK-Sprachen.

Einen Agent erstellen

curl -X POST "$FOUNDRY_PROJECT_ENDPOINT/agents?api-version=v1" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -d '{
    "name": "<AGENT_NAME>-function-calling",
    "description": "Agent with function calling",
    "definition": {
      "kind": "prompt",
      "model": "<MODEL_DEPLOYMENT>",
      "instructions": "You are a helpful agent.",
      "tools": [
        {
          "type": "function",
          "name": "getCurrentWeather",
          "description": "Get the current weather in a location",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {"type": "string", "description": "The city and state e.g. San Francisco, CA"},
              "unit": {"type": "string", "enum": ["c", "f"]}
            },
            "required": ["location"]
          }
        }
      ]
    }
  }'

Erstellen einer Unterhaltung

curl -X POST "$FOUNDRY_PROJECT_ENDPOINT/openai/v1/conversations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -d '{
    "items": [
      {
        "type": "message",
        "role": "user",
        "content": [
          {
            "type": "input_text",
            "text": "What'\''s the weather in Dar es Salaam, Tanzania?"
          }
        ]
      }
    ]
  }'

Speichern Sie die zurückgegebene Unterhaltungs-ID (conv_xyz...) für den nächsten Schritt.

Erstellen einer Antwort

Ersetzen Sie <CONVERSATION_ID> durch die ID aus dem vorherigen Schritt.

curl -X POST "$FOUNDRY_PROJECT_ENDPOINT/openai/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -d '{
    "agent": {"type": "agent_reference", "name": "<AGENT_NAME>-function-calling"},
    "conversation": "<CONVERSATION_ID>",
    "input": []
  }'

Erwartete Ausgabe

Die Antwort enthält ein Funktionsaufrufelement, das Sie verarbeiten müssen:

{
  "output": [
    {
      "type": "function_call",
      "call_id": "call_xyz789",
      "name": "getCurrentWeather",
      "arguments": "{\"location\": \"Dar es Salaam, Tanzania\", \"unit\": \"c\"}"
    }
  ]
}

Nachdem Sie den Funktionsaufruf verarbeitet und die Ausgabe an den Agent zurückgeben, enthält die abschließende Antwort die Wetterinformationen in natürlicher Sprache.

Verwenden Sie das folgende Codebeispiel, um einen Agent mit Funktionstools zu erstellen, Funktionsaufrufe aus dem Modell zu behandeln und Funktionsergebnisse bereitzustellen, um die endgültige Antwort zu erhalten.

import { DefaultAzureCredential } from "@azure/identity";
import { AIProjectClient } from "@azure/ai-projects";
import "dotenv/config";

const projectEndpoint = process.env["FOUNDRY_PROJECT_ENDPOINT"] || "<project endpoint>";
const deploymentName = process.env["FOUNDRY_MODEL_DEPLOYMENT_NAME"] || "<model deployment name>";

/**
 * Define a function tool for the model to use
 */
const funcTool = {
  type: "function" as const,
  name: "get_horoscope",
  description: "Get today's horoscope for an astrological sign.",
  strict: true,
  parameters: {
    type: "object",
    properties: {
      sign: {
        type: "string",
        description: "An astrological sign like Taurus or Aquarius",
      },
    },
    required: ["sign"],
    additionalProperties: false,
  },
};

/**
 * Generate a horoscope for the given astrological sign.
 */
function getHoroscope(sign: string): string {
  return `${sign}: Next Tuesday you will befriend a baby otter.`;
}

export async function main(): Promise<void> {
  // Create AI Project client
  const project = new AIProjectClient(projectEndpoint, new DefaultAzureCredential());
  const openAIClient = await project.getOpenAIClient();

  // Create agent with function tools
  console.log("Creating agent with function tools...");
  const agent = await project.agents.createVersion("function-tool-agent", {
    kind: "prompt",
    model: deploymentName,
    instructions: "You are a helpful assistant that can use function tools.",
    tools: [funcTool],
  });
  console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);

  // Prompt the model with tools defined
  console.log("\nGenerating initial response...");
  const response = await openAIClient.responses.create(
    {
      input: [
        {
          type: "message",
          role: "user",
          content: "What is my horoscope? I am an Aquarius.",
        },
      ],
    },
    {
      body: { agent: { name: agent.name, type: "agent_reference" } },
    },
  );
  console.log(`Response output: ${response.output_text}`);

  // Process function calls
  const inputList: Array<{
    type: "function_call_output";
    call_id: string;
    output: string;
  }> = [];

  for (const item of response.output) {
    if (item.type === "function_call") {
      if (item.name === "get_horoscope") {
        // Parse the function arguments
        const args = JSON.parse(item.arguments);

        // Execute the function logic for get_horoscope
        const horoscope = getHoroscope(args.sign);

        // Provide function call results to the model
        inputList.push({
          type: "function_call_output",
          call_id: item.call_id,
          output: JSON.stringify({ horoscope }),
        });
      }
    }
  }

  console.log("\nFinal input:");
  console.log(JSON.stringify(inputList, null, 2));

  // Submit function results to get final response
  const finalResponse = await openAIClient.responses.create(
    {
      input: inputList,
      previous_response_id: response.id,
    },
    {
      body: { agent: { name: agent.name, type: "agent_reference" } },
    },
  );

  // The model should be able to give a response!
  console.log("\nFinal output:");
  console.log(finalResponse.output_text);

  // Clean up
  console.log("\nCleaning up resources...");
  await project.agents.deleteVersion(agent.name, agent.version);
  console.log("Agent deleted");
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

Erwartete Ausgabe

Das folgende Beispiel zeigt die erwartete Ausgabe:

Creating agent with function tools...
Agent created (id: <agent-id>, name: function-tool-agent, version: <version>)

Generating initial response...
Response output: 

Final input:
[
  {
    "type": "function_call_output",
    "call_id": "call_abc123",
    "output": "{\"horoscope\":\"Aquarius: Next Tuesday you will befriend a baby otter.\"}"
  }
]

Final output:
Your horoscope for Aquarius: Next Tuesday you will befriend a baby otter.

Cleaning up resources...
Agent deleted

Überprüfen, ob Funktionsaufrufe funktionieren

Verwenden Sie diese Überprüfungen, um zu bestätigen, dass funktionsaufrufe funktionieren:

  1. Ihre erste Antwort enthält ein Ausgabeelement, auf das type auf function_call gesetzt ist.
  2. Ihre App führt die angeforderte Funktion mithilfe der zurückgegebenen Argumente aus.
  3. Ihre App sendet eine Nachverfolgungsantwort, die ein function_call_output Element enthält und auf die vorherige Antwort verweist, und der Agent gibt eine Antwort in natürlicher Sprache zurück.

Bestätigen Sie, wenn Sie die Ablaufverfolgung in Microsoft Foundry verwenden, dass der Toolaufruf erfolgt ist. Anleitungen zur Überprüfung von Toolaufrufen und zur Steuerung der Toolverwendung finden Sie unter Bewährte Methoden für die Verwendung von Tools im Microsoft Foundry Agent Service.

Überlegungen zu Sicherheit und Daten

  • Behandeln Sie Toolargumente und Toolausgaben als unsichere Eingaben. Validieren und bereinigen Sie Werte, bevor Sie sie verwenden.
  • Übergeben Sie geheime Schlüssel (API-Schlüssel, Token, Verbindungszeichenfolgen) nicht in der Toolausgabe. Gibt nur die Daten zurück, die das Modell benötigt.
  • Verwenden Sie die Berechtigung mit den geringsten Rechten für die Identität, die von DefaultAzureCredential verwendet wird.
  • Vermeiden Sie Nebenwirkungen, es sei denn, Sie beabsichtigen sie explizit. Beschränken Sie beispielsweise Funktionstools auf sichere Vorgänge oder erfordern eine explizite Benutzerbestätigung für Aktionen, die Daten ändern.
  • Geben Sie bei langwierigen Vorgängen sofort einen Status zurück und implementieren Sie eine Abfrage. Der Ablauf der 10-minütigen Laufzeitbegrenzung gilt für die gesamte verstrichene Zeit, nicht für die Ausführung jeder einzelnen Funktion.

Problembehandlung

Thema Wahrscheinliche Ursache Beschluss
Agent gibt Funktionsaufruf zurück, aber keine endgültige Antwort. Die Toolausgabe wurde nicht zum Modell zurückgegeben. Führen Sie die Funktion aus, rufen Sie dann responses.create mit der Toolausgabe auf und fahren mit previous_response_id fort.
Es erfolgt kein Funktionsaufruf. Die Funktion ist nicht in der Agent-Definition enthalten oder wurde schlecht benannt. Bestätigen Sie, dass das Funktionstool dem Agent hinzugefügt wird. Verwenden Sie klare, beschreibende Namen und Parameterbeschreibungen.
Argumente sind keine gültigen JSON-Strukturen. Schemakonflikt oder Modell halluzination. Überprüfen Sie, ob das JSON-Schema korrekte Typen und erforderliche Eigenschaften verwendet. Behandeln Sie Parsefehler sorgfältig in Ihrer App.
Es fehlen Pflichtfelder. Das Schema erzwingt keine erforderlichen Eigenschaften. Fügen Sie "required": [...] ein Array zu Ihrem Parameterschema hinzu. Setzen Sie strict: true für eine strengere Validierung.
Die Toolausgabe schlägt wegen Ablauf fehl. Läuft abgelaufen (10-Minuten-Grenzwert). Gibt die Ausgabe des Tools umgehend zurück. Geben Sie bei langsamen Vorgängen einen Status zurück und fragen Sie separat ab.
Funktion wird mit falschen Parametern aufgerufen. Mehrdeutige Funktionsbeschreibung. Verbessern Sie das Funktionsfeld description . Fügen Sie detaillierte Parameterbeschreibungen mit Beispielen hinzu.
Mehrere Funktionsaufrufe in einer Antwort. Das Modell hat mehrere erforderliche Funktionen ermittelt. Behandeln Sie jeden Funktionsaufruf im Ausgabearray. Gibt alle Ergebnisse in einem einzelnen responses.create Aufruf zurück.
Funktion im Foundry-Portal nicht sichtbar. Das Portal führt keine Funktionsaufrufe aus. Testen Sie funktionsaufrufe über SDK oder REST-API. Das Portal zeigt Agents an, ruft jedoch keine Funktionen auf.

Bereinigen von Ressourcen

Wenn Sie den Test abgeschlossen haben, löschen Sie die von Ihnen erstellten Ressourcen, um laufende Kosten zu vermeiden.

Löschen Sie den Agent:

curl -X DELETE "$FOUNDRY_PROJECT_ENDPOINT/agents/<AGENT_NAME>-function-calling?api-version=v1" \
  -H "Authorization: Bearer $AGENT_TOKEN"

Löschen sie die Unterhaltung:

curl -X DELETE "$FOUNDRY_PROJECT_ENDPOINT/openai/v1/conversations/<CONVERSATION_ID>" \
  -H "Authorization: Bearer $AGENT_TOKEN"

Verwandte Inhalte

  • Last updated on