Add structured inputs sample

sdk/ai/azure-ai-agents/CHANGELOG.md

@@ -16,6 +16,10 @@
   - `createStreamingWithAgent` and `createStreamingWithAgentConversation` on `ResponsesAsyncClient` return `Flux<ResponseStreamEvent>` for asynchronous streaming.
 - Added `StreamingUtils` implementation helper that bridges OpenAI `StreamResponse` to `IterableStream` and `AsyncStreamResponse` to `Flux`.
 - Added streaming samples: `SimpleStreamingSync`/`SimpleStreamingAsync`, `FunctionCallStreamingSync`/`FunctionCallStreamingAsync`, and `CodeInterpreterStreamingSync`/`CodeInterpreterStreamingAsync`.
+- Added structured input convenience methods to `ResponsesClient` and `ResponsesAsyncClient` for creating responses with agent-defined template parameters:
+  - `createWithAgentStructuredInput` accepts a `Map<String, Object>` of runtime values that are substituted into the agent's prompt template.
+  - `createStreamingWithAgentStructuredInput` provides the streaming equivalent, returning `IterableStream<ResponseStreamEvent>` (sync) or `Flux<ResponseStreamEvent>` (async).
+- Added `CreateResponseWithStructuredInput` sample demonstrating how to define structured inputs on an agent and pass runtime values when creating a response.
 
 ### Breaking Changes
 
@@ -33,6 +37,7 @@
 
 - Added `ToolsTests` and `ToolsAsyncTests` with recorded end-to-end test coverage for OpenAPI, Code Interpreter, Function Call, Web Search, MCP, and File Search tools.
 - Added `StreamingTests` and `StreamingAsyncTests` with recorded test coverage for streaming responses (simple prompt, function calling, and Code Interpreter scenarios).
+- Added structured input test coverage to `AgentsTests`, `AgentsAsyncTests`, `StreamingTests`, and `StreamingAsyncTests`.
 
 ## 2.0.0-beta.2 (2026-03-04)
 

sdk/ai/azure-ai-agents/README.md

@@ -623,6 +623,51 @@ See the full samples in [SimpleStreamingAsync.java](https://github.com/Azure/azu
 
 ---
 
+### Structured inputs
+
+Structured inputs allow you to define named parameters on an agent that get substituted into its prompt template at runtime. This is useful when you want the same agent definition to handle different users or contexts by simply changing the input values.
+
+#### Define structured inputs on an agent
+
+When creating the agent, declare each structured input with a description and whether it is required. Use `{{inputName}}` placeholders in the instructions to reference them:
+
+```java com.azure.ai.agents.define_structured_inputs
+// Create an agent with structured input definitions
+Map<String, StructuredInputDefinition> structuredInputDefinitions = new LinkedHashMap<>();
+structuredInputDefinitions.put("userName", new StructuredInputDefinition().setDescription("User's name").setRequired(true));
+structuredInputDefinitions.put("userRole", new StructuredInputDefinition().setDescription("User's role").setRequired(true));
+
+AgentVersionDetails agent = agentsClient.createAgentVersion("structured-input-agent",
+    new PromptAgentDefinition(model)
+        .setInstructions("You are a helpful assistant. "
+            + "The user's name is {{userName}} and their role is {{userRole}}. "
+            + "Greet them and confirm their details.")
+        .setStructuredInputs(structuredInputDefinitions));
+```
+
+#### Create a response with structured input values
+
+When creating a response, pass a `Map<String, Object>` whose keys match the structured input names declared on the agent. The values are substituted into the prompt template before the model processes the request:
+
+```java com.azure.ai.agents.create_response_with_structured_input
+// Create a response, passing structured input values that match the agent's definitions
+Map<String, Object> structuredInputValues = new LinkedHashMap<>();
+structuredInputValues.put("userName", "Alice Smith");
+structuredInputValues.put("userRole", "Senior Developer");
+
+Response response = responsesClient.createWithAgentStructuredInput(
+    new AgentReference(agent.getName()).setVersion(agent.getVersion()),
+    structuredInputValues,
+    ResponseCreateParams.builder().input("Hello! Can you confirm my details?")
+);
+```
+
+Streaming is also supported via `createStreamingWithAgentStructuredInput`, which returns an `IterableStream<ResponseStreamEvent>` (sync) or `Flux<ResponseStreamEvent>` (async).
+
+See the full sample in [CreateResponseWithStructuredInput.java](https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/ai/azure-ai-agents/src/samples/java/com/azure/ai/agents/CreateResponseWithStructuredInput.java).
+
+---
+
 ### Service API versions
 
 The client library targets the latest service API version by default.

sdk/ai/azure-ai-agents/assets.json

@@ -2,5 +2,5 @@
   "AssetsRepo": "Azure/azure-sdk-assets",
   "AssetsRepoPrefixPath": "java",
   "TagPrefix": "java/ai/azure-ai-agents",
-  "Tag": "java/ai/azure-ai-agents_4b3a190a4f"
+  "Tag": "java/ai/azure-ai-agents_bb4574aecb"
 }

sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/ResponsesAsyncClient.java

@@ -111,6 +111,44 @@ public Mono<Response> createWithAgent(AgentReference agentReference) {
         return createWithAgent(agentReference, new ResponseCreateParams.Builder());
     }
 
+    /**
+     * Creates a response using structured input values that are substituted into the agent's prompt template
+     * at runtime. The keys in the {@code structuredInputs} map must match the structured input names declared
+     * on the agent's definition (via {@link com.azure.ai.agents.models.StructuredInputDefinition}), and the values should conform to the
+     * schema and type expectations defined there.
+     *
+     * <p>For example, if the agent was created with structured inputs {@code "userName"} and {@code "userRole"},
+     * the map should contain the corresponding runtime values:</p>
+     * <pre>{@code
+     * Map<String, Object> structuredInputs = new LinkedHashMap<>();
+     * structuredInputs.put("userName", "Alice Smith");
+     * structuredInputs.put("userRole", "Senior Developer");
+     * }</pre>
+     *
+     * @param agentReference The agent reference.
+     * @param structuredInputs A map of structured input names to their runtime values. The values are
+     *     serialized as JSON and must match the structure expected by the agent's definition.
+     * @param params The parameters to create the response.
+     * @return A Mono that emits the created Response.
+     */
+    public Mono<Response> createWithAgentStructuredInput(AgentReference agentReference,
+        Map<String, Object> structuredInputs, ResponseCreateParams.Builder params) {
+        Objects.requireNonNull(agentReference, "agentReference cannot be null");
+        Objects.requireNonNull(structuredInputs, "structuredInputs cannot be null");
+        Objects.requireNonNull(params, "params cannot be null");
+
+        JsonValue agentRefJsonValue = OpenAIJsonHelper.toJsonValue(agentReference);
+        JsonValue structuredInputsJsonValue = JsonValue.from(structuredInputs);
+
+        Map<String, JsonValue> additionalBodyProperties = new HashMap<>();
+        additionalBodyProperties.put("agent_reference", agentRefJsonValue);
+        additionalBodyProperties.put("structured_inputs", structuredInputsJsonValue);
+
+        params.additionalBodyProperties(additionalBodyProperties);
+
+        return Mono.fromFuture(this.responseServiceAsync.create(params.build()));
+    }
+
     /**
      * Creates a streaming response with an agent.
      *
@@ -132,6 +170,43 @@ public Flux<ResponseStreamEvent> createStreamingWithAgent(AgentReference agentRe
         return StreamingUtils.toFlux(this.responseServiceAsync.createStreaming(params.build()));
     }
 
+    /**
+     * Creates a streaming response using structured input values that are substituted into the agent's prompt
+     * template at runtime. The keys in the {@code structuredInputs} map must match the structured input names
+     * declared on the agent's definition (via {@link com.azure.ai.agents.models.StructuredInputDefinition}), and the values should conform
+     * to the schema and type expectations defined there.
+     *
+     * <p>For example, if the agent was created with structured inputs {@code "userName"} and {@code "userRole"},
+     * the map should contain the corresponding runtime values:</p>
+     * <pre>{@code
+     * Map<String, Object> structuredInputs = new LinkedHashMap<>();
+     * structuredInputs.put("userName", "Alice Smith");
+     * structuredInputs.put("userRole", "Senior Developer");
+     * }</pre>
+     *
+     * @param agentReference The agent reference.
+     * @param structuredInputs A map of structured input names to their runtime values. The values are
+     *     serialized as JSON and must match the structure expected by the agent's definition.
+     * @param params The parameters to create the response.
+     * @return A Flux of ResponseStreamEvent.
+     */
+    public Flux<ResponseStreamEvent> createStreamingWithAgentStructuredInput(AgentReference agentReference,
+        Map<String, Object> structuredInputs, ResponseCreateParams.Builder params) {
+        Objects.requireNonNull(agentReference, "agentReference cannot be null");
+        Objects.requireNonNull(structuredInputs, "structuredInputs cannot be null");
+        Objects.requireNonNull(params, "params cannot be null");
+
+        JsonValue agentRefJsonValue = OpenAIJsonHelper.toJsonValue(agentReference);
+        JsonValue structuredInputsJsonValue = JsonValue.from(structuredInputs);
+
+        Map<String, JsonValue> additionalBodyProperties = new HashMap<>();
+        additionalBodyProperties.put("agent_reference", agentRefJsonValue);
+        additionalBodyProperties.put("structured_inputs", structuredInputsJsonValue);
+
+        params.additionalBodyProperties(additionalBodyProperties);
+        return StreamingUtils.toFlux(this.responseServiceAsync.createStreaming(params.build()));
+    }
+
     /**
      * Creates a streaming response with an agent conversation.
      *

sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/ResponsesClient.java

@@ -110,6 +110,43 @@ public Response createWithAgent(AgentReference agentReference) {
         return createWithAgent(agentReference, new ResponseCreateParams.Builder());
     }
 
+    /**
+     * Creates a response using structured input values that are substituted into the agent's prompt template
+     * at runtime. The keys in the {@code structuredInputs} map must match the structured input names declared
+     * on the agent's definition (via {@link com.azure.ai.agents.models.StructuredInputDefinition}), and the values should conform to the
+     * schema and type expectations defined there.
+     *
+     * <p>For example, if the agent was created with structured inputs {@code "userName"} and {@code "userRole"},
+     * the map should contain the corresponding runtime values:</p>
+     * <pre>{@code
+     * Map<String, Object> structuredInputs = new LinkedHashMap<>();
+     * structuredInputs.put("userName", "Alice Smith");
+     * structuredInputs.put("userRole", "Senior Developer");
+     * }</pre>
+     *
+     * @param agentReference The agent reference.
+     * @param structuredInputs A map of structured input names to their runtime values. The values are
+     *     serialized as JSON and must match the structure expected by the agent's definition.
+     * @param params The parameters to create the response.
+     * @return The created Response.
+     */
+    public Response createWithAgentStructuredInput(AgentReference agentReference, Map<String, Object> structuredInputs,
+        ResponseCreateParams.Builder params) {
+        Objects.requireNonNull(agentReference, "agentReference cannot be null");
+        Objects.requireNonNull(structuredInputs, "structuredInputs cannot be null");
+
+        JsonValue agentRefJsonValue = OpenAIJsonHelper.toJsonValue(agentReference);
+        JsonValue structuredInputsJsonValue = JsonValue.from(structuredInputs);
+
+        Map<String, JsonValue> additionalBodyProperties = new HashMap<>();
+        additionalBodyProperties.put("agent_reference", agentRefJsonValue);
+        additionalBodyProperties.put("structured_inputs", structuredInputsJsonValue);
+
+        params.additionalBodyProperties(additionalBodyProperties);
+
+        return this.responseService.create(params.build());
+    }
+
     /**
      * Creates a streaming response with an agent.
      *
@@ -131,6 +168,43 @@ public IterableStream<ResponseStreamEvent> createStreamingWithAgent(AgentReferen
         return StreamingUtils.toIterableStream(this.responseService.createStreaming(params.build()));
     }
 
+    /**
+     * Creates a streaming response using structured input values that are substituted into the agent's prompt
+     * template at runtime. The keys in the {@code structuredInputs} map must match the structured input names
+     * declared on the agent's definition (via {@link com.azure.ai.agents.models.StructuredInputDefinition}), and the values should conform
+     * to the schema and type expectations defined there.
+     *
+     * <p>For example, if the agent was created with structured inputs {@code "userName"} and {@code "userRole"},
+     * the map should contain the corresponding runtime values:</p>
+     * <pre>{@code
+     * Map<String, Object> structuredInputs = new LinkedHashMap<>();
+     * structuredInputs.put("userName", "Alice Smith");
+     * structuredInputs.put("userRole", "Senior Developer");
+     * }</pre>
+     *
+     * @param agentReference The agent reference.
+     * @param structuredInputs A map of structured input names to their runtime values. The values are
+     *     serialized as JSON and must match the structure expected by the agent's definition.
+     * @param params The parameters to create the response.
+     * @return An IterableStream of ResponseStreamEvent.
+     */
+    public IterableStream<ResponseStreamEvent> createStreamingWithAgentStructuredInput(AgentReference agentReference,
+        Map<String, Object> structuredInputs, ResponseCreateParams.Builder params) {
+        Objects.requireNonNull(agentReference, "agentReference cannot be null");
+        Objects.requireNonNull(structuredInputs, "structuredInputs cannot be null");
+        Objects.requireNonNull(params, "params cannot be null");
+
+        JsonValue agentRefJsonValue = OpenAIJsonHelper.toJsonValue(agentReference);
+        JsonValue structuredInputsJsonValue = JsonValue.from(structuredInputs);
+
+        Map<String, JsonValue> additionalBodyProperties = new HashMap<>();
+        additionalBodyProperties.put("agent_reference", agentRefJsonValue);
+        additionalBodyProperties.put("structured_inputs", structuredInputsJsonValue);
+
+        params.additionalBodyProperties(additionalBodyProperties);
+        return StreamingUtils.toIterableStream(this.responseService.createStreaming(params.build()));
+    }
+
     /**
      * Creates a streaming response with an agent conversation.
      *

sdk/ai/azure-ai-agents/src/samples/java/com/azure/ai/agents/CreateResponseWithStructuredInput.java

@@ -0,0 +1,68 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.azure.ai.agents;
+
+import com.azure.ai.agents.models.AgentReference;
+import com.azure.ai.agents.models.AgentVersionDetails;
+import com.azure.ai.agents.models.PromptAgentDefinition;
+import com.azure.ai.agents.models.StructuredInputDefinition;
+import com.azure.core.util.Configuration;
+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;
+
+/**
+ * This sample demonstrates how to create a response with structured inputs.
+ * Structured inputs are key-value pairs defined on an agent that get substituted
+ * into the agent's prompt template at runtime.
+ */
+public class CreateResponseWithStructuredInput {
+    public static void main(String[] args) {
+        String endpoint = Configuration.getGlobalConfiguration().get("FOUNDRY_PROJECT_ENDPOINT");
+        String model = Configuration.getGlobalConfiguration().get("FOUNDRY_MODEL_NAME");
+
+        AgentsClientBuilder builder = new AgentsClientBuilder()
+            .credential(new DefaultAzureCredentialBuilder().build())
+            .endpoint(endpoint)
+            .serviceVersion(AgentsServiceVersion.getLatest());
+
+        AgentsClient agentsClient = builder.buildAgentsClient();
+        ResponsesClient responsesClient = builder.buildResponsesClient();
+
+        // BEGIN: com.azure.ai.agents.define_structured_inputs
+        // Create an agent with structured input definitions
+        Map<String, StructuredInputDefinition> structuredInputDefinitions = new LinkedHashMap<>();
+        structuredInputDefinitions.put("userName", new StructuredInputDefinition().setDescription("User's name").setRequired(true));
+        structuredInputDefinitions.put("userRole", new StructuredInputDefinition().setDescription("User's role").setRequired(true));
+
+        AgentVersionDetails agent = agentsClient.createAgentVersion("structured-input-agent",
+            new PromptAgentDefinition(model)
+                .setInstructions("You are a helpful assistant. "
+                    + "The user's name is {{userName}} and their role is {{userRole}}. "
+                    + "Greet them and confirm their details.")
+                .setStructuredInputs(structuredInputDefinitions));
+        // END: com.azure.ai.agents.define_structured_inputs
+
+        // BEGIN: com.azure.ai.agents.create_response_with_structured_input
+        // Create a response, passing structured input values that match the agent's definitions
+        Map<String, Object> structuredInputValues = new LinkedHashMap<>();
+        structuredInputValues.put("userName", "Alice Smith");
+        structuredInputValues.put("userRole", "Senior Developer");
+
+        Response response = responsesClient.createWithAgentStructuredInput(
+            new AgentReference(agent.getName()).setVersion(agent.getVersion()),
+            structuredInputValues,
+            ResponseCreateParams.builder().input("Hello! Can you confirm my details?")
+        );
+        // END: com.azure.ai.agents.create_response_with_structured_input
+
+        System.out.println("Response: " + response.output());
+
+        // Cleanup
+        agentsClient.deleteAgentVersion(agent.getName(), agent.getVersion());
+    }
+}