Azure AI Agents Persistent Java

1---
2name: azure-ai-agents-persistent-java
3description: |
4  Azure AI Agents Persistent SDK for Java. Low-level SDK for creating and managing AI agents with threads, messages, runs, and tools.
5  Triggers: "PersistentAgentsClient", "persistent agents java", "agent threads java", "agent runs java", "streaming agents java".
6package: com.azure:azure-ai-agents-persistent
7---
8 
9# Azure AI Agents Persistent SDK for Java
10 
11Low-level SDK for creating and managing persistent AI agents with threads, messages, runs, and tools.
12 
13## Installation
14 
15```xml
16<dependency>
17    <groupId>com.azure</groupId>
18    <artifactId>azure-ai-agents-persistent</artifactId>
19    <version>1.0.0-beta.1</version>
20</dependency>
21```
22 
23## Environment Variables
24 
25```bash
26PROJECT_ENDPOINT=https://<resource>.services.ai.azure.com/api/projects/<project>
27MODEL_DEPLOYMENT_NAME=gpt-4o-mini
28```
29 
30## Authentication
31 
32```java
33import com.azure.ai.agents.persistent.PersistentAgentsClient;
34import com.azure.ai.agents.persistent.PersistentAgentsClientBuilder;
35import com.azure.identity.DefaultAzureCredentialBuilder;
36 
37String endpoint = System.getenv("PROJECT_ENDPOINT");
38PersistentAgentsClient client = new PersistentAgentsClientBuilder()
39    .endpoint(endpoint)
40    .credential(new DefaultAzureCredentialBuilder().build())
41    .buildClient();
42```
43 
44## Key Concepts
45 
46The Azure AI Agents Persistent SDK provides a low-level API for managing persistent agents that can be reused across sessions.
47 
48### Client Hierarchy
49 
50| Client | Purpose |
51|--------|---------|
52| `PersistentAgentsClient` | Sync client for agent operations |
53| `PersistentAgentsAsyncClient` | Async client for agent operations |
54 
55## Core Workflow
56 
57### 1. Create Agent
58 
59```java
60// Create agent with tools
61PersistentAgent agent = client.createAgent(
62    modelDeploymentName,
63    "Math Tutor",
64    "You are a personal math tutor."
65);
66```
67 
68### 2. Create Thread
69 
70```java
71PersistentAgentThread thread = client.createThread();
72```
73 
74### 3. Add Message
75 
76```java
77client.createMessage(
78    thread.getId(),
79    MessageRole.USER,
80    "I need help with equations."
81);
82```
83 
84### 4. Run Agent
85 
86```java
87ThreadRun run = client.createRun(thread.getId(), agent.getId());
88 
89// Poll for completion
90while (run.getStatus() == RunStatus.QUEUED || run.getStatus() == RunStatus.IN_PROGRESS) {
91    Thread.sleep(500);
92    run = client.getRun(thread.getId(), run.getId());
93}
94```
95 
96### 5. Get Response
97 
98```java
99PagedIterable<PersistentThreadMessage> messages = client.listMessages(thread.getId());
100for (PersistentThreadMessage message : messages) {
101    System.out.println(message.getRole() + ": " + message.getContent());
102}
103```
104 
105### 6. Cleanup
106 
107```java
108client.deleteThread(thread.getId());
109client.deleteAgent(agent.getId());
110```
111 
112## Best Practices
113 
1141. **Use DefaultAzureCredential** for production authentication
1152. **Poll with appropriate delays** — 500ms recommended between status checks
1163. **Clean up resources** — Delete threads and agents when done
1174. **Handle all run statuses** — Check for RequiresAction, Failed, Cancelled
1185. **Use async client** for better throughput in high-concurrency scenarios
119 
120## Error Handling
121 
122```java
123import com.azure.core.exception.HttpResponseException;
124 
125try {
126    PersistentAgent agent = client.createAgent(modelName, name, instructions);
127} catch (HttpResponseException e) {
128    System.err.println("Error: " + e.getResponse().getStatusCode() + " - " + e.getMessage());
129}
130```
131 
132## Reference Links
133 
134| Resource | URL |
135|----------|-----|
136| Maven Package | https://central.sonatype.com/artifact/com.azure/azure-ai-agents-persistent |
137| GitHub Source | https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/ai/azure-ai-agents-persistent |
138