Yapılandırılmış girişlerle çalışma zamanında aracı davranışını özelleştirme

Yapılandırılmış girişleri kullanarak aracının Foundry modelinin çalışma zamanında istekleri nasıl işlediğini özelleştirebilirsiniz. Yapılandırılmış girişler, handlebar şablonu söz dizimi ({{variableName}}) kullanılarak ajan içinde tanımlanan yer tutuculardır. Çalışma zamanında, her yapılandırma için ayrı aracı sürümleri oluşturmadan aracı yönergelerini, araç kaynak yapılandırmalarını ve yanıt parametrelerini dinamik olarak özelleştirmek için gerçek değerler sağlarsınız.

Bu makalede şunların nasıl yapılacağını öğreneceksiniz:

  • Aracı tanımında yapılandırılmış girişleri tanımlama
  • Ajan talimatlarında 'handlebar' şablonlarını kullanma
  • Kod Yorumlayıcı ve Dosya Arama gibi araç kaynaklarını dinamik olarak yapılandırma
  • Yanıtlar API'sini aracılığıyla çalışma zamanında yapılandırılmış giriş değerlerini geçirme

Önkoşullar

Yapılandırılmış girişler nedir?

Yapılandırılmış girişler, parametreli aracı tanımları oluşturmak için handlebar şablonu söz dizimlerini ({{variableName}}) kullanır. altında aracı tanımında structured_inputsgiriş şemaları tanımlarsınız; burada her girişin bir adı, açıklaması, türü ve isteğe bağlı varsayılan değeri vardır. Çalışma zamanında, aracı isteği işlemeden önce şablon yer tutucularının yerini alan gerçek değerleri sağlayın.

Yapılandırılmış girişler iki geçersiz kılma kategorisini destekler:

  • Yönerge geçersiz kılmaları: Aracı yönergelerini, yanıt düzeyi yönergelerini ve sistem veya geliştirici iletilerini parametreleştirin.
  • Araç kaynağı geçersiz kılmaları: Çalışma sırasında araç özelliklerini dinamik olarak yapılandırın, örneğin:
    • Dosya arama vektör veri deposu Kimlikleri
    • Kod yorumlayıcı dosya kimlikleri ve kapsayıcılar
    • Model Bağlam Protokolü (MCP) sunucu URL'leri ve üst bilgileri

ve file_idsgibi vector_store_ids dizi alanları için sistem çalışma zamanında boş dize değerlerini otomatik olarak kaldırır. Bu özellik esnek giriş sayılarına olanak tanır; gerekenden daha fazla şablon yuvası tanımlayın ve kullanılmayan yuvaları boş bırakın.

Desteklenen yapılandırılmış giriş özellikleri

Aşağıdaki tabloda, tanıtıcı çubuğu şablonlarını destekleyen aracı tanımı özellikleri listelenir:

Kategori Özellik Açıklama
Talimatlar Ajanda instructions Ajan seviyesi yönerge metni
Talimatlar Yanıt instructions Yanıtlar API isteğinde geçirilen yönergeler
Talimatlar Sistem/geliştirici iletisi content Giriş dizisindeki ileti içeriği
Dosya Arama vector_store_ids Vektör veri deposu kimlikleri dizisi (boş değerler çıkarılmış)
Kod Yorumlayıcı container (dize) Önceden yapılandırılmış bir kapsayıcı için kapsayıcı kimliği
Kod Yorumlayıcı container.file_ids (dizi) Otomatik kapsayıcıdaki dosya kimlikleri (boş değerler çıkarılmış)
MCP server_label MCP sunucusu etiketi
MCP server_url MCP sunucu uç noktasının URL'si
MCP headers (değerler) HTTP üst bilgi değerleri anahtar-değer çiftleri olarak
Azure Yapay Zeka Arama filter Arama dizinine uygulanan OData filtre ifadesi

Temsilci talimatlarıyla yapılandırılmış girdileri kullanma

Yapılandırılmış girişlerin en basit kullanımı aracı yönergelerini parametreleştirmektir. Handlebar şablonlarını instructions alanında tanımlayın ve çalışma zamanında değerleri sağlayın. Bu yaklaşım, birden çok aracı sürümü oluşturmadan farklı kullanıcılar veya bağlamlar için aracı davranışını kişiselleştirmenize olanak tanır.

Aşağıdaki örnekler, yönergeleri kullanıcıya özgü ayrıntıları içeren bir aracı oluşturur ve ardından yanıt oluştururken bu değerleri sağlar.

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition, StructuredInputDefinition
from azure.identity import DefaultAzureCredential

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

# Create clients to call Foundry API
project = AIProjectClient(endpoint=PROJECT_ENDPOINT, credential=DefaultAzureCredential())
openai = project.get_openai_client()

# Create agent with handlebar templates in instructions
agent = project.agents.create_version(
    agent_name="structured-input-agent",
    definition=PromptAgentDefinition(
        model="gpt-5-mini",
        instructions=(
            "You are a helpful assistant. "
            "The user's name is {{userName}} and their role is {{userRole}}. "
            "Greet them and confirm their details."
        ),
        structured_inputs={
            "userName": StructuredInputDefinition(
                description="The user's name", required=True, schema={"type": "string"},
            ),
            "userRole": StructuredInputDefinition(
                description="The user's role", required=True, schema={"type": "string"},
            ),
        },
    ),
)
print(f"Agent created: {agent.name}, version: {agent.version}")

# Create conversation and send request with runtime values
conversation = openai.conversations.create()
response = openai.responses.create(
    conversation=conversation.id,
    input="Hello! Can you confirm my details?",
    extra_body={
        "agent_reference": {"name": agent.name, "type": "agent_reference"},
        "structured_inputs": {"userName": "Alice Smith", "userRole": "Senior Developer"},
    },
)
print(response.output_text)

Beklenen çıkış

Agent created: structured-input-agent, version: 1
Hello Alice Smith! I can confirm your details: your name is Alice Smith and your role is Senior Developer. How can I help you today?

Aracı, isteği işlemeden önce yönergelerdeki {{userName}} ve {{userRole}} yer tutucularını "Alice Smith" ve "Kıdemli Geliştirici" ile değiştirir.

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

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

// Create project client to call Foundry API
AIProjectClient projectClient = new(
    endpoint: new Uri(projectEndpoint),
    tokenProvider: new DefaultAzureCredential());

// Create agent with handlebar templates in instructions
DeclarativeAgentDefinition agentDefinition = new(model: "gpt-5-mini")
{
    Instructions = "You are a helpful assistant. "
        + "The user's name is {{userName}} and their role is {{userRole}}. "
        + "Greet them and confirm their details.",
    StructuredInputs =
    {
        ["userName"] = new StructuredInputDefinition
            { Description = "The user's name", IsRequired = true },
        ["userRole"] = new StructuredInputDefinition
            { Description = "The user's role", IsRequired = true }
    }
};
AgentVersion agent = projectClient.AgentAdministrationClient.CreateAgentVersion(
    agentName: "structured-input-agent", options: new(agentDefinition));

