Microsoft Foundry aracılarıyla işlev çağrısı kullanma

Microsoft Foundry aracıları, aracıları özel özelliklerle genişletmenize olanak tanıyan işlev çağrılarını destekler. Adı, parametreleri ve açıklaması olan bir işlev tanımlayın; aracının Foundry modeli uygulamanızın çağırmasını isteyebilir. Uygulamanız işlevi yürütür ve çıkışı döndürür. Sonucu kullanarak, aracı sistemlerinizden gelen doğru ve gerçek zamanlı verilerle konuşmanıza devam eder.

Önemli

İşletimlerin süresi oluşturulduktan 10 dakika sonra sona erer. Araç çıktılarını süresi dolmadan önce gönderin.

Microsoft Foundry portalında işlev araçlarıyla aracıları çalıştırabilirsiniz. Ancak portal, bir aracıya işlev tanımları eklemeyi, kaldırmayı veya güncelleştirmeyi desteklemez. İşlev araçlarını yapılandırmak için SDK veya REST API'yi kullanın.

Kullanım desteği

Aşağıdaki tabloda SDK ve kurulum desteği gösterilmektedir.

Microsoft Foundry desteği Python SDK C# SDK'sı JavaScript SDK'sı Java SDK REST API Temel aracı kurulumu Standart ajan kurulumu
✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️

Önkoşullar

Başlamadan önce şunları yaptığınızdan emin olun:

  • Temel veya standart aracı ortamı.

  • Dökümhane projesi ve dağıtılan model.

  • Diliniz için SDK paketi:

    • Python: azure-ai-projects (en son)
    • .NET: Azure.AI.Extensions.OpenAI
    • TypeScript: @azure/ai-projects (son sürümde)
    • Java: azure-ai-agents

    Yükleme ve kimlik doğrulama adımları için hızlı başlangıç bölümüne bakın.

Ipucu

Eğer DefaultAzureCredential kullanıyorsanız, örnekleri çalıştırmadan önce az login kullanarak oturum açın.

İşlev araçlarıyla aracı oluşturma

İşlev çağrısı şu deseni izler:

  1. İşlev araçlarını tanımlama — Her işlevin adını, parametrelerini ve amacını açıklayın.
  2. Aracı oluşturma — Aracıyı işlev tanımlarınıza kaydedin.
  3. İstem gönder — Aracı, istemi analiz eder ve gerekirse işlev çağrılarını ister.
  4. Yürütme ve döndürme — Uygulamanız işlevi çalıştırır ve çıkışı aracıya geri gönderir.
  5. Son yanıtı alma — Aracı, yanıtını tamamlamak için işlev çıkışınızı kullanır.

Aracı oluşturmak, işlev çağrısını işlemek ve aracıya araç çıkışı döndürmek için aşağıdaki kod örneğini kullanın.

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

# Create a conversation for multi-turn interaction
conversation = openai.conversations.create()

# 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.",
    conversation=conversation.id,
    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,
    conversation=conversation.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)
openai.conversations.delete(conversation_id=conversation.id)

Beklenen çıkış

Aşağıdaki örnekte beklenen çıkış gösterilmektedir:

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

İşlevlerle aracıları kullanma örneği

Bu örnekte, aracılarla yerel işlevleri kullanırsınız. Kullanıcı sorusuna yanıt olarak Aracıya özel bilgiler vermek için işlevlerini kullanın. Bu örnekteki kod zaman uyumlu. Zaman uyumsuz bir örnek için GitHub .NET deposu için Azure SDK sample code örneğine bakın.

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.
        DeclarativeAgentDefinition 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.AgentAdministrationClient.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.ProjectOpenAIClient.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.AgentAdministrationClient.DeleteAgentVersion(agentName: agentVersion.Name, agentVersion: agentVersion.Version);
    }
}

Beklenen çıkış

Aşağıdaki örnekte beklenen çıkış gösterilmektedir:

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

Foundry Agent Service'te işlev çağrısını kullanmanın iki yolu vardır.

  1. response oluşturun. Aracı işlevleri yeniden çağırması gerektiğinde, başka bir response oluşturun.
  2. bir conversationoluşturun ve birden çok konuşma öğesi oluşturun. Her konuşma öğesi bir responseöğesine karşılık gelir.

Örnekleri çalıştırmadan önce aşağıdaki ortam değişkenlerini ayarlayın:

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

Aracınızın çağıracağı bir işlevi tanımlayın

Öncelikle ajanın çağıracağı bir işlev tanımlayın. Aracının çağıracağı bir işlev oluşturduğunuzda, bir docstring'de aracının yapısını ve gerekli parametreleri açıklayın. Örnek işlevler için diğer SDK dillerine bakın.

Bir ajan oluştur

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

Konuşma oluşturma

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

Bir sonraki adım için döndürülen konuşma kimliğini (conv_xyz...) kaydedin.

Yanıt oluşturma

değerini önceki adımdaki kimlikle değiştirin <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": []
  }'

Beklenen çıkış

Yanıt, işlemeniz gereken bir işlev çağrısı öğesi içerir:

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

İşlev çağrısını işleyip çıkışı aracıya sağladıktan sonra, son yanıt doğal bir dilde hava durumu bilgilerini içerir.

İşlev çağrısı çıkışını gönderme

