OpenAPI Tool samples and tests

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_34d0d1c5d4"
+  "Tag": "java/ai/azure-ai-agents_69bc682982"
 }

sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/OpenApiFunctionDefinition.java

@@ -6,11 +6,14 @@
 import com.azure.core.annotation.Fluent;
 import com.azure.core.annotation.Generated;
 import com.azure.core.util.BinaryData;
+import com.azure.json.JsonProviders;
 import com.azure.json.JsonReader;
 import com.azure.json.JsonSerializable;
 import com.azure.json.JsonToken;
 import com.azure.json.JsonWriter;
 import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
 import java.util.List;
 import java.util.Map;
 
@@ -197,6 +200,22 @@ public OpenApiFunctionDefinition(String name, Map<String, BinaryData> spec, Open
         this.auth = auth;
     }
 
+    /**
+     * Reads an OpenAPI specification from a JSON file and returns it as a {@code Map<String, BinaryData>}
+     * suitable for the {@code spec} parameter of
+     * {@link #OpenApiFunctionDefinition(String, Map, OpenApiAuthDetails)}.
+     *
+     * @param path the path to the OpenAPI spec JSON file.
+     * @return the spec as a map of top-level keys to their serialized values.
+     * @throws IOException if the file cannot be read or parsed.
+     */
+    public static Map<String, BinaryData> readSpecFromFile(Path path) throws IOException {
+        try (JsonReader reader = JsonProviders.createReader(Files.readAllBytes(path))) {
+            return reader
+                .readMap(r -> r.getNullable(nonNullReader -> BinaryData.fromObject(nonNullReader.readUntyped())));
+        }
+    }
+
     /*
      * List of OpenAPI spec parameters that will use user-provided defaults
      */

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

@@ -0,0 +1,29 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.azure.ai.agents;
+
+import java.net.URISyntaxException;
+import java.net.URL;
+import java.nio.file.Path;
+import java.nio.file.Paths;
+
+public class SampleUtils {
+
+    /**
+     * Gets the path to a file in the sample resource folder.
+     * @param fileName the name of the file in the sample resource folder
+     * @return Path to the sample resource file
+     */
+    public static Path getResourcePath(String fileName) {
+        try {
+            URL resourceUrl = SampleUtils.class.getClassLoader().getResource(fileName);
+            if (resourceUrl == null) {
+                throw new RuntimeException("Sample resource file not found: " + fileName);
+            }
+            return Paths.get(resourceUrl.toURI());
+        } catch (URISyntaxException e) {
+            throw new RuntimeException("Invalid URI for sample resource: " + fileName, e);
+        }
+    }
+}

sdk/ai/azure-ai-agents/src/samples/java/com/azure/ai/agents/tools/OpenApiSample.java