// Send response with runtime structured input values
AgentReference agentRef = new(name: agent.Name, version: agent.Version);
ProjectResponsesClient responseClient =
    projectClient.ProjectOpenAIClient.GetProjectResponsesClientForAgent(agentRef);

CreateResponseOptions responseOptions = new()
{
    Input = [ResponseItem.CreateUserMessageItem("Hello! Can you confirm my details?")]
};
responseOptions.Patch.Set(
    "$.structured_inputs[\"userName\"]"u8,
    BinaryData.FromObjectAsJson("Alice Smith"));
responseOptions.Patch.Set(
    "$.structured_inputs[\"userRole\"]"u8,
    BinaryData.FromObjectAsJson("Senior Developer"));

ResponseResult response = responseClient.CreateResponse(responseOptions);
Console.WriteLine(response.GetOutputText());

// Clean up
projectClient.AgentAdministrationClient.DeleteAgentVersion(
    agentName: agent.Name, agentVersion: agent.Version);

Beklenen çıkış

Hello Alice Smith! I can confirm your details: your name is Alice Smith and your role is Senior Developer. How can I help you today?

Aracı StructuredInputs tanımındaki sözlük, şablon adlarını şemalarıyla eşler. Çalışma zamanında, Patch.Set üzerindeki CreateResponseOptions yöntemini kullanarak, $.structured_inputs JSON yolu aracılığıyla gerçek değerleri aktarın.

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

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

export async function main(): Promise<void> {
  // Create clients to call Foundry API
  const project = new AIProjectClient(PROJECT_ENDPOINT, new DefaultAzureCredential());
  const openai = project.getOpenAIClient();

  // Create agent with handlebar templates in instructions
  const agent = await project.agents.createVersion("structured-input-agent", {
    kind: "prompt",
    model: "gpt-5-mini",
    instructions:
      "You are a helpful assistant. " +
      "The user's name is {{userName}} and their role is {{userRole}}. " +
      "Greet them and confirm their details.",
    structured_inputs: {
      userName: { description: "The user's name", required: true },
      userRole: { description: "The user's role", required: true },
    },
  });
  console.log(`Agent created: ${agent.name}, version: ${agent.version}`);

  // Create conversation and send request with runtime values
  const conversation = await openai.conversations.create();
  const response = await openai.responses.create(
    {
      conversation: conversation.id,
      input: "Hello! Can you confirm my details?",
    },
    {
      body: {
        agent_reference: { name: agent.name, type: "agent_reference" },
        structured_inputs: { userName: "Alice Smith", userRole: "Senior Developer" },
      },
    },
  );
  console.log(response.output_text);

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

main().catch(console.error);

Beklenen çıkış

Agent created: structured-input-agent, version: 1
Hello Alice Smith! I can confirm your details: your name is Alice Smith and your role is Senior Developer. How can I help you today?

Aracı tanımı, şablon şemalarını bildirmek için kullanır structured_inputs . Çalışma zamanında, body parametresindeki gerçek değerleri agent_reference ile birlikte geçirin.

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

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

import com.azure.ai.agents.AgentsClient;
import com.azure.ai.agents.AgentsClientBuilder;
import com.azure.ai.agents.AgentsServiceVersion;
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.PromptAgentDefinition;
import com.azure.ai.agents.models.StructuredInputDefinition;
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.LinkedHashMap;
import java.util.Map;

public class StructuredInputInstructionsExample {
    public static void main(String[] args) {
        // Format: "https://resource_name.ai.azure.com/api/projects/project_name"
        String projectEndpoint = "your_project_endpoint";

        AgentsClientBuilder builder = new AgentsClientBuilder()
            .credential(new DefaultAzureCredentialBuilder().build())
            .endpoint(projectEndpoint)
            .serviceVersion(AgentsServiceVersion.getLatest());

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

        // Define structured input schemas
        Map<String, StructuredInputDefinition> inputDefs = new LinkedHashMap<>();
        inputDefs.put("userName",
            new StructuredInputDefinition().setDescription("The user's name").setRequired(true));
        inputDefs.put("userRole",
            new StructuredInputDefinition().setDescription("The user's role").setRequired(true));

        // Create agent with handlebar templates in instructions
        AgentVersionDetails agent = agentsClient.createAgentVersion(
            "structured-input-agent",
            new PromptAgentDefinition("gpt-5-mini")
                .setInstructions("You are a helpful assistant. "
                    + "The user's name is {{userName}} and their role is {{userRole}}. "
                    + "Greet them and confirm their details.")
                .setStructuredInputs(inputDefs));

        // Supply structured input values at runtime
        Map<String, BinaryData> inputValues = new LinkedHashMap<>();
        inputValues.put("userName", BinaryData.fromObject("Alice Smith"));
        inputValues.put("userRole", BinaryData.fromObject("Senior Developer"));

        Response response = responsesClient.createAzureResponse(
            new AzureCreateResponseOptions()
                .setAgentReference(
                    new AgentReference(agent.getName()).setVersion(agent.getVersion()))
                .setStructuredInputs(inputValues),
            ResponseCreateParams.builder()
                .input("Hello! Can you confirm my details?"));

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

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

Beklenen çıkış

Response: Hello Alice Smith! I can confirm your details: your name is Alice Smith and your role is Senior Developer. How can I help you today?

Java SDK aracı şeması için StructuredInputDefinition ve Map<String, BinaryData> aracılığıyla geçirilen çalışma zamanı değerleri için AzureCreateResponseOptions kullanır.

Yapılandırılmış girişlerle ajan oluşturma

curl -X POST "$FOUNDRY_PROJECT_ENDPOINT/agents?api-version=v1" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -d '{
    "name": "structured-input-agent",
    "definition": {
      "kind": "prompt",
      "model": "<MODEL_DEPLOYMENT>",
      "instructions": "You are a helpful assistant. The user'\''s name is {{userName}} and their role is {{userRole}}. Greet them and confirm their details.",
      "structured_inputs": {
        "userName": {
          "type": "string",
          "description": "The user'\''s name",
          "default_value": "Unknown"
        },
        "userRole": {
          "type": "string",
          "description": "The user'\''s role",
          "default_value": "User"
        }
      }
    }
  }'

Yapılandırılmış giriş değerleriyle yanıt oluşturma

curl -X POST "$FOUNDRY_PROJECT_ENDPOINT/openai/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -d '{
    "agent_reference": {
      "type": "agent_reference",
      "name": "structured-input-agent"
    },
    "input": [
      {
        "type": "message",
        "role": "user",
        "content": "Hello! Can you confirm my details?"
      }
    ],
    "structured_inputs": {
      "userName": "Alice Smith",
      "userRole": "Senior Developer"
    }
  }'

Aracı tanımının structured_inputs nesnesi, şemaları açıklamalarla ve varsayılan değerlerle bildirir. Yanıt isteğinde structured_inputs ve {{userName}} şablonlarının yerini {{userRole}} alan gerçek çalışma zamanı değerleri sağlanır.

Kod Yorumlayıcı ile yapılandırılmış girişleri kullanma

Yapılandırılmış girişleri kullanarak, Kod Yorumlayıcı aracının çalışma zamanında hangi dosyaları ve kapsayıcıları kullandığını dinamik olarak yapılandırabilirsiniz. Aracın file_ids veya container özelliklerinde handlebar şablonları tanımlayın ve yanıt oluştururken gerçek kimlikleri sağlayın.

from io import BytesIO
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    PromptAgentDefinition,
    CodeInterpreterTool,
    AutoCodeInterpreterToolParam,
    StructuredInputDefinition,
)
from azure.identity import DefaultAzureCredential

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

