Menyesuaikan perilaku agen saat runtime dengan input terstruktur

Anda dapat menyesuaikan bagaimana model Foundry agen memproses permintaan saat runtime menggunakan input terstruktur. Input terstruktur adalah tempat penampung yang ditentukan dalam agen perangkat lunak menggunakan sintaks templat "handlebar" ({{variableName}}). Pada runtime, Anda menyediakan nilai aktual untuk menyesuaikan instruksi agen, konfigurasi sumber daya alat, dan parameter respons secara dinamis—tanpa membuat versi agen terpisah untuk setiap konfigurasi.

Dalam artikel ini, Anda mempelajari cara:

  • Menentukan input terstruktur dalam definisi agen
  • Gunakan template handlebar dalam instruksi agen
  • Mengonfigurasi sumber daya alat secara dinamis seperti Penerjemah Kode dan Pencarian File
  • Meneruskan nilai input terstruktur saat runtime melalui API Respons

Prasyarat

  • Lingkungan agen dasar atau standar.
  • Paket SDK terbaru untuk bahasa Anda. Lihat panduan cepat untuk langkah-langkah penginstalan.
  • Azure kredensial yang dikonfigurasi untuk otentikasi (seperti DefaultAzureCredential).
  • URL titik akhir proyek Foundry dan nama penyebaran model Anda.

Important

Jangan meneruskan rahasia, token akses, atau info masuk lainnya sebagai input terstruktur. Log atau pelacakan aplikasi mungkin menangkap nilai input terstruktur sebagai bagian dari permintaan. Simpan kredensial dalam koneksi proyek atau penyimpanan rahasia terkelola lainnya sebagai gantinya.

Apa itu input terstruktur?

Input terstruktur menggunakan sintaks templat handlebar ({{variableName}}) untuk membuat definisi agen berparameter. Anda menentukan skema input dalam definisi agen di bawah structured_inputs, di mana setiap input memiliki nama, deskripsi, jenis, dan nilai default opsional. Selama runtime, berikan nilai yang sebenarnya yang menggantikan placeholder templat sebelum agen memproses permintaan.

Input terstruktur mendukung dua kategori penimpaan:

  • Penimpaan instruksi: Membuat parameter instruksi agen, instruksi tingkat respons, dan pesan sistem atau pengembang.
  • Penggantian sumber daya alat: Mengonfigurasi properti alat secara dinamis selama waktu eksekusi, termasuk:
    • ID simpanan vektor pencarian berkas
    • ID dan kontainer file penerjemah kode
    • URL dan header server Protokol Konteks Model (MCP)

Untuk bidang array seperti file_ids dan vector_store_ids, sistem secara otomatis menghapus nilai string kosong saat runtime. Fitur ini memungkinkan jumlah input yang fleksibel – menentukan lebih banyak slot templat daripada yang diperlukan dan membiarkan yang tidak digunakan kosong.

Properti input terstruktur yang didukung

Tabel berikut ini mencantumkan properti definisi agen yang mendukung templat handlebar:

Kategori Properti Deskripsi
Petunjuk Agen instructions Teks instruksi tingkat agen
Petunjuk Respon instructions Instruksi yang diteruskan dalam permintaan API Respons
Petunjuk Pesan sistem/pengembang content Konten pesan dalam array input
Pencarian File vector_store_ids Larik ID penyimpanan vektor (dengan nilai kosong dihapus)
Penerjemah Kode container (String) ID Kontainer untuk kontainer yang telah dikonfigurasi sebelumnya
Penerjemah Kode container.file_ids (array/larik) ID file dalam kontainer otomatis (nilai kosong dihapus)
MCP server_label Label untuk server MCP
MCP server_url URL untuk titik akhir server MCP
MCP headers (nilai) Nilai header HTTP sebagai pasangan kunci-nilai
Pencarian Azure AI filter Ekspresi filter OData diterapkan ke indeks pencarian

Menggunakan input terstruktur dengan instruksi agen

Penggunaan input terstruktur yang paling sederhana adalah untuk membuat parameter instruksi agen. Tentukan templat handlebar di instructions bidang dan berikan nilai pada runtime. Pendekatan ini memungkinkan Anda mempersonalisasi perilaku agen untuk pengguna atau konteks yang berbeda tanpa membuat beberapa versi agen.

Contoh berikut membuat agen yang instruksinya mencakup detail khusus pengguna lalu menyediakan nilai-nilai tersebut saat membuat respons.

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"
AGENT_NAME = "structured-input-agent"

with AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
) as project:
    # Create agent with handlebar templates in instructions
    agent = project.agents.create_version(
        agent_name=AGENT_NAME,
        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}")

    with project.get_openai_client(agent_name=agent.name) as openai:
        # 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={
                "structured_inputs": {
                    "userName": "Alice Smith",
                    "userRole": "Senior Developer",
                },
            ),
        )
        print(response.output_text)

Output yang diharapkan

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?

Agen mengganti penampung {{userName}} dan {{userRole}} dalam instruksi dengan "Alice Smith" dan "Pengembang Senior" sebelum memproses permintaan.

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

Output yang diharapkan

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?

StructuredInputs Kamus pada definisi agen memetakan nama templat ke skemanya. Pada runtime, gunakan metode Patch.Set pada CreateResponseOptions untuk menyediakan nilai aktual menggunakan jalur JSON $.structured_inputs.

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

Output yang diharapkan

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?

Definisi agen menggunakan structured_inputs untuk mendeklarasikan skema templat. Pada runtime, masukkan nilai aktual dalam parameter body bersama dengan agent_reference.

Tambahkan dependensi ke pom.xml:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-ai-agents</artifactId>
    <version>2.4.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());
    }
}

Output yang diharapkan

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?

SDK Java menggunakan StructuredInputDefinition untuk skema agen dan Map<String, BinaryData> untuk nilai runtime yang diteruskan melalui AzureCreateResponseOptions.

Membuat agen dengan input terstruktur

curl -X POST "$FOUNDRY_PROJECT_ENDPOINT/agents?api-version=v1" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  --data-binary @- <<EOF
{
    "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"
        }
      }
    }
}
EOF

Membuat respons dengan nilai input terstruktur

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

Objek definisi structured_inputs agen mendeklarasikan skema dengan deskripsi dan nilai default. Permintaan respons structured_inputs menyediakan nilai runtime yang aktual menggantikan templat {{userName}} dan {{userRole}}.

Menggunakan input terstruktur dengan Penerjemah Kode

Dengan menggunakan input terstruktur, Anda dapat mengonfigurasi file dan kontainer mana yang digunakan alat Penerjemah Kode secara dinamis pada runtime. Tentukan templat handlebar di properti file_ids atau container alat, lalu berikan ID aktual saat membuat respons.

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)

Output yang diharapkan

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

Placeholder {{analysis_file_id}} dalam array alat file_ids digantikan oleh ID file aktual saat runtime. Dengan menggunakan pendekatan ini, Anda dapat menggunakan kembali definisi agen yang sama dengan file yang berbeda untuk setiap permintaan.

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

Output yang diharapkan

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

Output yang diharapkan

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

Output yang diharapkan

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

Membuat agen dengan file Penerjemah Kode dinamis

curl -X POST "$FOUNDRY_PROJECT_ENDPOINT/agents?api-version=v1" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  --data-binary @- <<EOF
{
    "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"}
        }
      }
    }
}
EOF

Membuat respons dengan ID file

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

{{analysis_file_id}} Templat di file_ids diganti dengan ID file aktual saat runtime. Anda dapat menentukan beberapa tempat penampung ID file dan membiarkan tempat penampung YANG tidak digunakan kosong. Nilai kosong secara otomatis dihapus dari array.

Dengan menggunakan input terstruktur, Anda dapat secara dinamis mengonfigurasi vektor mana yang menyimpan kueri alat Pencarian File saat runtime. Tentukan tempat penampung templat dalam vector_store_ids array, lalu berikan ID penyimpanan vektor aktual saat membuat respons.

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)

Output yang diharapkan

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

Placeholder {{vector_store_id}} diganti dengan ID toko vektor yang sebenarnya saat runtime. Anda dapat menentukan beberapa tempat penampung penyimpanan vektor untuk mengaktifkan pangkalan pengetahuan berjenjang atau khusus konteks.

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

Output yang diharapkan

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

Output yang diharapkan

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

Output yang diharapkan

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

Membuat agen dengan penyimpanan vektor pencarian berkas yang dinamis

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

Buat respons dengan ID penyimpanan vektor

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

Contoh ini menggabungkan penyimpanan vektor statis (vs_base_kb) dengan yang dinamis ({{tier_specific_kb}}). Tempat penampung templat digantikan pada saat runtime, dan proses secara otomatis menghapus nilai string kosong di dalam array.

Dengan menggunakan input terstruktur, Anda dapat mengonfigurasi indeks alat Pencarian Azure AI secara dinamis filter pada runtime. Tentukan templat handlebar di dalam ekspresi filter OData, lalu berikan nilai filter aktual saat membuat respons. Pola ini memungkinkan definisi agen tunggal melayani pengguna yang kuerinya harus dilingkup ke subset indeks yang berbeda tanpa membuat versi agen terpisah per nilai filter.