@@ -0,0 +1,109 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.azure.ai.agents.tools;
+
+import com.azure.ai.agents.AgentsClient;
+import com.azure.ai.agents.AgentsClientBuilder;
+import com.azure.ai.agents.ConversationsClient;
+import com.azure.ai.agents.ResponsesClient;
+import com.azure.ai.agents.SampleUtils;
+import com.azure.ai.agents.models.AgentReference;
+import com.azure.ai.agents.models.AgentVersionDetails;
+import com.azure.ai.agents.models.OpenApiAnonymousAuthDetails;
+import com.azure.ai.agents.models.OpenApiFunctionDefinition;
+import com.azure.ai.agents.models.OpenApiTool;
+import com.azure.ai.agents.models.PromptAgentDefinition;
+import com.azure.core.util.BinaryData;
+import com.azure.core.util.Configuration;
+import com.azure.identity.DefaultAzureCredentialBuilder;
+import com.openai.models.conversations.Conversation;
+import com.openai.models.conversations.items.ItemCreateParams;
+import com.openai.models.responses.EasyInputMessage;
+import com.openai.models.responses.Response;
+import com.openai.models.responses.ResponseCreateParams;
+
+import java.util.Arrays;
+import java.util.Map;
+
+/**
+ * This sample demonstrates how to create an agent with an OpenAPI tool that calls
+ * an external API defined by an OpenAPI specification file.
+ *
+ * <p>Before running the sample, set these environment variables:</p>
+ * <ul>
+ *   <li>FOUNDRY_PROJECT_ENDPOINT - The Azure AI Project endpoint.</li>
+ *   <li>FOUNDRY_MODEL_DEPLOYMENT_NAME - The model deployment name.</li>
+ * </ul>
+ *
+ * <p>Also place an OpenAPI spec JSON file at {@code src/samples/resources/assets/httpbin_openapi.json}.</p>
+ */
+public class OpenApiSample {
+    public static void main(String[] args) throws Exception {
+        String endpoint = Configuration.getGlobalConfiguration().get("FOUNDRY_PROJECT_ENDPOINT");
+        String model = Configuration.getGlobalConfiguration().get("FOUNDRY_MODEL_DEPLOYMENT_NAME");
+
+        AgentsClientBuilder builder = new AgentsClientBuilder()
+            .credential(new DefaultAzureCredentialBuilder().build())
+            .endpoint(endpoint);
+
+        AgentsClient agentsClient = builder.buildAgentsClient();
+        ResponsesClient responsesClient = builder.buildResponsesClient();
+        ConversationsClient conversationsClient = builder.buildConversationsClient();
+
+
+        // Load the OpenAPI spec from a JSON file
+        Map<String, BinaryData> spec = OpenApiFunctionDefinition.readSpecFromFile(
+            SampleUtils.getResourcePath("assets/httpbin_openapi.json"));
+
+        OpenApiFunctionDefinition toolDefinition = new OpenApiFunctionDefinition(
+            "httpbin_get",
+            spec,
+            new OpenApiAnonymousAuthDetails())
+            .setDescription("Get request metadata from an OpenAPI endpoint.");
+
+        PromptAgentDefinition agentDefinition = new PromptAgentDefinition(model)
+            .setInstructions("Use the OpenAPI tool for HTTP request metadata.")
+            .setTools(Arrays.asList(new OpenApiTool(toolDefinition)));
+
+        AgentVersionDetails agentVersion = agentsClient.createAgentVersion("openapi-agent", agentDefinition);
+        System.out.println("Agent: " + agentVersion.getName() + ", version: " + agentVersion.getVersion());
+
+        // Create a conversation and add a user message
+        Conversation conversation = conversationsClient.getConversationService().create();
+        conversationsClient.getConversationService().items().create(
+            ItemCreateParams.builder()
+                .conversationId(conversation.id())
+                .addItem(EasyInputMessage.builder()
+                    .role(EasyInputMessage.Role.USER)
+                    .content("Use the OpenAPI tool and summarize the returned URL and origin in one sentence.")
+                    .build())
+                .build());
+
+        try {
+            AgentReference agentReference = new AgentReference(agentVersion.getName())
+                .setVersion(agentVersion.getVersion());
+
+            ResponseCreateParams.Builder options = ResponseCreateParams.builder()
+                .maxOutputTokens(300L);
+
+            Response response = responsesClient.createWithAgentConversation(
+                agentReference, conversation.id(), options);
+
+            String text = response.output().stream()
+                .filter(item -> item.isMessage())
+                .map(item -> item.asMessage().content()
+                    .get(item.asMessage().content().size() - 1)
+                    .asOutputText()
+                    .text())
+                .reduce((first, second) -> second)
+                .orElse("<no message output>");
+
+            System.out.println("Status: " + response.status().map(Object::toString).orElse("unknown"));
+            System.out.println("Response: " + text);
+        } finally {
+            agentsClient.deleteAgentVersion(agentVersion.getName(), agentVersion.getVersion());
+            System.out.println("Agent deleted");
+        }
+    }
+}

sdk/ai/azure-ai-agents/src/samples/resources/assets/httpbin_openapi.json