# Create clients to call Foundry API
project = AIProjectClient(endpoint=PROJECT_ENDPOINT, credential=DefaultAzureCredential())
openai = project.get_openai_client()

# Upload a CSV file for the code interpreter
csv_file = BytesIO(b"x\n1\n2\n3\n")
csv_file.name = "numbers.csv"
uploaded = openai.files.create(purpose="assistants", file=csv_file)
print(f"File uploaded (id: {uploaded.id})")

# Create agent with a template placeholder for the file ID
tool = CodeInterpreterTool(
    container=AutoCodeInterpreterToolParam(file_ids=["{{analysis_file_id}}"])
)
agent = project.agents.create_version(
    agent_name="code-interp-structured",
    definition=PromptAgentDefinition(
        model="gpt-5-mini",
        instructions="You are a helpful data analyst.",
        tools=[tool],
        structured_inputs={
            "analysis_file_id": StructuredInputDefinition(
                description="File ID for the code interpreter",
                required=True,
                schema={"type": "string"},
            ),
        },
    ),
)

# Supply the actual file ID at runtime
conversation = openai.conversations.create()
response = openai.responses.create(
    conversation=conversation.id,
    input="Read numbers.csv and return the sum of x.",
    extra_body={
        "agent_reference": {"name": agent.name, "type": "agent_reference"},
        "structured_inputs": {"analysis_file_id": uploaded.id},
    },
    tool_choice="required",
)
print(response.output_text)

Beklenen çıkış

File uploaded (id: <file-id>)
The sum of x in numbers.csv is 6.

Aracın {{analysis_file_id}}file_ids dizisindeki yer tutucu, çalışma zamanında gerçek dosya kimliğiyle değiştirilir. Bu yaklaşımı kullanarak, her istek için farklı dosyalarla aynı aracı tanımını yeniden kullanabilirsiniz.

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

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

// Create project client to call Foundry API
AIProjectClient projectClient = new(
    endpoint: new Uri(projectEndpoint),
    tokenProvider: new DefaultAzureCredential());

// Create agent with a structured input placeholder for the file ID
DeclarativeAgentDefinition agentDefinition = new(model: "gpt-5-mini")
{
    Instructions = "You are a helpful data analyst.",
    Tools = {
        ResponseTool.CreateCodeInterpreterTool(
            new CodeInterpreterToolContainer(
                CodeInterpreterToolContainerConfiguration
                    .CreateAutomaticContainerConfiguration(
                        fileIds: ["{{analysis_file_id}}"])))
    },
    StructuredInputs =
    {
        ["analysis_file_id"] = new StructuredInputDefinition
            { Description = "File ID for the code interpreter", IsRequired = true }
    }
};
AgentVersion agent = projectClient.AgentAdministrationClient.CreateAgentVersion(
    agentName: "code-interp-structured", options: new(agentDefinition));

// Supply the actual file ID at runtime
AgentReference agentRef = new(name: agent.Name, version: agent.Version);
ProjectResponsesClient responseClient =
    projectClient.ProjectOpenAIClient.GetProjectResponsesClientForAgent(agentRef);

CreateResponseOptions responseOptions = new()
{
    Input = [ResponseItem.CreateUserMessageItem(
        "Read numbers.csv and return the sum of x.")]
};
responseOptions.Patch.Set(
    "$.structured_inputs[\"analysis_file_id\"]"u8,
    BinaryData.FromObjectAsJson("<uploaded-file-id>"));

ResponseResult response = responseClient.CreateResponse(responseOptions);
Console.WriteLine(response.GetOutputText());

// Clean up
projectClient.AgentAdministrationClient.DeleteAgentVersion(
    agentName: agent.Name, agentVersion: agent.Version);

Beklenen çıkış

The sum of x in numbers.csv is 6.

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

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

export async function main(): Promise<void> {
  const project = new AIProjectClient(PROJECT_ENDPOINT, new DefaultAzureCredential());
  const openai = project.getOpenAIClient();

  // Upload a file for code interpreter
  const file = new File(["x\n1\n2\n3\n"], "numbers.csv");
  const uploaded = await openai.files.create({ file, purpose: "assistants" });
  console.log(`File uploaded (id: ${uploaded.id})`);

  // Create agent with a template placeholder for the file ID
  const agent = await project.agents.createVersion("code-interp-structured", {
    kind: "prompt",
    model: "gpt-5-mini",
    instructions: "You are a helpful data analyst.",
    tools: [
      {
        type: "code_interpreter",
        container: { type: "auto", file_ids: ["{{analysis_file_id}}"] },
      },
    ],
    structured_inputs: {
      analysis_file_id: {
        description: "File ID for the code interpreter",
        required: true,
      },
    },
  });

  // Supply the actual file ID at runtime
  const conversation = await openai.conversations.create();
  const response = await openai.responses.create(
    {
      conversation: conversation.id,
      input: "Read numbers.csv and return the sum of x.",
      tool_choice: "required",
    },
    {
      body: {
        agent_reference: { name: agent.name, type: "agent_reference" },
        structured_inputs: { analysis_file_id: uploaded.id },
      },
    },
  );
  console.log(response.output_text);

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

main().catch(console.error);

Beklenen çıkış

File uploaded (id: <file-id>)
The sum of x in numbers.csv is 6.

import com.azure.ai.agents.AgentsClient;
import com.azure.ai.agents.AgentsClientBuilder;
import com.azure.ai.agents.AgentsServiceVersion;
import com.azure.ai.agents.ResponsesClient;
import com.azure.ai.agents.models.*;
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.LinkedHashMap;
import java.util.Map;

public class CodeInterpreterStructuredInputExample {
    public static void main(String[] args) {
        // Format: "https://resource_name.ai.azure.com/api/projects/project_name"
        String projectEndpoint = "your_project_endpoint";

        AgentsClientBuilder builder = new AgentsClientBuilder()
            .credential(new DefaultAzureCredentialBuilder().build())
            .endpoint(projectEndpoint)
            .serviceVersion(AgentsServiceVersion.getLatest());

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

        // Create code interpreter tool with a template placeholder
        CodeInterpreterTool tool = new CodeInterpreterTool()
            .setContainer(new AutoCodeInterpreterToolParameter()
                .setFileIds(Arrays.asList("{{analysis_file_id}}")));

        Map<String, StructuredInputDefinition> inputDefs = new LinkedHashMap<>();
        inputDefs.put("analysis_file_id",
            new StructuredInputDefinition()
                .setDescription("File ID for the code interpreter")
                .setRequired(true));

        AgentVersionDetails agent = agentsClient.createAgentVersion(
            "code-interp-structured",
            new PromptAgentDefinition("gpt-5-mini")
                .setInstructions("You are a helpful data analyst.")
                .setTools(Arrays.asList(tool))
                .setStructuredInputs(inputDefs));

        // Supply the actual file ID at runtime
        Map<String, BinaryData> inputValues = new LinkedHashMap<>();
        inputValues.put("analysis_file_id",
            BinaryData.fromObject("<uploaded-file-id>"));

        Response response = responsesClient.createAzureResponse(
            new AzureCreateResponseOptions()
                .setAgentReference(
                    new AgentReference(agent.getName()).setVersion(agent.getVersion()))
                .setStructuredInputs(inputValues),
            ResponseCreateParams.builder()
                .input("Read numbers.csv and return the sum of x."));

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

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

Beklenen çıkış

Response: The sum of x in numbers.csv is 6.

Dinamik Kod Yorumlayıcı dosyalarını kullanarak aracı oluşturun

curl -X POST "$FOUNDRY_PROJECT_ENDPOINT/agents?api-version=v1" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -d '{
    "name": "code-interp-structured",
    "definition": {
      "kind": "prompt",
      "model": "<MODEL_DEPLOYMENT>",
      "instructions": "You are a helpful data analyst.",
      "tools": [
        {
          "type": "code_interpreter",
          "container": {
            "type": "auto",
            "file_ids": ["{{analysis_file_id}}"]
          }
        }
      ],
      "structured_inputs": {
        "analysis_file_id": {
          "description": "File ID for the code interpreter",
          "required": true,
          "schema": {"type": "string"}
        }
      }
    }
  }'

Dosya kimliğiyle yanıt oluşturma

curl -X POST "$FOUNDRY_PROJECT_ENDPOINT/openai/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -d '{
    "agent_reference": {
      "type": "agent_reference",
      "name": "code-interp-structured"
    },
    "input": [
      {
        "type": "message",
        "role": "user",
        "content": "Read numbers.csv and return the sum of x."
      }
    ],
    "structured_inputs": {
      "analysis_file_id": "<FILE_ID>"
    },
    "tool_choice": "required"
  }'

içindeki {{analysis_file_id}}file_ids şablonu çalışma zamanında gerçek dosya kimliğiyle değiştirilir. Birden çok dosya kimliği yer tutucusu tanımlayabilir ve kullanılmayanları boş bırakabilirsiniz. Boş değerler diziden otomatik olarak kaldırılır.

Yapılandırılmış girişleri kullanarak, çalışma zamanında Dosya Arama aracı sorgularını depolayan vektörleri dinamik olarak yapılandırabilirsiniz. Dizide vector_store_ids şablon yer tutucuları tanımlayın ve yanıt oluştururken gerçek vektör deposu kimliklerini girin.

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    PromptAgentDefinition,
    FileSearchTool,
    StructuredInputDefinition,
)
from azure.identity import DefaultAzureCredential

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

