你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
可以使用 结构化输入自定义代理的 Foundry 模型在运行时处理请求的方式。 结构化输入是使用句柄栏模板语法在代理中定义的占位符（{{variableName}}）。 在运行时，提供实际值来动态自定义代理指令、工具资源配置和响应参数，而无需为每个配置创建单独的代理版本。
在本文中，您将学到如何：
- 在代理定义中定义结构化输入
- 在代理说明中使用句柄栏模板
- 动态配置工具资源，如代码解释器和文件搜索
- 通过响应 API 在运行时传递结构化输入值
先决条件
- 基本或标准代理环境。
- 针对您的编程语言的最新 SDK 包。 请参阅 快速入门以了解安装步骤。
- 为身份验证配置的Azure凭据（如
DefaultAzureCredential）。 - Foundry 项目终结点 URL 和模型部署名称。
什么是结构化输入？
结构化输入使用句柄栏模板语法（{{variableName}}）来创建参数化代理定义。 可以在代理定义中 structured_inputs定义输入架构，其中每个输入都有一个名称、说明、类型和可选默认值。 在运行时，提供在代理处理请求之前替换模板占位符的实际值。
结构化输入支持两类替代：
- 指令替代：参数化智能体指令、响应级别指令和系统或开发人员消息。
-
工具资源替代：在运行时动态配置工具属性，包括：
- 文件搜索矢量存储 ID
- 代码解释器文件 ID 和容器
- 模型上下文协议 （MCP） 服务器 URL 和标头
对于像 file_ids 和 vector_store_ids 这样的数组字段，系统在运行时会自动删除空字符串值。 此功能支持灵活的输入计数 - 定义比所需更多的模板槽，并将未使用的槽留空。
支持的结构化输入属性
下表列出了支持句柄栏模板的代理定义属性：
| 类别 | 财产 | 描述 |
|---|---|---|
| 说明 | 代理 instructions |
代理级指令文本 |
| 说明 | 响应 instructions |
响应 API 请求中传递的说明 |
| 说明 | 系统/开发人员消息 content |
输入数组中的消息内容 |
| 文件搜索 | vector_store_ids |
矢量存储 ID 数组（空值已移除） |
| 代码解释器 |
container （字符串） |
预配置的容器的容器 ID |
| 代码解释器 |
container.file_ids （数组） |
自动容器中的文件 ID（已去除空值） |
| MCP | server_label |
MCP 服务器的标签 |
| MCP | server_url |
MCP 服务器终结点的 URL |
| MCP |
headers （值） |
HTTP 标头值作为键值对 |
将结构化输入与代理说明配合使用
结构化输入的最简单用法是参数化代理指令。 在 instructions 字段中定义 Handlebars 模板，并在运行时提供值。 此方法允许你为不同用户或上下文个性化代理行为，而无需创建多个代理版本。
以下示例创建一个代理，其说明包括特定于用户的详细信息，然后在创建响应时提供这些值。
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)
预期输出
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?
在处理请求之前，代理先将指令中的{{userName}}和{{userRole}}占位符分别替换为“Alice Smith”和“高级开发人员”。
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);
预期输出
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代理定义中的字典将模板名称映射到其架构。 在运行时，使用 Patch.Set 方法在 CreateResponseOptions 上，通过 $.structured_inputs 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";
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);
预期输出
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?
代理定义使用 structured_inputs 来声明模板架构。 在运行时，将 body 参数中的实际值与 agent_reference 的实际值一起传递。
将依赖项添加到pom.xml：
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-ai-agents</artifactId>
<version>2.0.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());
}
}
预期输出
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 对代理架构使用 StructuredInputDefinition，对通过 Map<String, BinaryData> 传递的运行时值使用 AzureCreateResponseOptions。
使用结构化输入创建代理
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"
}
}
}
}'
使用结构化输入值创建响应
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"
}
}'
代理定义的 structured_inputs 对象使用说明和默认值声明架构。 响应请求 structured_inputs 提供替换 {{userName}} 和 {{userRole}} 模板的实际运行时值。
将结构化输入与代码解释器配合使用
通过使用结构化输入，可以动态配置代码解释器工具在运行时使用的文件和容器。 在工具 file_ids 或 container 属性中定义句柄栏模板，然后在创建响应时提供实际 ID。
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)
预期输出
File uploaded (id: <file-id>)
The sum of x in numbers.csv is 6.
{{analysis_file_id}} 占位符在工具的 file_ids 数组中被替换为运行时的实际文件 ID。 通过这种方法，您可以在每个请求中使用不同的文件重复利用相同的代理定义。
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);
预期输出
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);
预期输出
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());
}
}
预期输出
Response: The sum of x in numbers.csv is 6.
使用动态代码解释器文件创建代理
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"}
}
}
}
}'
使用文件 ID 创建响应
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}}中，模板file_ids将在运行时被替换为实际文件 ID。 可以定义多个文件 ID 占位符，并将未使用的占位符留空。 空值会自动从数组中删除。
将结构化输入与文件搜索配合使用
通过使用结构化输入，可以动态配置哪些向量在运行时存储文件搜索工具查询。 在 vector_store_ids 数组中定义模板占位符，然后在创建响应时提供实际的矢量存储标识。
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)
预期输出
Vector store created (id: <vector-store-id>)
Based on the product information, Contoso offers several product lines including...
{{vector_store_id}}占位符在运行时替换为实际的向量存储 ID。 可以定义多个矢量存储占位符以启用分层或特定于上下文的知识库。
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);
预期输出
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);
预期输出
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());
}
}
预期输出
Response: Based on the product information, Contoso offers several product lines including...
创建一个具有动态文件搜索功能的矢量存储的代理程序
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"}
}
}
}
}'
使用矢量存储 ID 创建响应
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"
}
}'
此示例将静态向量存储（vs_base_kb）与动态向量存储（{{tier_specific_kb}}）结合在一起。 模板占位符在运行时被替换，该过程会自动删除数组中的任何空字符串值。
将结构化输入与 MCP 服务器配合使用
通过使用结构化输入，可以在运行时动态配置 MCP 服务器连接。 可以设置服务器 URL、身份验证标头和服务器标签。 通过使用此方法，单个代理定义可以连接到不同的 MCP 服务器，具体取决于上下文。
以下 JSON 显示 创建代理版本 操作的请求正文（POST /agents?api-version=v1）。 代理定义包括包含句柄栏模板占位符的 MCP 工具属性：
{
"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"}
}
}
}
}
在运行时，在创建响应操作的请求正文中提供实际的服务器配置值（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 结构化输入的 SDK 模式遵循前面示例中所示的相同方法。 在 MCP 工具属性中定义模板占位符，在代理定义中声明结构化输入架构，并在运行时提供值。
以下Python示例显示了完整的模式：
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 服务器的详细信息，请参阅 将代理连接到 MCP 服务器。
在响应 API 中使用结构化输入
可以直接在响应 API 调用中使用句柄栏模板，而无需在代理定义中定义它们。 此方法适用于响应级别的指令以及输入数组中的系统消息或开发者消息。
包含结构化输入的响应级别指令
在响应请求中将结构化输入与 instructions 一起传递，，以对系统提示进行参数化：
{
"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"
}
具有结构化输入的系统和开发人员消息
在系统和开发人员消息内容中使用句柄栏模板将运行时值注入到聊天上下文中：
{
"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 代码中，使用前面示例中所示的相同 extra_body （Python）、body （TypeScript）或 AzureCreateResponseOptions （Java/C#） 模式传递这些值。
以下Python示例演示如何对结构化输入使用响应级指令：
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)
高级模板语法
结构化输入支持完整的Handlebars模板语法，不仅限于简单的变量替换。 可以使用条件、循环和其他内置帮助程序在单个代理定义中创建动态指令逻辑。
以下示例创建一个天气助手，其行为根据运行时输入进行调整。 说明模板使用 {{#if}} 处理条件部分，并使用 {{#each}} 遍历用户首选项列表：
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)
使用这些值，已解析的指令为：
你是天气助理。 为用户提供有用的天气摘要。
用户询问了以下问题：西雅图，WA
使用以下单位：华氏度
在响应中包含简短的多天预测。
用户具有以下附加首选项：
- 突出显示紫外线指数
- 包括风速
保持最终答案清晰易读。
下表汇总了支持的 Handlebars 帮助程序：
| 帮手 | 语法 | 描述 |
|---|---|---|
| 条件 | {{#if value}}...{{else}}...{{/if}} |
基于真实值或虚构值呈现内容 |
| 否定 | {{#unless value}}...{{/unless}} |
当值为假时呈现内容 |
| 循环 | {{#each array}}{{this}}{{/each}} |
遍历数组项 |
| 最后一项检查 | {{#unless @last}}, {{/unless}} |
有条件地呈现循环项之间的分隔符 |