Validasi nilai sebelum menyisipkannya ke dalam filter OData. Izinkan hanya nilai yang diharapkan, lakukan escape pada karakter khusus OData, dan jangan terima ekspresi filter lengkap dari pengguna yang tidak tepercaya.

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"
AGENT_NAME = "aisearch-agent-structured-input"

with AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
) as project:
    # 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=AGENT_NAME,
        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})")

    with project.get_openai_client(agent_name=agent.name) as openai:
        # 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={
                "structured_inputs": {"userFilter": "boots"},
            },
        )

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

Output yang diharapkan

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

Placeholder {{userFilter}} di dalam ekspresi filter diganti dengan nilai runtime boots sebelum pencarian dijalankan. Anda dapat menyediakan nilai filter yang berbeda untuk setiap permintaan ke hasil cakupan tanpa membuat versi agen baru.

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

Output yang diharapkan

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

Properti Filter pada AzureAISearchToolIndex menerima templat handlebar yang diselesaikan pada runtime. Gunakan Patch.Set pada CreateResponseOptions untuk menyediakan nilai filter melalui $.structured_inputs jalur JSON.

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

Output yang diharapkan

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

Output yang diharapkan

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

Membuat agen dengan filter Pencarian Azure AI dinamis

curl -X POST "$FOUNDRY_PROJECT_ENDPOINT/agents?api-version=v1" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  --data-binary @- <<EOF
{
    "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"}
        }
      }
    }
}
EOF

Buat respons dengan nilai filter

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

Saat runtime, ekspresi filter menggantikan templat {{userFilter}} dengan boots. Heredoc yang tidak dikutip memperluas variabel lingkungan koneksi dan indeks sebelum curl mengirim isi JSON.

Menggunakan input terstruktur dengan server MCP

Dengan menggunakan input terstruktur, Anda dapat mengonfigurasi properti server MCP nonsecret secara dinamis seperti URL server, label server, dan header perutean. Gunakan koneksi proyek atau mekanisme autentikasi terkelola lainnya untuk kredensial. Dengan menggunakan pendekatan ini, definisi agen tunggal dapat terhubung ke server MCP yang berbeda tergantung pada konteksnya.

JSON berikut menunjukkan isi permintaan untuk operasi Buat Versi Agen (POST /agents?api-version=v1). Definisi agen mencakup properti alat MCP dengan tempat penampung templat handlebar:

{
  "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": {"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"}
      },
      "project_id": {
        "description": "Project identifier",
        "required": true,
        "schema": {"type": "string"}
      }
    }
  }
}

Pada runtime, berikan nilai konfigurasi server aktual dalam isi permintaan untuk operasi Buat Respons (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",
    "project_id": "proj_12345"
  }
}

Pola SDK untuk input terstruktur MCP mengikuti pendekatan yang sama yang ditunjukkan pada contoh sebelumnya. Tentukan tempat penampung templat di properti alat MCP, deklarasikan skema input terstruktur dalam definisi agen, dan berikan nilai saat runtime.

Contoh Python berikut menunjukkan pola lengkap:

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"
AGENT_NAME = "mcp-dynamic-agent"

with AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
) as project:
    # Create MCP tool with template placeholders
    tool = MCPTool(
        server_label="{{server_label}}",
        server_url="{{server_url}}",
        require_approval="never",
        headers={"X-Project-ID": "{{project_id}}"},
    )

    # Create agent with structured inputs for MCP configuration
    agent = project.agents.create_version(
        agent_name=AGENT_NAME,
        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"},
                ),
                "project_id": StructuredInputDefinition(
                    description="Project identifier", required=True, schema={"type": "string"},
                ),
            },
        ),
    )

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

Contoh TypeScript berikut menunjukkan pola yang sama:

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 structured inputs for MCP configuration. The MCP tool
  // is defined inline so TypeScript infers the literal "mcp" type instead of
  // widening it to string.
  const agent = await project.agents.createVersion("mcp-dynamic-agent", {
    kind: "prompt",
    model: "gpt-5-mini",
    instructions: "You are a helpful 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,
        schema: { type: "string" },
      },
      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" },
      },
    },
  });

  // Supply MCP server configuration at runtime
  const conversation = await openai.conversations.create();
  const response = await openai.responses.create(
    {
      conversation: conversation.id,
      input: "List recent commits",
    },
    {
      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: "******",
          project_id: "proj_12345",
        },
      },
    },
  );
  console.log(response.output_text);
}

main().catch(console.error);

Untuk informasi selengkapnya tentang menyambungkan ke server MCP, lihat Menyambungkan agen ke server MCP.

Menggunakan input terstruktur di API Respons