# Create clients to call Foundry API
project = AIProjectClient(endpoint=PROJECT_ENDPOINT, credential=DefaultAzureCredential())
openai = project.get_openai_client()

# Create a vector store and upload a file
vector_store = openai.vector_stores.create(name="ProductInfoStore")
with open("product_info.md", "rb") as f:
    file = openai.vector_stores.files.upload_and_poll(
        vector_store_id=vector_store.id, file=f
    )
print(f"Vector store created (id: {vector_store.id})")

# Create agent with a template placeholder for vector store ID
tool = FileSearchTool(vector_store_ids=["{{vector_store_id}}"])
agent = project.agents.create_version(
    agent_name="file-search-structured",
    definition=PromptAgentDefinition(
        model="gpt-5-mini",
        instructions="You are a helpful assistant that searches product information.",
        tools=[tool],
        structured_inputs={
            "vector_store_id": StructuredInputDefinition(
                description="Vector store ID for file search",
                required=True,
                schema={"type": "string"},
            ),
        },
    ),
)

# Supply the actual vector store ID at runtime
conversation = openai.conversations.create()
response = openai.responses.create(
    conversation=conversation.id,
    input="Tell me about Contoso products",
    extra_body={
        "agent_reference": {"name": agent.name, "type": "agent_reference"},
        "structured_inputs": {"vector_store_id": vector_store.id},
    },
)
print(response.output_text)

Beklenen çıkış

Vector store created (id: <vector-store-id>)
Based on the product information, Contoso offers several product lines including...

Çalışma zamanında "{{vector_store_id}}" yer tutucu, gerçek vektör deposu kimliğiyle değiştirilir. Katmanlı veya bağlama özgü bilgi bankalarını etkinleştirmek için birden çok vektör deposu yer tutucusu tanımlayabilirsiniz.

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

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

AIProjectClient projectClient = new(
    endpoint: new Uri(projectEndpoint),
    tokenProvider: new DefaultAzureCredential());

// Create agent with a template placeholder for vector store ID
DeclarativeAgentDefinition agentDefinition = new(model: "gpt-5-mini")
{
    Instructions = "You are a helpful assistant that searches product information.",
    Tools = {
        ResponseTool.CreateFileSearchTool(
            vectorStoreIds: ["{{vector_store_id}}"])
    },
    StructuredInputs =
    {
        ["vector_store_id"] = new StructuredInputDefinition
            { Description = "Vector store ID for file search", IsRequired = true }
    }
};
AgentVersion agent = projectClient.AgentAdministrationClient.CreateAgentVersion(
    agentName: "file-search-structured", options: new(agentDefinition));

// Supply the actual vector store ID at runtime
AgentReference agentRef = new(name: agent.Name, version: agent.Version);
ProjectResponsesClient responseClient =
    projectClient.ProjectOpenAIClient.GetProjectResponsesClientForAgent(agentRef);

CreateResponseOptions responseOptions = new()
{
    Input = [ResponseItem.CreateUserMessageItem("Tell me about Contoso products")]
};
responseOptions.Patch.Set(
    "$.structured_inputs[\"vector_store_id\"]"u8,
    BinaryData.FromObjectAsJson("<vector-store-id>"));

ResponseResult response = responseClient.CreateResponse(responseOptions);
Console.WriteLine(response.GetOutputText());

// Clean up
projectClient.AgentAdministrationClient.DeleteAgentVersion(
    agentName: agent.Name, agentVersion: agent.Version);

Beklenen çıkış

Based on the product information, Contoso offers several product lines including...

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

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

