مشاركة عبر

استخدم استدعاء الدوال مع وكلاء Microsoft Foundry

يدعم وكلاء مايكروسوفت فاوندري استدعاء الوظائف، مما يتيح لك توسيع الوكلاء بقدرات مخصصة. حدد دالة باسمها، ومعاملاتها، ووصفها، ويمكن للوكيل أن يطلب من تطبيقك استدعاؤها. تطبيقك ينفذ الوظيفة ويعيد النتائج. ثم يستخدم الوكيل النتيجة لمواصلة المحادثة ببيانات دقيقة وفي الوقت الحقيقي من أنظمتك.

مهم

تنتهي صلاحية عمليات التشغيل بعد 10 دقائق من الإنشاء. قدم مخرجات أدواتك قبل أن تنتهي صلاحيتها.

يمكنك تشغيل وكلاء باستخدام أدوات الوظائف في بوابة Microsoft Foundry. ومع ذلك، لا تدعم البوابة إضافة أو إزالة أو تحديث تعريفات الدوال على الوكيل. استخدم واجهة برمجة تطبيقات SDK أو REST لتكوين أدوات الوظائف.

دعم الاستخدام

✔️ (GA) تشير إلى التوفر العام، ✔️ (معاينة) تشير إلى معاينة عامة، وشرطة شرطة (-) تشير إلى عدم توفر الميزة.

دعم مايكروسوفت فاوندري حزمة تطوير التطوير الخاصة لبايثون C # SDK حزمة تطوير جافاسكريبت مجموعة تطوير جافا واجهة برمجة تطبيقات REST إعداد العامل الأساسي إعداد العامل القياسي
✔️ ✔️ (GA) ✔️ (معاينة) ✔️ (GA) ✔️ (معاينة) ✔️ (GA) ✔️ ✔️

المتطلبات المسبقه

قبل البدء، تأكد من أن لديك:

  • بيئة عامل أساسية أو قياسية.

  • مشروع Foundry ونموذج تم نشره.

  • حزمة SDK للغتك:

    • Python: azure-ai-projects (الأحدث)
    • .NET: Azure.AI.Extensions.OpenAI (ما قبل الإصدار)
    • TypeScript: @azure/ai-projects (الأحدث)
    • Java: azure-ai-agents (ما قبل الإصدار)

    لخطوات التثبيت والمصادقة، راجع البدء السريع.

نصيحة

إذا استخدمت DefaultAzureCredential، سجل الدخول قبل az login تشغيل العينات.

إنشاء وكيل باستخدام أدوات الدوال

يتبع استدعاء الدوال هذا النمط:

  1. تعريف أدوات الدوال — صف اسم كل دالة ومعلماتها وغرضها.
  2. أنشئ وكيلا — سجل الوكيل بتعريفات الدوال الخاصة بك.
  3. إرسال المطالبة — يقوم الوكيل بتحليل الإشعار ويطلب استدعاءات الدوال إذا لزم الأمر.
  4. التنفيذ والعودة — يقوم تطبيقك بتشغيل الدالة ويعيد إرسال الإخراج إلى الوكيل.
  5. احصل على الاستجابة النهائية — يستخدم الوكيل مخرجات الدالة الخاصة بك لإكمال استجابته.

استخدم عينة الكود التالية لإنشاء وكيل، والتعامل مع استدعاء دالة، وإعادة مخرجات الأداة إلى الوكيل.

import json
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

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

# Format: "https://resource_name.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"

project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_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.agents.create_version(
    agent_name="MyAgent",
    definition=PromptAgentDefinition(
        model="gpt-4.1-mini",
        instructions="You are a helpful assistant that can use function tools.",
        tools=tools,
    ),
)

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

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

# Submit function results and get the final response
response = openai.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}")

# Clean up resources
project.agents.delete_version(agent_name=agent.name, agent_version=agent.version)

الإخراج المتوقع

يوضح المثال التالي الإخراج المتوقع:

Agent response: Your horoscope for Aquarius: Next Tuesday you will befriend a baby otter.

مثال على استخدام الوكلاء مع الدوال

في هذا المثال، تستخدم الدوال المحلية مع الوكلاء. استخدم الدوال لإعطاء الوكيل معلومات محددة ردا على سؤال المستخدم. الكود في هذا المثال متزامن. للحصول على مثال غير متزامن، انظر مثال sample code في Azure SDK المستودع .NET على GitHub.

using System;
using Azure.AI.Projects;
using Azure.AI.Extensions.OpenAI;
using Azure.Identity;

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;
    }

    // Format: "https://resource_name.ai.azure.com/api/projects/project_name"
    private const string ProjectEndpoint = "your_project_endpoint";

    public static void Main() 
    {
        AIProjectClient projectClient = new(endpoint: new Uri(ProjectEndpoint), tokenProvider: new DefaultAzureCredential());
        // Create an agent version with the defined functions as tools.
        PromptAgentDefinition agentDefinition = new(model: "gpt-4.1-mini")
        {
            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);
    }
}

الإخراج المتوقع

يوضح المثال التالي الإخراج المتوقع:

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

هناك طريقتان لاستخدام استدعاء الدوال في خدمة وكلاء المساند.

  1. أنشئ .response عندما تحتاج إلى استدعاء الوكيل للدوال مرة أخرى، أنشئ دوال أخرى response.
  2. أنشئ ، conversationثم أنشئ عدة عناصر للمحادثة. كل عنصر في المحادثة يتوافق مع عنصر واحد response.

قم بتعيين المتغيرات البيئية التالية قبل تشغيل الأمثلة:

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

تعريف دالة لوكيلك للاتصال بها

ابدأ بتعريف دالة لوكيلك لاستدعاءها. عند إنشاء دالة ليتصل بها وكيل، صف هيكلها وأي معلمات مطلوبة في سلسلة المستندات. على سبيل المثال الدوال، انظر لغات SDK الأخرى.

إنشَاء مندوب

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"]
          }
        }
      ]
    }
  }'

إنشاء محادثة

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?"
          }
        ]
      }
    ]
  }'

احفظ معرف المحادثة المرتجع (conv_xyz...) للخطوة التالية.

إنشاء استجابة

استبدلها <CONVERSATION_ID> بمعرف من الخطوة السابقة.

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": []
  }'

الإخراج المتوقع

تحتوي الاستجابة على عنصر استدعاء للوظيفة تحتاج إلى معالجته:

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

بعد معالجة استدعاء الدالة وتقديم المخرج للوكيل، يتضمن الرد النهائي معلومات الطقس بلغة طبيعية.

إرسال مخرجات استدعاء الدالة

بعد معالجة استدعاء الدالة محليا، أعد إرسال النتيجة إلى الوكيل:

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": [
      {
        "type": "function_call_output",
        "call_id": "<CALL_ID>",
        "output": "{\"temperature\": \"30\", \"unit\": \"c\", \"description\": \"Sunny\"}"
      }
    ]
  }'

استبدل <CALL_ID> بالقيمة call_id من استدعاء الدالة في الاستجابة السابقة. يستخدم الوكيل الدالة المخرجة لتوليد إجابة بلغة طبيعية.

استخدم عينة الكود التالية لإنشاء وكيل باستخدام أدوات الوظائف، والتعامل مع استدعاءات الدوال من النموذج، وتوفير نتائج الدوال للحصول على الاستجابة النهائية.

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

// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
const projectEndpoint = "your_project_endpoint";