Anda dapat menggunakan templat handlebar secara langsung dalam panggilan Responses API tanpa menentukannya dalam definisi agen. Pendekatan ini berfungsi untuk instruksi pada tingkat respons dan untuk pesan sistem atau pengembang dalam array input.

Instruksi tingkat respon dengan input terstruktur

Teruskan input terstruktur bersama instructions dalam permintaan tanggapan untuk memparameterisasi prompt sistem.

{
  "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"
}

Pesan sistem dan pengembang dengan input terstruktur

Gunakan templat handlebar dalam konten pesan sistem dan pengembang untuk menyuntikkan nilai runtime ke dalam konteks percakapan:

{
  "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"
}

Dalam kode SDK, berikan nilai-nilai ini dengan menggunakan pola extra_body (Python) yang sama, body (TypeScript), atau AzureCreateResponseOptions (Java/C#) yang ditunjukkan dalam contoh sebelumnya.

Contoh Python berikut menunjukkan cara menggunakan instruksi tingkat respons dengan input terstruktur:

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)

Contoh TypeScript berikut menunjukkan pola yang sama:

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

  // Pass structured inputs with response-level instructions
  const response = await 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?",
        },
      ],
    },
    {
      body: {
        structured_inputs: {
          customerName: "Bob Johnson",
          companyName: "Tech Corp",
          location: "San Francisco",
        },
      },
    },
  );
  console.log(response.output_text);
}

main().catch(console.error);

Sintaks templat tingkat lanjut

Input terstruktur mendukung sintaks templat Handlebars penuh lebih dari sekadar substitusi variabel sederhana. Anda dapat menggunakan kondisional, perulangan, dan pembantu bawaan lainnya untuk membuat logika instruksi dinamis dalam satu definisi agen.

Contoh berikut membuat asisten cuaca yang perilakunya beradaptasi berdasarkan input runtime. Templat instruksi menggunakan {{#if}} untuk bagian kondisional dan {{#each}} untuk melakukan iterasi atas daftar preferensi pengguna:

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"
AGENT_NAME = "weather-assistant"

with AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
) as project:
    # 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=AGENT_NAME,
        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"},
                ),
            },
        ),
    )

    with project.get_openai_client(agent_name=agent.name) as openai:
        # 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={
                "structured_inputs": {
                    "location": "Seattle, WA",
                    "units": "Fahrenheit",
                    "includeForecast": True,
                    "preferences": ["Highlight UV index", "Include wind speed"],
                },
            },
        )
        print(response.output_text)

Contoh TypeScript berikut menunjukkan pola yang sama:

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

  // Define instructions with conditionals and loops
  const 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.`;

  const agent = await project.agents.createVersion("weather-assistant", {
    kind: "prompt",
    model: "gpt-5-mini",
    instructions,
    structured_inputs: {
      location: {
        description: "City or region to check weather for",
        required: true,
        schema: { type: "string" },
      },
      units: {
        description: "Temperature units (Celsius or Fahrenheit)",
        default_value: "Celsius",
        schema: { type: "string" },
      },
      includeForecast: {
        description: "Whether to include a multi-day forecast",
        default_value: false,
        schema: { type: "boolean" },
      },
      preferences: {
        description: "Additional user preferences",
        schema: { type: "array" },
      },
    },
  });

  // Supply values at runtime — conditionals and loops resolve automatically
  const conversation = await openai.conversations.create();
  const response = await openai.responses.create(
    {
      conversation: conversation.id,
      input: "What's the weather like?",
    },
    {
      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"],
        },
      },
    },
  );
  console.log(response.output_text);
}

main().catch(console.error);

Dengan nilai-nilai ini, instruksi yang diselesaikan menjadi:

Kau asisten cuaca. Berikan ringkasan cuaca yang bermanfaat untuk pengguna.

Pengguna bertanya tentang: Seattle, WA

Gunakan unit berikut: Fahrenheit

Sertakan prakiraan singkat beberapa hari dalam respons Anda.

Pengguna memiliki preferensi tambahan ini:

  • Tampilkan indeks UV
  • Sertakan kecepatan angin

Jaga agar jawaban akhir tetap jelas dan mudah dibaca.

Tabel berikut ini meringkas pembantu Handlebar yang didukung:

Asisten Sintaks Deskripsi
Bersyarat {{#if value}}...{{else}}...{{/if}} Merender konten berdasarkan nilai kebenaran atau falsy
Negasi {{#unless value}}...{{/unless}} Menampilkan konten saat nilai dievaluasi sebagai tidak benar
Loop {{#each array}}{{this}}{{/each}} Melakukan iterasi atas item array
Pemeriksaan item terakhir {{#unless @last}}, {{/unless}} Render secara kondisional pemisah antara item perulangan

Konten terkait

  • Terakhir diperbarui pada