export async function main(): Promise<void> {
  const project = new AIProjectClient(PROJECT_ENDPOINT, new DefaultAzureCredential());
  const openai = project.getOpenAIClient();

  // Create a vector store (assumes file already uploaded)
  const vectorStore = await openai.vectorStores.create({ name: "ProductInfoStore" });
  console.log(`Vector store created (id: ${vectorStore.id})`);

  // Create agent with a template placeholder for vector store ID
  const agent = await project.agents.createVersion("file-search-structured", {
    kind: "prompt",
    model: "gpt-5-mini",
    instructions: "You are a helpful assistant that searches product information.",
    tools: [
      {
        type: "file_search",
        vector_store_ids: ["{{vector_store_id}}"],
      },
    ],
    structured_inputs: {
      vector_store_id: {
        description: "Vector store ID for file search",
        required: true,
      },
    },
  });

  // Supply the actual vector store ID at runtime
  const conversation = await openai.conversations.create();
  const response = await openai.responses.create(
    {
      conversation: conversation.id,
      input: "Tell me about Contoso products",
    },
    {
      body: {
        agent_reference: { name: agent.name, type: "agent_reference" },
        structured_inputs: { vector_store_id: vectorStore.id },
      },
    },
  );
  console.log(response.output_text);

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

main().catch(console.error);

Beklenen çıkış

Vector store created (id: <vector-store-id>)
Based on the product information, Contoso offers several product lines including...

import com.azure.ai.agents.AgentsClient;
import com.azure.ai.agents.AgentsClientBuilder;
import com.azure.ai.agents.AgentsServiceVersion;
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.FileSearchTool;
import com.azure.ai.agents.models.PromptAgentDefinition;
import com.azure.ai.agents.models.StructuredInputDefinition;
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.LinkedHashMap;
import java.util.Map;

public class FileSearchStructuredInputExample {
    public static void main(String[] args) {
        // Format: "https://resource_name.ai.azure.com/api/projects/project_name"
        String projectEndpoint = "your_project_endpoint";

        AgentsClientBuilder builder = new AgentsClientBuilder()
            .credential(new DefaultAzureCredentialBuilder().build())
            .endpoint(projectEndpoint)
            .serviceVersion(AgentsServiceVersion.getLatest());

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

        // Create agent with a template placeholder for vector store ID
        FileSearchTool tool = new FileSearchTool()
            .setVectorStoreIds(Arrays.asList("{{vector_store_id}}"));

        Map<String, StructuredInputDefinition> inputDefs = new LinkedHashMap<>();
        inputDefs.put("vector_store_id",
            new StructuredInputDefinition()
                .setDescription("Vector store ID for file search")
                .setRequired(true));

        AgentVersionDetails agent = agentsClient.createAgentVersion(
            "file-search-structured",
            new PromptAgentDefinition("gpt-5-mini")
                .setInstructions(
                    "You are a helpful assistant that searches product information.")
                .setTools(Arrays.asList(tool))
                .setStructuredInputs(inputDefs));

        // Supply the actual vector store ID at runtime
        Map<String, BinaryData> inputValues = new LinkedHashMap<>();
        inputValues.put("vector_store_id",
            BinaryData.fromObject("<vector-store-id>"));

        Response response = responsesClient.createAzureResponse(
            new AzureCreateResponseOptions()
                .setAgentReference(
                    new AgentReference(agent.getName()).setVersion(agent.getVersion()))
                .setStructuredInputs(inputValues),
            ResponseCreateParams.builder()
                .input("Tell me about Contoso products"));

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

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

Beklenen çıkış

Response: Based on the product information, Contoso offers several product lines including...

Dinamik dosya arama vektör depoları ile aracı oluşturma

curl -X POST "$FOUNDRY_PROJECT_ENDPOINT/agents?api-version=v1" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -d '{
    "name": "file-search-structured",
    "definition": {
      "kind": "prompt",
      "model": "<MODEL_DEPLOYMENT>",
      "instructions": "You are a helpful assistant that searches product information.",
      "tools": [
        {
          "type": "file_search",
          "vector_store_ids": [
            "vs_base_kb",
            "{{tier_specific_kb}}"
          ]
        }
      ],
      "structured_inputs": {
        "tier_specific_kb": {
          "description": "Vector store ID for customer tier",
          "required": true,
          "schema": {"type": "string"}
        }
      }
    }
  }'

Vektör deposu kimliği ile bir yanıt oluşturun.

curl -X POST "$FOUNDRY_PROJECT_ENDPOINT/openai/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -d '{
    "agent_reference": {
      "type": "agent_reference",
      "name": "file-search-structured"
    },
    "input": [
      {
        "type": "message",
        "role": "user",
        "content": "Tell me about Contoso products"
      }
    ],
    "structured_inputs": {
      "tier_specific_kb": "vs_premium_kb_2024"
    }
  }'

Bu örnek, statik vektör depolarını (vs_base_kb) dinamik bir depoyla ({{tier_specific_kb}} ) birleştirir. Şablon yer tutucusu çalışma zamanında değiştirilir ve işlem dizideki boş dize değerlerini otomatik olarak kaldırır.

Yapılandırılmış girişleri kullanarak, çalışma zamanında Azure Yapay Zeka Arama aracının dizin filter dinamik olarak yapılandırabilirsiniz. OData filtre ifadesinin içinde bir handlebar şablonu tanımlayın ve yanıt oluştururken gerçek filtre değerini sağlayın. Bu düzen, tek bir aracı tanımının, filtre değeri başına ayrı bir aracı sürümü oluşturmadan sorguların kapsamının bir dizinin farklı alt kümeleri olarak tanımlanması gereken kullanıcılara hizmet vermesine olanak tanır.

import os
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    AISearchIndexResource,
    AzureAISearchQueryType,
    AzureAISearchTool,
    AzureAISearchToolResource,
    PromptAgentDefinition,
    StructuredInputDefinition,
)
from azure.identity import DefaultAzureCredential

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

# Create clients to call Foundry API
project = AIProjectClient(endpoint=PROJECT_ENDPOINT, credential=DefaultAzureCredential())
openai = project.get_openai_client()

# Create the AI Search tool with a handlebar template inside the filter expression
tool = AzureAISearchTool(
    azure_ai_search=AzureAISearchToolResource(
        indexes=[
            AISearchIndexResource(
                project_connection_id=os.environ["AI_SEARCH_PROJECT_CONNECTION_ID"],
                index_name=os.environ["AI_SEARCH_INDEX_NAME"],
                query_type=AzureAISearchQueryType.SIMPLE,
                filter="search.ismatchscoring('{{userFilter}}')",
            ),
        ]
    )
)

# Create the agent with a structured input that supplies the filter value
agent = project.agents.create_version(
    agent_name="aisearch-agent-structured-input",
    definition=PromptAgentDefinition(
        model="gpt-5-mini",
        instructions=(
            "You are a helpful assistant. You must always provide citations for "
            "answers using the tool and render them as: "
            "`\u3010message_idx:search_idx\u2020source\u3011`."
        ),
        tools=[tool],
        structured_inputs={
            "userFilter": StructuredInputDefinition(
                description="The user's search filter",
                required=True,
                schema={"type": "string"},
            ),
        },
    ),
)
print(f"Agent created (id: {agent.id}, name: {agent.name}, version: {agent.version})")

# Supply the actual filter value at runtime
stream_response = openai.responses.create(
    stream=True,
    tool_choice="required",
    input="What outdoor gear do you have?",
    extra_body={
        "agent_reference": {"name": agent.name, "type": "agent_reference"},
        "structured_inputs": {"userFilter": "boots"},
    },
)

for event in stream_response:
    if event.type == "response.completed":
        print(f"Agent response: {event.response.output_text}")

Beklenen çıkış

Agent created (id: <agent-id>, name: aisearch-agent-structured-input, version: 1)
Agent response: Based on the index, the available outdoor boots include ...

