diff --git a/doc-samples/agents/c#/azure-ai-agent-sdk/OpenAPI.md b/doc-samples/agents/c#/azure-ai-agent-sdk/OpenAPI.md new file mode 100644 index 000000000..e6952a2f5 --- /dev/null +++ b/doc-samples/agents/c#/azure-ai-agent-sdk/OpenAPI.md @@ -0,0 +1,141 @@ +# Sample using agents with OpenAPI tool in Azure.AI.Agents + +In this example we will demonstrate the possibility to use services with [OpenAPI Specification](https://en.wikipedia.org/wiki/OpenAPI_Specification) with the agent. We will use [wttr.in](https://wttr.in) service to get weather and its specification file [weather_openapi.json](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/ai/Azure.AI.Projects/tests/Samples/Agent/weather_openapi.json). + +1. First get `ProjectEndpoint` and `ModelDeploymentName` from config and create a `PersistentAgentsClient`. Also, create an `OpenApiAnonymousAuthDetails` and `OpenApiToolDefinition` from config. +```C# Snippet:AgentsOpenAPICallingExample_CreateClient +var projectEndpoint = configuration["ProjectEndpoint"]; +var modelDeploymentName = configuration["ModelDeploymentName"]; +var openApiSpec = configuration["OpenApiSpec"]; +PersistentAgentsClient client = new(new Uri(projectEndpoint), new DefaultAzureCredential()); + +var spec = BinaryData.FromBytes(File.ReadAllBytes(openApiSpec)); +OpenApiAnonymousAuthDetails openApiAnonAuth = new(); +OpenApiToolDefinition openApiTool = new( + name: "get_weather", + description: "Retrieve weather information for a location", + spec: spec, + auth: openApiAnonAuth, + defaultParams: ["format"] +); +``` + +2. Next we will need to create an agent. + +Synchronous sample: +```C# Snippet:AgentsOverviewCreateAgentSync +PersistentAgent agent = client.CreateAgent( + model: modelDeploymentName, + name: "Open API Tool Calling Agent", + instructions: "You are a helpful agent.", + tools: [openApiTool] +); +``` + +Asynchronous sample: +```C# Snippet:AgentsOverviewCreateAgent +PersistentAgent agent = await client.CreateAgentAsync( + model: modelDeploymentName, + name: "Open API Tool Calling Agent", + instructions: "You are a helpful agent.", + tools: [openApiTool] +); +``` + +3. Now we will create a `ThreadRun` and wait until it is complete. If the run will not be successful, we will print the last error. + +Synchronous sample: +```C# Snippet:AgentsOpenAPISyncHandlePollingWithRequiredAction +PersistentAgentThread thread = client.CreateThread(); +ThreadMessage message = client.CreateMessage( + thread.Id, + MessageRole.User, + "What's the weather in Seattle?"); + +ThreadRun run = client.CreateRun(thread, agent); + +do +{ + Thread.Sleep(TimeSpan.FromMilliseconds(500)); + run = client.GetRun(thread.Id, run.Id); +} +while (run.Status == RunStatus.Queued + || run.Status == RunStatus.InProgress + || run.Status == RunStatus.RequiresAction); +``` + +Asynchronous sample: +```C# Snippet:AgentsOpenAPIHandlePollingWithRequiredAction +PersistentAgentThread thread = await client.CreateThreadAsync(); +ThreadMessage message = await client.CreateMessageAsync( + thread.Id, + MessageRole.User, + "What's the weather in Seattle?"); + +ThreadRun run = await client.CreateRunAsync(thread, agent); + +do +{ + await Task.Delay(TimeSpan.FromMilliseconds(500)); + run = await client.GetRunAsync(thread.Id, run.Id); +} +while (run.Status == RunStatus.Queued + || run.Status == RunStatus.InProgress + || run.Status == RunStatus.RequiresAction); +``` + +4. Print the messages to the console in chronological order. + +Synchronous sample: +```C# Snippet:AgentsOpenAPISync_Print +PageableList messages = client.GetMessages( + threadId: thread.Id, + order: ListSortOrder.Ascending +); + +foreach (ThreadMessage threadMessage in messages) +{ + foreach (MessageContent contentItem in threadMessage.ContentItems) + { + if (contentItem is MessageTextContent textItem) + { + Console.Write($"{threadMessage.Role}: {textItem.Text}"); + } + Console.WriteLine(); + } +} +``` + +Asynchronous sample: +```C# Snippet:AgentsOpenAPI_Print +PageableList messages = await client.GetMessagesAsync( + threadId: thread.Id, + order: ListSortOrder.Ascending +); + +foreach (ThreadMessage threadMessage in messages) +{ + foreach (MessageContent contentItem in threadMessage.ContentItems) + { + if (contentItem is MessageTextContent textItem) + { + Console.Write($"{threadMessage.Role}: {textItem.Text}"); + } + Console.WriteLine(); + } +} +``` + +5. Finally, we delete all the resources, we have created in this sample. + +Synchronous sample: +```C# Snippet:AgentsOpenAPISync_Cleanup +client.DeleteThread(thread.Id); +client.DeleteAgent(agent.Id); +``` + +Asynchronous sample: +```C# Snippet:AgentsOpenAPI_Cleanup +await client.DeleteThreadAsync(thread.Id); +await client.DeleteAgentAsync(agent.Id); +```