@@ -0,0 +1,39 @@
+{
+  "openapi": "3.0.0",
+  "info": {
+    "title": "httpbin",
+    "version": "1.0.0",
+    "description": "A simple HTTP request/response service"
+  },
+  "servers": [
+    {
+      "url": "https://httpbin.org"
+    }
+  ],
+  "paths": {
+    "/get": {
+      "get": {
+        "operationId": "httpbin_get",
+        "summary": "Returns the GET request data including headers, origin IP, and URL",
+        "responses": {
+          "200": {
+            "description": "Successful response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "args": { "type": "object" },
+                    "headers": { "type": "object" },
+                    "origin": { "type": "string" },
+                    "url": { "type": "string" }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

sdk/ai/azure-ai-agents/src/test/java/com/azure/ai/agents/OpenAPIToolTests.java

@@ -0,0 +1,93 @@
+// 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.OpenApiAnonymousAuthDetails;
+import com.azure.ai.agents.models.OpenApiFunctionDefinition;
+import com.azure.ai.agents.models.OpenApiTool;
+import com.azure.ai.agents.models.PromptAgentDefinition;
+import com.azure.core.http.HttpClient;
+import com.azure.core.util.BinaryData;
+import com.openai.models.conversations.Conversation;
+import com.openai.models.conversations.items.ItemCreateParams;
+import com.openai.models.responses.EasyInputMessage;
+import com.openai.models.responses.Response;
+import com.openai.models.responses.ResponseCreateParams;
+import com.openai.models.responses.ResponseStatus;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.MethodSource;
+
+import java.io.IOException;
+import java.util.Arrays;
+import java.util.Map;
+
+import static com.azure.ai.agents.TestUtils.DISPLAY_NAME_WITH_ARGUMENTS;
+import static org.junit.jupiter.api.Assertions.*;
+
+public class OpenAPIToolTests extends ClientTestBase {
+
+    private static final String AGENT_NAME = "openapi-tool-test-agent-java";
+
+    @ParameterizedTest(name = DISPLAY_NAME_WITH_ARGUMENTS)
+    @MethodSource("com.azure.ai.agents.TestUtils#getTestParameters")
+    public void openApiToolEndToEnd(HttpClient httpClient, AgentsServiceVersion serviceVersion) throws IOException {
+        AgentsClient agentsClient = getAgentsSyncClient(httpClient, serviceVersion);
+        ResponsesClient responsesClient = getResponsesSyncClient(httpClient, serviceVersion);
+        ConversationsClient conversationsClient = getConversationsSyncClient(httpClient, serviceVersion);
+
+        // Load the OpenAPI spec from test resources
+        Map<String, BinaryData> spec
+            = OpenApiFunctionDefinition.readSpecFromFile(TestUtils.getTestResourcePath("assets/httpbin_openapi.json"));
+
+        OpenApiFunctionDefinition toolDefinition
+            = new OpenApiFunctionDefinition("httpbin_get", spec, new OpenApiAnonymousAuthDetails())
+                .setDescription("Get request metadata from an OpenAPI endpoint.");
+
+        PromptAgentDefinition agentDefinition
+            = new PromptAgentDefinition("gpt-4o").setInstructions("Use the OpenAPI tool for HTTP request metadata.")
+                .setTools(Arrays.asList(new OpenApiTool(toolDefinition)));
+
+        AgentVersionDetails agentVersion = agentsClient.createAgentVersion(AGENT_NAME, agentDefinition);
+        assertNotNull(agentVersion);
+        assertNotNull(agentVersion.getId());
+        assertEquals(AGENT_NAME, agentVersion.getName());
+
+        try {
+            // Create a conversation and add a user message
+            Conversation conversation = conversationsClient.getConversationService().create();
+            assertNotNull(conversation);
+            assertNotNull(conversation.id());
+
+            conversationsClient.getConversationService()
+                .items()
+                .create(ItemCreateParams.builder()
+                    .conversationId(conversation.id())
+                    .addItem(EasyInputMessage.builder()
+                        .role(EasyInputMessage.Role.USER)
+                        .content("Use the OpenAPI tool and summarize the returned URL and origin in one sentence.")
+                        .build())
+                    .build());
+
+            // Create a response using the agent with the conversation
+            AgentReference agentReference
+                = new AgentReference(agentVersion.getName()).setVersion(agentVersion.getVersion());
+
+            ResponseCreateParams.Builder options = ResponseCreateParams.builder().maxOutputTokens(300L);
+
+            Response response = responsesClient.createWithAgentConversation(agentReference, conversation.id(), options);
+
+            assertNotNull(response);
+            assertTrue(response.id().startsWith("resp"));
+            assertTrue(response.status().isPresent());
+            assertEquals(ResponseStatus.COMPLETED, response.status().get());
+            assertFalse(response.output().isEmpty());
+            assertTrue(response.output().stream().anyMatch(item -> item.isMessage()));
+        } finally {
+            // Clean up
+            agentsClient.deleteAgentVersion(agentVersion.getName(), agentVersion.getVersion());
+        }
+    }
+}

sdk/ai/azure-ai-agents/src/test/resources/assets/httpbin_openapi.json

@@ -0,0 +1,39 @@
+{
+  "openapi": "3.0.0",
+  "info": {
+    "title": "httpbin",
+    "version": "1.0.0",
+    "description": "A simple HTTP request/response service"
+  },
+  "servers": [
+    {
+      "url": "https://httpbin.org"
+    }
+  ],
+  "paths": {
+    "/get": {
+      "get": {
+        "operationId": "httpbin_get",
+        "summary": "Returns the GET request data including headers, origin IP, and URL",
+        "responses": {
+          "200": {
+            "description": "Successful response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "args": { "type": "object" },
+                    "headers": { "type": "object" },
+                    "origin": { "type": "string" },
+                    "url": { "type": "string" }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}