{{userFilter}} ifadesinin içindeki filter yer tutucusu, arama çalıştırılmadan önce çalışma zamanı değeri boots ile değiştirilir. Yeni bir aracı sürümü oluşturmadan sonuçların kapsamını belirlemeye yönelik her istek için farklı filtre değerleri sağlayabilirsiniz.

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

// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
var projectEndpoint = "your_project_endpoint";
var searchConnectionName = "my-search-connection";
var searchIndexName = "my-search-index";

AIProjectClient projectClient = new(
    endpoint: new Uri(projectEndpoint),
    tokenProvider: new DefaultAzureCredential());

// Resolve the project connection ID from the connection name
AIProjectConnection aiSearchConnection =
    projectClient.Connections.GetConnection(connectionName: searchConnectionName);

// Define the search index with a handlebar template inside the filter expression
AzureAISearchToolIndex index = new()
{
    ProjectConnectionId = aiSearchConnection.Id,
    IndexName = searchIndexName,
    QueryType = AzureAISearchQueryType.Simple,
    Filter = "search.ismatchscoring('{{userFilter}}')"
};

// Create the agent with a structured input that supplies the filter value
DeclarativeAgentDefinition agentDefinition = new(model: "gpt-5-mini")
{
    Instructions = "You are a helpful assistant. You must always provide citations for "
        + "answers using the tool and render them as: "
        + "`\u3010message_idx:search_idx\u2020source\u3011`.",
    Tools = { new AzureAISearchTool(new AzureAISearchToolOptions(indexes: [index])) },
    StructuredInputs =
    {
        ["userFilter"] = new StructuredInputDefinition
            { Description = "The user's search filter", IsRequired = true }
    }
};
AgentVersion agent = projectClient.AgentAdministrationClient.CreateAgentVersion(
    agentName: "aisearch-agent-structured-input",
    options: new(agentDefinition));

// Supply the actual filter value at runtime
AgentReference agentRef = new(name: agent.Name, version: agent.Version);
ProjectResponsesClient responseClient =
    projectClient.ProjectOpenAIClient.GetProjectResponsesClientForAgent(agentRef);

CreateResponseOptions responseOptions = new()
{
    Input = [ResponseItem.CreateUserMessageItem("What outdoor gear do you have?")]
};
responseOptions.Patch.Set(
    "$.structured_inputs[\"userFilter\"]"u8,
    BinaryData.FromObjectAsJson("boots"));

ResponseResult response = responseClient.CreateResponse(responseOptions);
Console.WriteLine(response.GetOutputText());

// Clean up
projectClient.AgentAdministrationClient.DeleteAgentVersion(
    agentName: agent.Name, agentVersion: agent.Version);

Beklenen çıkış

Based on the index, the available outdoor boots include ...

Filter üzerindeki AzureAISearchToolIndex özelliği çalışma zamanında çözümlenebilen handlebar şablonlarını kabul eder. Filtre değerini Patch.Set JSON yolu aracılığıyla sağlamak için CreateResponseOptions üzerinde $.structured_inputs 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 PROJECT_ENDPOINT = "your_project_endpoint";
const SEARCH_CONNECTION_NAME = "my-search-connection";
const SEARCH_INDEX_NAME = "my-search-index";

export async function main(): Promise<void> {
  const project = new AIProjectClient(PROJECT_ENDPOINT, new DefaultAzureCredential());
  const openai = project.getOpenAIClient();

  // Resolve the project connection ID from the connection name
  const aiSearchConnection = await project.connections.get(SEARCH_CONNECTION_NAME);

  // Create the agent with a handlebar template inside the filter expression
  const agent = await project.agents.createVersion("aisearch-agent-structured-input", {
    kind: "prompt",
    model: "gpt-5-mini",
    instructions:
      "You are a helpful assistant. You must always provide citations for " +
      "answers using the tool and render them as: `[message_idx:search_idx†source]`.",
    tools: [
      {
        type: "azure_ai_search",
        azure_ai_search: {
          indexes: [
            {
              project_connection_id: aiSearchConnection.id,
              index_name: SEARCH_INDEX_NAME,
              query_type: "simple",
              filter: "search.ismatchscoring('{{userFilter}}')",
            },
          ],
        },
      },
    ],
    structured_inputs: {
      userFilter: { description: "The user's search filter", required: true },
    },
  });
  console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);

  // Supply the actual filter value at runtime
  const response = await openai.responses.create(
    {
      input: "What outdoor gear do you have?",
      tool_choice: "required",
    },
    {
      body: {
        agent_reference: { name: agent.name, type: "agent_reference" },
        structured_inputs: { userFilter: "boots" },
      },
    },
  );
  console.log(response.output_text);

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

main().catch(console.error);

Beklenen çıkış

Agent created (id: <agent-id>, name: aisearch-agent-structured-input, version: 1)
Based on the index, the available outdoor boots include ...

import com.azure.ai.agents.AgentsClient;
import com.azure.ai.agents.AgentsClientBuilder;
import com.azure.ai.agents.AgentsServiceVersion;
import com.azure.ai.agents.ResponsesClient;
import com.azure.ai.agents.models.AISearchIndexResource;
import com.azure.ai.agents.models.AgentReference;
import com.azure.ai.agents.models.AgentVersionDetails;
import com.azure.ai.agents.models.AzureAISearchQueryType;
import com.azure.ai.agents.models.AzureAISearchTool;
import com.azure.ai.agents.models.AzureAISearchToolResource;
import com.azure.ai.agents.models.AzureCreateResponseOptions;
import com.azure.ai.agents.models.PromptAgentDefinition;
import com.azure.ai.agents.models.StructuredInputDefinition;
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.LinkedHashMap;
import java.util.Map;

