|
| 1 | +# Azure Agents client library for Java |
| 2 | + |
| 3 | +Develop Agents using the Azure AI Foundry platform, leveraging an extensive ecosystem of models, tools, and capabilities from OpenAI, Microsoft, and other LLM providers. |
| 4 | + |
| 5 | +## Documentation |
| 6 | + |
| 7 | +Various documentation is available to help you get started |
| 8 | + |
| 9 | +- [API reference documentation][docs] |
| 10 | +- [Product documentation][product_documentation] |
| 11 | + |
| 12 | +## Getting started |
| 13 | + |
| 14 | +### Prerequisites |
| 15 | + |
| 16 | +- [Java Development Kit (JDK)][jdk] with version 8 or above |
| 17 | +- [Azure Subscription][azure_subscription] |
| 18 | + |
| 19 | +### Adding the package to your product |
| 20 | + |
| 21 | +[//]: # ({x-version-update-start;com.azure:azure-ai-agents;current}) |
| 22 | +```xml |
| 23 | +<dependency> |
| 24 | + <groupId>com.azure</groupId> |
| 25 | + <artifactId>azure-ai-agents</artifactId> |
| 26 | + <version>1.0.0-beta.1</version> |
| 27 | +</dependency> |
| 28 | +``` |
| 29 | +[//]: # ({x-version-update-end}) |
| 30 | + |
| 31 | +### Authentication |
| 32 | + |
| 33 | +[Azure Identity][azure_identity] package provides the default implementation for authenticating the client. |
| 34 | + |
| 35 | +## Key concepts |
| 36 | + |
| 37 | +### Create an AgentsClient |
| 38 | + |
| 39 | +To interact with the Azure Agents service, you'll need to create an instance of the `AgentsClient` class. |
| 40 | + |
| 41 | +```java |
| 42 | +AgentsClient agentsClient = new AgentsClientBuilder() |
| 43 | + .credential(new DefaultAzureCredentialBuilder().build()) |
| 44 | + .endpoint(endpoint) |
| 45 | + .buildClient(); |
| 46 | +``` |
| 47 | + |
| 48 | +Alternatively, you can create an asynchronous client using the `AgentsAsyncClient` class. |
| 49 | + |
| 50 | +```java |
| 51 | +AgentsAsyncClient agentsAsyncClient = new AgentsClientBuilder() |
| 52 | + .credential(new DefaultAzureCredentialBuilder().build()) |
| 53 | + .endpoint(endpoint) |
| 54 | + .buildAsyncClient(); |
| 55 | +``` |
| 56 | + |
| 57 | +The Agents client library has 3 sub-clients which group the different operations that can be performed: |
| 58 | +- `AgentsClient` / `AgentsAsyncClient`: Perform operations related to agents, such as creating, retrieving, updating, and deleting agents. |
| 59 | +- `ConversationsClient` / `ConversationsAsyncClient`: Handle conversation operations. See the [OpenAI's Conversation API documentation][openai_conversations_api_docs] for more information. |
| 60 | +- `ResponsesClient` / `ResponsesAsyncClient`: Handle responses operations. See the [OpenAI's Responses API documentation][openai_responses_api_docs] for more information. |
| 61 | + |
| 62 | +To access each sub-client you need to use your `AgentsClientBuilder()`. The Agents client library takes the [Official OpenAI SDK][openai_java_sdk] as a dependency, which is used for all operations, except the ones corresponding to direct Agent management. |
| 63 | + |
| 64 | +```java |
| 65 | +AgentsClientBuilder builder = new AgentsClientBuilder() |
| 66 | + .credential(new DefaultAzureCredentialBuilder().build()) |
| 67 | + .endpoint(endpoint); |
| 68 | + |
| 69 | +// Agents sub-clients |
| 70 | +AgentsClient agentsClient = builder.buildClient(); |
| 71 | +AgentsAsyncClient agentsAsyncClient = builder.buildAsyncClient(); |
| 72 | +// Conversations sub-clients. |
| 73 | +ConversationsClient conversationsClient = builder.buildConversationsClient(); |
| 74 | +ConversationsAsyncClient conversationsAsyncClient = builder.buildConversationsAsyncClient(); |
| 75 | +// Responses sub-clients. |
| 76 | +ResponsesClient responsesClient = builder.buildResponsesClient(); |
| 77 | +ResponsesAsyncClient responsesAsyncClient = builder.buildResponsesAsyncClient(); |
| 78 | +``` |
| 79 | + |
| 80 | +The [OpenAI Official Java SDK][openai_java_sdk] is imported transitively and can be accessed from either the `ResponsesClient` or the `ConversationsClient` using the `getOpenAIClient()` method. |
| 81 | + |
| 82 | +```java |
| 83 | +// OpenAI SDK ResponsesService accessed from ResponsesClient |
| 84 | +ResponsesClient responsesClient = builder.buildResponsesClient(); |
| 85 | +ResponsesService responsesService = responsesClient.getOpenAIClient(); |
| 86 | + |
| 87 | +// OpenAI SDK ConversationService accessed from ConversationsClient |
| 88 | +ConversationsClient conversationsClient = builder.buildConversationsClient(); |
| 89 | +ConversationService conversationService = conversationsClient.getOpenAIClient(); |
| 90 | +``` |
| 91 | + |
| 92 | +### Using OpenAI's official library |
| 93 | + |
| 94 | +If you prefer using the [OpenAI official Java client library][openai_java_sdk] instead, you can do so by including that dependency in your project instead and following the instructions in the linked repository. Additionally, you will have to set up your `OpenAIClient` as shown below: |
| 95 | + |
| 96 | +```java com.azure.ai.agents.openai_official_library |
| 97 | +OpenAIClient client = OpenAIOkHttpClient.builder() |
| 98 | + .baseUrl(endpoint.endsWith("/") ? endpoint + "openai" : endpoint + "/openai") |
| 99 | + .azureUrlPathMode(AzureUrlPathMode.UNIFIED) |
| 100 | + .credential(BearerTokenCredential.create(AuthenticationUtil.getBearerTokenSupplier( |
| 101 | + new DefaultAzureCredentialBuilder().build(), "https://ai.azure.com/.default"))) |
| 102 | + .azureServiceVersion(AzureOpenAIServiceVersion.fromString("2025-11-15-preview")) |
| 103 | + .build(); |
| 104 | + |
| 105 | +ResponseCreateParams responseRequest = new ResponseCreateParams.Builder() |
| 106 | + .input("Hello, how can you help me?") |
| 107 | + .model(model) |
| 108 | + .build(); |
| 109 | + |
| 110 | +Response result = client.responses().create(responseRequest); |
| 111 | +``` |
| 112 | + |
| 113 | +Remember to adjust your value for the `AzureOpenAIServiceVersion` in the builder and to postpend to your `endpoint`'s path `openai` (if it's not already there) like it's shown in the above code snippet. |
| 114 | + |
| 115 | +## Examples |
| 116 | + |
| 117 | +### Prompt Agent |
| 118 | + |
| 119 | +This example will show how to create the context necessary for a `PromptAgent` to work. Note that the way that context is handled in this scenario would allow you to share the context with multiple agents. |
| 120 | + |
| 121 | +#### Create an Agent |
| 122 | + |
| 123 | +Creating an Agent can be done like in the following code snippet: |
| 124 | + |
| 125 | +```java com.azure.ai.agents.create_prompt_agent |
| 126 | +PromptAgentDefinition promptAgentDefinition = new PromptAgentDefinition("gpt-4o"); |
| 127 | +AgentVersionDetails agent = agentsClient.createAgentVersion("my-agent", promptAgentDefinition); |
| 128 | +``` |
| 129 | + |
| 130 | +This will return an `AgentVersionObject` which contains the information necessary to create an `AgentReference`. But first it's necessary to setup the `Conversation` and its messages to be able to obtain `Response`s with a centralized context. |
| 131 | + |
| 132 | +#### Create conversation |
| 133 | + |
| 134 | +First we need to create our `Conversation` object so we can attach items to it: |
| 135 | + |
| 136 | +```java com.azure.ai.agents.create_conversation |
| 137 | +Conversation conversation = conversationsClient.getConversationService().create(); |
| 138 | +``` |
| 139 | + |
| 140 | +With `conversation.id()` contains the reference we will use to append messages to this `Conversation`. `Conversation` objects can be used by multiple agents and serve the purpose of being a centralized source of context. To add items: |
| 141 | + |
| 142 | +```java com.azure.ai.agents.add_message_to_conversation |
| 143 | +conversationsClient.getConversationService().items().create( |
| 144 | + ItemCreateParams.builder() |
| 145 | + .conversationId(conversation.id()) |
| 146 | + .addItem(EasyInputMessage.builder() |
| 147 | + .role(EasyInputMessage.Role.SYSTEM) |
| 148 | + .content("You are a helpful assistant that speaks like a pirate.") |
| 149 | + .build() |
| 150 | + ).addItem(EasyInputMessage.builder() |
| 151 | + .role(EasyInputMessage.Role.USER) |
| 152 | + .content("Hello, agent!") |
| 153 | + .build() |
| 154 | + ).build() |
| 155 | +); |
| 156 | +``` |
| 157 | + |
| 158 | +#### Text generation with Responses |
| 159 | + |
| 160 | +And the final step that ties everything together, we pass the `AgentReference` and the `conversation.id()` as parameters for the `Response` creation: |
| 161 | + |
| 162 | +```java com.azure.ai.agents.create_response |
| 163 | +AgentReference agentReference = new AgentReference(agent.getName()).setVersion(agent.getVersion()); |
| 164 | +Response response = responsesClient.createWithAgentConversation(agentReference, conversation.id()); |
| 165 | +``` |
| 166 | + |
| 167 | +### Service API versions |
| 168 | + |
| 169 | +The client library targets the latest service API version by default. |
| 170 | +The service client builder accepts an optional service API version parameter to specify which API version to communicate. |
| 171 | + |
| 172 | +#### Select a service API version |
| 173 | + |
| 174 | +You have the flexibility to explicitly select a supported service API version when initializing a service client via the service client builder. |
| 175 | +This ensures that the client can communicate with services using the specified API version. |
| 176 | + |
| 177 | +When selecting an API version, it is important to verify that there are no breaking changes compared to the latest API version. |
| 178 | +If there are significant differences, API calls may fail due to incompatibility. |
| 179 | + |
| 180 | +Always ensure that the chosen API version is fully supported and operational for your specific use case and that it aligns with the service's versioning policy. |
| 181 | + |
| 182 | +## Troubleshooting |
| 183 | + |
| 184 | +## Next steps |
| 185 | + |
| 186 | +## Contributing |
| 187 | + |
| 188 | +For details on contributing to this repository, see the [contributing guide](https://github.com/Azure/azure-sdk-for-java/blob/main/CONTRIBUTING.md). |
| 189 | + |
| 190 | +1. Fork it |
| 191 | +1. Create your feature branch (`git checkout -b my-new-feature`) |
| 192 | +1. Commit your changes (`git commit -am 'Add some feature'`) |
| 193 | +1. Push to the branch (`git push origin my-new-feature`) |
| 194 | +1. Create new Pull Request |
| 195 | + |
| 196 | +<!-- LINKS --> |
| 197 | +[product_documentation]: https://aka.ms/azsdk/azure-ai-agents/product-doc |
| 198 | +[docs]: https://azure.github.io/azure-sdk-for-java/ |
| 199 | +[jdk]: https://learn.microsoft.com/azure/developer/java/fundamentals/ |
| 200 | +[azure_subscription]: https://azure.microsoft.com/free/ |
| 201 | +[azure_identity]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/identity/azure-identity |
| 202 | +[openai_java_sdk]: https://github.com/openai/openai-java/ |
| 203 | +[openai_responses_api_docs]: https://platform.openai.com/docs/api-reference/responses |
| 204 | +[openai_conversations_api_docs]: https://platform.openai.com/docs/api-reference/conversations |
0 commit comments