/**
 * 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 openai = project.getOpenAIClient();

  // Create agent with function tools
  const agent = await project.agents.createVersion("function-tool-agent", {
    kind: "prompt",
    model: "gpt-4.1-mini",
    instructions: "You are a helpful assistant that can use function tools.",
    tools: [funcTool],
  });

  // Prompt the model with tools defined
  const response = await openai.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 }),
        });
      }
    }
  }

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

  // Print the final response
  console.log(finalResponse.output_text);

  // Clean up
  await project.agents.deleteVersion(agent.name, agent.version);
}

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

الإخراج المتوقع

يوضح المثال التالي الإخراج المتوقع:

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

استخدم استدعاء الدوال في وكيل Java

الإعداد

أضف الاعتماد إلى :pom.xml

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-ai-agents</artifactId>
    <version>2.0.0-beta.3</version>
</dependency>

إنشاء وكيل باستخدام أدوات الدوال

import com.azure.ai.agents.AgentsClient;
import com.azure.ai.agents.AgentsClientBuilder;
import com.azure.ai.agents.ResponsesClient;
import com.azure.ai.agents.models.AgentReference;
import com.azure.ai.agents.models.AgentVersionDetails;
import com.azure.ai.agents.models.AzureCreateResponseOptions;
import com.azure.ai.agents.models.FunctionTool;
import com.azure.ai.agents.models.PromptAgentDefinition;
import com.azure.core.util.BinaryData;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.openai.models.responses.Response;
import com.openai.models.responses.ResponseCreateParams;

import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;

public class FunctionCallingExample {
    // Format: "https://resource_name.ai.azure.com/api/projects/project_name"
    private static final String PROJECT_ENDPOINT = "your_project_endpoint";

    public static void main(String[] args) {
        AgentsClientBuilder builder = new AgentsClientBuilder()
            .credential(new DefaultAzureCredentialBuilder().build())
            .endpoint(PROJECT_ENDPOINT);

        AgentsClient agentsClient = builder.buildAgentsClient();
        ResponsesClient responsesClient = builder.buildResponsesClient();

        // Define function parameters
        Map<String, BinaryData> parameters = new HashMap<>();
        parameters.put("type", BinaryData.fromString("\"object\""));
        parameters.put("properties", BinaryData.fromString(
            "{\"location\":{\"type\":\"string\",\"description\":\"The city and state, e.g. Seattle, WA\"},"
            + "\"unit\":{\"type\":\"string\",\"enum\":[\"celsius\",\"fahrenheit\"]}}"));
        parameters.put("required", BinaryData.fromString("[\"location\"]"));

        FunctionTool weatherFunction = new FunctionTool("get_weather", parameters, true);

        // Create agent with function tool
        PromptAgentDefinition agentDefinition = new PromptAgentDefinition("gpt-4.1-mini")
            .setInstructions("You are a weather assistant. Use the get_weather function to retrieve weather information.")
            .setTools(Arrays.asList(weatherFunction));

        AgentVersionDetails agent = agentsClient.createAgentVersion("function-calling-agent", agentDefinition);
        System.out.printf("Agent created: %s (version %s)%n", agent.getName(), agent.getVersion());

        // Create a response - the agent will call the function
        AgentReference agentReference = new AgentReference(agent.getName())
            .setVersion(agent.getVersion());

        Response response = responsesClient.createAzureResponse(
            new AzureCreateResponseOptions().setAgentReference(agentReference),
            ResponseCreateParams.builder()
                .input("What is the weather in Seattle?"));

        System.out.println("Response: " + response.output());

        // Clean up
        agentsClient.deleteAgentVersion(agent.getName(), agent.getVersion());
    }
}

للاطلاع على حلقة استدعاء الدوال الكاملة التي تتعامل مع استدعاء الأداة وترسل النتائج مرة أخرى إلى الوكيل، راجع Azure AI Agents Java عينات SDK.

تحقق من عمل استدعاء الدوال

استخدم هذه الفحوصات للتأكد من أن استدعاء الدوال يعمل:

  1. استجابتك الأولى تحتوي على عنصر مخرج مع type تعيين على function_call.
  2. تطبيقك ينفذ الوظيفة المطلوبة باستخدام الوسائط المرتجعة.
  3. يقدم تطبيقك ردا متابعة يتضمن function_call_output بندا ويشير إلى الرد السابق، ويعيد الوكيل إجابة باللغة الطبيعية.

إذا كنت تستخدم التتبع في Microsoft Foundry، تأكد من حدوث استدعاء الأداة. للحصول على إرشادات حول التحقق من استدعاء الأدوات والتحكم في استخدام الأدوات، راجع أفضل الممارسات لاستخدام الأدوات في خدمة وكلاء مايكروسوفت فاوندري.

اعتبارات الأمان والبيانات

  • عامل حجج الأدوات ومخرجات الأدوات كمدخلات غير موثوقة. تحقق من صحة القيم وتعمقها قبل استخدامها.
  • لا تمرر الأسرار (مفاتيح API، الرموز، سلاسل الاتصال) في مخرجات الأدوات. أعيد فقط البيانات التي يحتاجها النموذج.
  • تطبيق أقل امتياز على الهوية التي يستخدمها DefaultAzureCredential.
  • تجنب الآثار الجانبية إلا إذا كنت تنوي ذلك بشكل صريح. على سبيل المثال، تقييد أدوات الوظائف على العمليات الآمنة، أو تتطلب تأكيدا صريحا من المستخدم للأفعال التي تغير البيانات.
  • بالنسبة للعمليات طويلة الأمد، أعد حالة فورا ونفذ الاستطلاعات. انتهاء صلاحية التشغيل البالغ 10 دقائق تنطبق على إجمالي الوقت المنقضي، وليس على تنفيذ الوظائف الفردية.

استكشاف الأخطاء وإصلاحها

مشكلة السبب المحتمل الحل
الوكيل يعيد استدعاء الدالة لكن لا يوجد إجابة نهائية. لم يتم إرجاع إخراج الأداة إلى النموذج. نفذ الوظيفة، ثم استدعاء responses.create باستخدام إخراج الأداة واستمرار previous_response_id .
لا يحدث استدعاء للدالة. وظيفة ليست في تعريف الوكيل أو تسمية ضعيفة. تأكد من إضافة أداة الدالة إلى الوكيل. استخدم أسماء واضحة ووصفية ووصف للمعلمات.
الحجج ليست صحيحة يا JSON. عدم تطابق المخطط أو النموذج الذي يولد معلومات غير صحيحة. تحقق من أن مخطط JSON يستخدم الأنواع الصحيحة والخصائص المطلوبة. تعامل مع أخطاء التحليل بشكل جيد في تطبيقك.
الحقول المطلوبة مفقودة. Schema لا يفرض الخصائص المطلوبة. أضف "required": [...] مصفوفة إلى مخطط المعلمات الخاص بك. اضبط strict: true للتحقق الأكثر صرامة.
تفشل مخرجات الأدوات بسبب انتهاء الصلاحية. انتهت مدة السلسلة (حد 10 دقائق). إرجاع أدوات الخروج بسرعة. للعمليات البطيئة، أعد حالة واستطلاع بشكل منفصل.
الدالة مستدعاة بمعاملات خاطئة. وصف دالة غامض. حسن مجال الوظائف description . أضف أوصاف مفصلة للمعلمات مع أمثلة.
استدعاءات دوال متعددة في استجابة واحدة. حدد النموذج عدة وظائف مطلوبة. التعامل مع كل استدعاء دالة في مصفوفة الإخراج. أعيد جميع النتائج في مكالمة واحدة responses.create .
الوظيفة غير مرئية في بوابة Foundry. Portal لا ينفذ استدعاءات الدوال. استدعاء وظائف الاختبار عبر SDK أو واجهة برمجة تطبيقات REST. البوابة تعرض العملاء لكنها لا تستدعي وظائف.

تنظيف الموارد

عند الانتهاء من الاختبار، احذف الموارد التي أنشأتها لتجنب التكاليف المستمرة.

حذف الوكيل:

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

احذف المحادثة:

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

المحتوى ذو الصلة

  • Last updated on