public class AzureAISearchStructuredInputExample {
    public static void main(String[] args) {
        // Format: "https://resource_name.ai.azure.com/api/projects/project_name"
        String projectEndpoint = "your_project_endpoint";
        String searchConnectionId = "your-search-connection-id";
        String searchIndexName = "my-search-index";

        AgentsClientBuilder builder = new AgentsClientBuilder()
            .credential(new DefaultAzureCredentialBuilder().build())
            .endpoint(projectEndpoint)
            .serviceVersion(AgentsServiceVersion.getLatest());

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

        // Create the AI Search tool with a handlebar template inside the filter expression
        AzureAISearchTool tool = new AzureAISearchTool(
            new AzureAISearchToolResource(Arrays.asList(
                new AISearchIndexResource()
                    .setProjectConnectionId(searchConnectionId)
                    .setIndexName(searchIndexName)
                    .setQueryType(AzureAISearchQueryType.SIMPLE)
                    .setFilter("search.ismatchscoring('{{userFilter}}')")
            ))
        );

        Map<String, StructuredInputDefinition> inputDefs = new LinkedHashMap<>();
        inputDefs.put("userFilter",
            new StructuredInputDefinition()
                .setDescription("The user's search filter")
                .setRequired(true));

        AgentVersionDetails agent = agentsClient.createAgentVersion(
            "aisearch-agent-structured-input",
            new PromptAgentDefinition("gpt-5-mini")
                .setInstructions("You are a helpful assistant. Always provide citations.")
                .setTools(Arrays.asList(tool))
                .setStructuredInputs(inputDefs));

        // Supply the actual filter value at runtime
        Map<String, BinaryData> inputValues = new LinkedHashMap<>();
        inputValues.put("userFilter", BinaryData.fromObject("boots"));

        Response response = responsesClient.createAzureResponse(
            new AzureCreateResponseOptions()
                .setAgentReference(
                    new AgentReference(agent.getName()).setVersion(agent.getVersion()))
                .setStructuredInputs(inputValues),
            ResponseCreateParams.builder()
                .input("What outdoor gear do you have?"));

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

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

Beklenen çıkış

Response: Based on the index, the available outdoor boots include ...

Dinamik Azure Yapay Zeka Arama filtresiyle aracı oluşturma

curl -X POST "$FOUNDRY_PROJECT_ENDPOINT/agents?api-version=v1" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -d '{
    "name": "aisearch-agent-structured-input",
    "definition": {
      "kind": "prompt",
      "model": "<MODEL_DEPLOYMENT>",
      "instructions": "You are a helpful assistant. Always provide citations.",
      "tools": [
        {
          "type": "azure_ai_search",
          "azure_ai_search": {
            "indexes": [
              {
                "project_connection_id": "$AZURE_AI_SEARCH_CONNECTION_ID",
                "index_name": "$AI_SEARCH_INDEX_NAME",
                "query_type": "simple",
                "filter": "search.ismatchscoring('\''{{userFilter}}'\'')"
              }
            ]
          }
        }
      ],
      "structured_inputs": {
        "userFilter": {
          "description": "The user's search filter",
          "required": true,
          "schema": {"type": "string"}
        }
      }
    }
  }'

Filtre değeriyle yanıt oluşturma

curl -X POST "$FOUNDRY_PROJECT_ENDPOINT/openai/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -d '{
    "agent_reference": {
      "type": "agent_reference",
      "name": "aisearch-agent-structured-input"
    },
    "input": [
      {
        "type": "message",
        "role": "user",
        "content": "What outdoor gear do you have?"
      }
    ],
    "structured_inputs": {
      "userFilter": "boots"
    },
    "tool_choice": "required"
  }'

{{userFilter}} ifadesinin içindeki filter şablonu, çalışma zamanında boots ile değiştirilir. '\'' Create-agent gövdesindeki sıra, tek tırnaklı bir dize içindeki değişmez tek tırnak için standart Bash kaçışıdır. Kabuğunuz alıntıları farklı şekilde işlerse, bunun yerine bir dosyadan JSON gövdesini sağlayın.

YAPıLANDıRıLMıŞ girişleri MCP sunucularıyla kullanma

Yapılandırılmış girişleri kullanarak mcp sunucu bağlantılarını çalışma zamanında dinamik olarak yapılandırabilirsiniz. Sunucu URL'sini, kimlik doğrulama üst bilgilerini ve sunucu etiketini ayarlayabilirsiniz. Bu yaklaşımı kullanarak, bağlama bağlı olarak tek bir aracı tanımı farklı MCP sunucularına bağlanabilir.

Aşağıdaki JSON, Aracı Sürümü Oluşturma işlemiPOST /agents?api-version=v1 ( ) için istek gövdesini gösterir. Aracı tanımı, handlebar şablonu yer tutucularına sahip MCP araç özelliklerini içerir:

{
  "name": "mcp-dynamic-agent",
  "definition": {
    "kind": "prompt",
    "model": "gpt-4o",
    "instructions": "You are a development assistant for {{project_name}}.",
    "tools": [
      {
        "type": "mcp",
        "server_label": "{{server_label}}",
        "server_url": "{{server_url}}",
        "require_approval": "never",
        "headers": {
          "Authorization": "{{auth_token}}",
          "X-Project-ID": "{{project_id}}"
        }
      }
    ],
    "structured_inputs": {
      "project_name": {
        "description": "Project name",
        "required": true
      },
      "server_label": {
        "description": "MCP server label",
        "required": true,
        "schema": {"type": "string"}
      },
      "server_url": {
        "description": "MCP server URL",
        "required": true,
        "schema": {"type": "string"}
      },
      "auth_token": {
        "description": "Authentication token",
        "required": true,
        "schema": {"type": "string"}
      },
      "project_id": {
        "description": "Project identifier",
        "required": true,
        "schema": {"type": "string"}
      }
    }
  }
}

Çalışma zamanında, Yanıt Oluşturma işlemi için istek gövdesinde gerçek sunucu yapılandırma değerlerini sağlayın (POST /openai/v1/responses):

{
  "agent_reference": {
    "type": "agent_reference",
    "name": "mcp-dynamic-agent"
  },
  "input": [{"type": "message", "role": "user", "content": "List recent commits"}],
  "structured_inputs": {
    "project_name": "CloudSync API",
    "server_label": "cloudsync-repo",
    "server_url": "https://gitmcp.io/myorg/cloudsync-api",
    "auth_token": "Bearer ghp_xxxxxxxxxxxx",
    "project_id": "proj_12345"
  }
}

MCP yapılandırılmış girişleri için SDK desenleri, önceki örneklerde gösterilen yaklaşımın aynısını izler. MCP araç özelliklerinde şablon yer tutucularını tanımlayın, aracı tanımında yapılandırılmış giriş şemalarını bildirin ve çalışma zamanında değerleri sağlayın.

Aşağıdaki Python örnek tam deseni gösterir:

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    MCPTool,
    PromptAgentDefinition,
    StructuredInputDefinition,
)
from azure.identity import DefaultAzureCredential

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

# Create clients to call Foundry API
project = AIProjectClient(endpoint=PROJECT_ENDPOINT, credential=DefaultAzureCredential())
openai = project.get_openai_client()

# Create MCP tool with template placeholders
tool = MCPTool(
    server_label="{{server_label}}",
    server_url="{{server_url}}",
    require_approval="never",
    headers={"Authorization": "{{auth_token}}", "X-Project-ID": "{{project_id}}"},
)

# Create agent with structured inputs for MCP configuration
agent = project.agents.create_version(
    agent_name="mcp-dynamic-agent",
    definition=PromptAgentDefinition(
        model="gpt-5-mini",
        instructions="You are a helpful development assistant for {{project_name}}.",
        tools=[tool],
        structured_inputs={
            "project_name": StructuredInputDefinition(
                description="Project name", required=True, schema={"type": "string"},
            ),
            "server_label": StructuredInputDefinition(
                description="MCP server label", required=True, schema={"type": "string"},
            ),
            "server_url": StructuredInputDefinition(
                description="MCP server URL", required=True, schema={"type": "string"},
            ),
            "auth_token": StructuredInputDefinition(
                description="Authentication token", required=True, schema={"type": "string"},
            ),
            "project_id": StructuredInputDefinition(
                description="Project identifier", required=True, schema={"type": "string"},
            ),
        },
    ),
)

# Supply MCP server configuration at runtime
conversation = openai.conversations.create()
response = openai.responses.create(
    conversation=conversation.id,
    input="List recent commits",
    extra_body={
        "agent_reference": {"name": agent.name, "type": "agent_reference"},
        "structured_inputs": {
            "project_name": "CloudSync API",
            "server_label": "cloudsync-repo",
            "server_url": "https://gitmcp.io/myorg/cloudsync-api",
            "auth_token": "Bearer ghp_xxxxxxxxxxxx",
            "project_id": "proj_12345",
        },
    },
)
print(response.output_text)