İşlev çağrısını yerel olarak işledikten sonra sonucu aracıya geri gönderin:

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> değerini önceki yanıttaki işlev çağrısındaki call_id değeriyle değiştirin. Ajan, doğal dil yanıtı oluşturmak için işlev çıkışını kullanır.

İşlev araçlarıyla bir aracı oluşturmak, modelden gelen işlev çağrılarını işlemek ve son yanıtı almak için işlev sonuçları sağlamak için aşağıdaki kod örneğini kullanın.

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 a conversation for multi-turn interaction
  const conversation = await openai.conversations.create();

  // 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.",
        },
      ],
      conversation: conversation.id,
    },
    {
      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,
      conversation: conversation.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);
  await openai.conversations.delete(conversation.id);
}

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

Beklenen çıkış

Aşağıdaki örnekte beklenen çıkış gösterilmektedir:

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

Java aracısında işlev çağrısı kullanma

Ayarlamak

bağımlılığını öğesinin pom.xmliçine ekleyin:

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

İşlev araçlarıyla aracı oluşturma

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

Araç çağrısını işleyen ve sonuçları aracıya geri gönderen tam işlev çağrısı döngüsü için bkz. Azure AI Agents Java SDK örnekleri.

İşlev çağrısının çalıştığını doğrulama

İşlev çağrısının çalıştığını onaylamak için şu denetimleri kullanın:

  1. İlk yanıtınız, typefunction_call olarak ayarlanmış bir çıkış öğesi içeriyor.
  2. Uygulamanız döndürülen bağımsız değişkenleri kullanarak istenen işlevi yürütür.
  3. Uygulamanız bir öğe içeren function_call_output bir takip yanıtı gönderir ve önceki yanıta başvurur, ve aracı doğal dilde bir yanıt döndürür.

Microsoft Foundry'de izlemeyi kullanıyorsanız, araç çağrısının gerçekleştiğini onaylayın. Araç çağrısını doğrulama ve araç kullanımını denetleme hakkında yönergeler için Microsoft Foundry Agent Service'de araçları kullanmaya yönelik en iyi uygulamalar'a bakın.

Güvenlik ve veriyle ilgili dikkat edilmesi gerekenler

  • Araç bağımsız değişkenlerini ve araç çıkışlarını güvenilir olmayan giriş olarak değerlendirin. Değerleri kullanmadan önce doğrulayın ve temizleyin.
  • Araç çıkışında gizli bilgiler (API anahtarları, belirteçler, bağlantı dizeleri) geçirmeyin. Yalnızca modelin ihtiyaç duyduğu verileri döndürür.
  • tarafından DefaultAzureCredentialkullanılan kimliğe en az ayrıcalık uygulayın.
  • Açıkça amaçlamadığınız sürece yan etkilerden kaçının. Örneğin, işlev araçlarını güvenli işlemle kısıtlayın veya verileri değiştiren eylemler için açık kullanıcı onayı gerektirin.
  • Uzun süre çalışan işlemler için durum bilgisini hemen döndürün ve yoklama mekanizmasını uygulayın. 10 dakikalık çalıştırma süre sonu, tek tek işlev yürütmesine değil, geçen toplam süreye uygulanır.

Sorun giderme

Sorunu Olası neden Çözünürlük
Aracı işlev çağrısını döndürür, ancak nihai cevabı vermez. Araç çıktısı modüle geri döndürülmedi. İşlevi yürütün, ardından devam etmek için araç çıktısı ve responses.create kimliğiyle conversation çağrısını yapın.
İşlev çağrısı gerçekleşmez. Fonksiyon, ajan tanımında yok veya yanlış adlandırılmış. Fonksiyon aracının temsilciye eklendiğini onaylayın. Net, açıklayıcı adlar ve parametre açıklamaları kullanın.
Bağımsız değişkenler geçerli JSON değildir. Şema uyuşmazlığı veya modeli yanlış bilgi oluşturdu. JSON şemasının doğru türleri ve gerekli özellikleri kullandığını doğrulayın. Uygulamanızda ayrıştırma hatalarını düzgün bir şekilde işleyin.
Gerekli alanlar eksik. Şema gerekli özellikleri zorunlu kılmaz. Parametre şemanıza dizi ekleyin "required": [...] . Daha katı doğrulama için ayarlayın strict: true .
Araç çıkışları süresi dolduğu için başarısızlıkla sonuçlanır. Süre doldu (10 dakikalık süre sınırı). Araç çıkışlarını hemen döndür. Yavaş işlemler için bir durum döndürün ve ayrı olarak yoklayarak işlemi izleyin.
yanlış parametrelerle çağrılan işlev. Belirsiz işlev açıklaması. İşlev description alanını geliştirin. Örneklerle ayrıntılı parametre açıklamaları ekleyin.
Tek yanıtta birden çok işlev çağrısı. Model, gereken birden çok işlevi belirledi. Çıkış dizisindeki her işlev çağrısını işleyebilirsiniz. Tüm sonuçları tek responses.create bir çağrıda döndürür.
İşlev, Foundry portalında görünmüyor. Portal işlev çağrılarını yürütmez. SDK veya REST API aracılığıyla çağrı yapan test işlevi. Portal aracıları gösterir ancak işlevleri çağırmaz.

Kaynakları temizleme

Testi bitirdiğinizde, devam eden maliyetlerden kaçınmak için oluşturduğunuz kaynakları silin.

Aracıyı silin:

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

Konuşmayı silin:

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

İlgili içerik

  • Last updated on