MCP sunucularına bağlanma hakkında daha fazla bilgi için bkz. Aracıları MCP sunucularına bağlama.

Yanıtlar API'sinde yapılandırılmış girişleri kullanma

Handlebar şablonlarını, aracı tanımında tanımlamadan doğrudan Yanıtlar API çağrılarında kullanabilirsiniz. Bu yaklaşım, yanıt düzeyi yönergeleri ve giriş dizisindeki sistem veya geliştirici iletileri için çalışır.

Yapılandırılmış girişlerle yanıt düzeyi yönergeleri

Sistem istemini parametreleştirmek için bir yanıt isteğiyle birlikte instructions yapılandırılmış girişleri geçirin:

{
  "instructions": "You are assisting {{customerName}} from {{companyName}} located in {{location}}.",
  "input": [
    {
      "type": "message",
      "role": "user",
      "content": "Hello, who am I?"
    }
  ],
  "structured_inputs": {
    "customerName": "Bob Johnson",
    "companyName": "Tech Corp",
    "location": "San Francisco"
  },
  "model": "gpt-4o"
}

Yapılandırılmış girişlere sahip sistem ve geliştirici iletileri

Konuşma bağlamı içine çalışma zamanı değerleri eklemek için sistem ve geliştirici iletisi içeriğinde handlebar şablonlarını kullanın:

{
  "instructions": "You are a helpful assistant.",
  "input": [
    {
      "type": "message",
      "role": "system",
      "content": "The user's name is {{userName}} and they work in {{department}}."
    },
    {
      "type": "message",
      "role": "developer",
      "content": [
        {
          "type": "input_text",
          "text": "User role: {{userRole}}. Always be professional."
        }
      ]
    },
    {
      "type": "message",
      "role": "user",
      "content": "Hello, can you confirm my details?"
    }
  ],
  "structured_inputs": {
    "userName": "Sarah Connor",
    "department": "Engineering",
    "userRole": "Tech Lead"
  },
  "model": "gpt-4o"
}

SDK kodunda, önceki örneklerde gösterilen aynı extra_body (Python), body (TypeScript) veya AzureCreateResponseOptions (Java/C#) desenlerini kullanarak bu değerleri geçirin.

Aşağıdaki Python örnekte, yapılandırılmış girişlerle yanıt düzeyi yönergelerinin nasıl kullanılacağı gösterilmektedir:

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

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

# Create clients to call Foundry API
project = AIProjectClient(endpoint=PROJECT_ENDPOINT, credential=DefaultAzureCredential())
openai = project.get_openai_client()

# Pass structured inputs with response-level instructions
response = openai.responses.create(
    model="gpt-5-mini",
    instructions="You are assisting {{customerName}} from {{companyName}} located in {{location}}.",
    input=[
        {
            "type": "message",
            "role": "user",
            "content": "Hello, who am I?",
        }
    ],
    extra_body={
        "structured_inputs": {
            "customerName": "Bob Johnson",
            "companyName": "Tech Corp",
            "location": "San Francisco",
        },
    },
)
print(response.output_text)

Gelişmiş şablon söz dizimi

Yapılandırılmış girişler, basit değişken değiştirmenin ötesinde tam Handlebars şablonu söz dizimlerini destekler. Tek bir aracı tanımı içinde dinamik yönerge mantığı oluşturmak için koşulluları, döngüleri ve diğer yerleşik yardımcıları kullanabilirsiniz.

Aşağıdaki örnek, davranışı çalışma zamanı girişlerine göre uyarlanan bir hava durumu yardımcısı oluşturur. Yönergeler şablonu, koşullu bölümler için {{#if}} ve kullanıcı tercihleri listesini yinelemek için {{#each}} kullanır.

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition, StructuredInputDefinition
from azure.identity import DefaultAzureCredential

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

# Create clients to call Foundry API
project = AIProjectClient(endpoint=PROJECT_ENDPOINT, credential=DefaultAzureCredential())
openai = project.get_openai_client()

# Define instructions with conditionals and loops
instructions = """You are a weather assistant. Provide a helpful weather summary for the user.

The user asked about: {{location}}
Use the following units: {{units}}

{{#if includeForecast}}
Include a brief multi-day forecast in your response.
{{else}}
Focus only on the current conditions.
{{/if}}

{{#if preferences}}
The user has these additional preferences:
{{#each preferences}}
- {{this}}
{{/each}}
{{/if}}

Keep the final answer clear and easy to read."""

agent = project.agents.create_version(
    agent_name="weather-assistant",
    definition=PromptAgentDefinition(
        model="gpt-5-mini",
        instructions=instructions,
        structured_inputs={
            "location": StructuredInputDefinition(
                description="City or region to check weather for",
                required=True,
                schema={"type": "string"},
            ),
            "units": StructuredInputDefinition(
                description="Temperature units (Celsius or Fahrenheit)",
                default_value="Celsius",
                schema={"type": "string"},
            ),
            "includeForecast": StructuredInputDefinition(
                description="Whether to include a multi-day forecast",
                default_value="false",
                schema={"type": "boolean"},
            ),
            "preferences": StructuredInputDefinition(
                description="Additional user preferences",
                schema={"type": "array"},
            ),
        },
    ),
)

# Supply values at runtime — conditionals and loops resolve automatically
conversation = openai.conversations.create()
response = openai.responses.create(
    conversation=conversation.id,
    input="What's the weather like?",
    extra_body={
        "agent_reference": {"name": agent.name, "type": "agent_reference"},
        "structured_inputs": {
            "location": "Seattle, WA",
            "units": "Fahrenheit",
            "includeForecast": True,
            "preferences": ["Highlight UV index", "Include wind speed"],
        },
    },
)
print(response.output_text)

Bu değerlerle, çözümlenen yönergeler şu hale gelir:

Sen hava durumu asistanısın. Kullanıcı için yararlı bir hava durumu özeti sağlayın.

Kullanıcı şunu sordu: Seattle, WA

Şu birimleri kullanın: Fahrenheit

Yanıtınıza kısa bir çok günlük tahmin ekleyin.

Kullanıcının şu ek tercihleri vardır:

  • UV indeksini vurgulama
  • Rüzgar hızını dahil et

Son yanıtı net ve okunması kolay tutun.

Aşağıdaki tabloda desteklenen Handlebars yardımcıları özetlenmektedir:

Yardımcı Sözdizimi Açıklama
Koşullu {{#if value}}...{{else}}...{{/if}} Doğru veya yanlış bir değere göre içeriği oluşturma
Negatiflik {{#unless value}}...{{/unless}} Bir değer "falsy" olduğunda içeriği yayınla
Döngü {{#each array}}{{this}}{{/each}} Dizi öğeleri üzerinde iterasyon yapma
Son öğe denetimi {{#unless @last}}, {{/unless}} Döngü öğeleri arasında ayırıcıları koşullu olarak işleme

İlgili içerik

  • Last updated on