--- name: azure-ai-agents-persistent-java description: | Azure AI Agents Persistent SDK for Java. Low-level SDK for creating and managing AI agents with threads, messages, runs, and tools. Triggers: "PersistentAgentsClient", "persistent agents java", "agent threads java", "agent runs java", "streaming agents java". package: com.azure:azure-ai-agents-persistent --- # Azure AI Agents Persistent SDK for Java Low-level SDK for creating and managing persistent AI agents with threads, messages, runs, and tools. ## Installation ```xml com.azure<\/groupId> azure-ai-agents-persistent<\/artifactId> 1.0.0-beta.1<\/version> <\/dependency> ``` ## Environment Variables ```bash PROJECT_ENDPOINT=https:\/\/.services.ai.azure.com\/api\/projects\/ MODEL_DEPLOYMENT_NAME=gpt-4o-mini ``` ## Authentication ```java import com.azure.ai.agents.persistent.PersistentAgentsClient; import com.azure.ai.agents.persistent.PersistentAgentsClientBuilder; import com.azure.identity.DefaultAzureCredentialBuilder; String endpoint = System.getenv("PROJECT_ENDPOINT"); PersistentAgentsClient client = new PersistentAgentsClientBuilder() .endpoint(endpoint) .credential(new DefaultAzureCredentialBuilder().build()) .buildClient(); ``` ## Key Concepts The Azure AI Agents Persistent SDK provides a low-level API for managing persistent agents that can be reused across sessions. ### Client Hierarchy | Client | Purpose | |--------|---------| | `PersistentAgentsClient` | Sync client for agent operations | | `PersistentAgentsAsyncClient` | Async client for agent operations | ## Core Workflow ### 1. Create Agent ```java \/\/ Create agent with tools PersistentAgent agent = client.createAgent( modelDeploymentName, "Math Tutor", "You are a personal math tutor." ); ``` ### 2. Create Thread ```java PersistentAgentThread thread = client.createThread(); ``` ### 3. Add Message ```java client.createMessage( thread.getId(), MessageRole.USER, "I need help with equations." ); ``` ### 4. Run Agent ```java ThreadRun run = client.createRun(thread.getId(), agent.getId()); \/\/ Poll for completion while (run.getStatus() == RunStatus.QUEUED || run.getStatus() == RunStatus.IN_PROGRESS) { Thread.sleep(500); run = client.getRun(thread.getId(), run.getId()); } ``` ### 5. Get Response ```java PagedIterable messages = client.listMessages(thread.getId()); for (PersistentThreadMessage message : messages) { System.out.println(message.getRole() + ": " + message.getContent()); } ``` ### 6. Cleanup ```java client.deleteThread(thread.getId()); client.deleteAgent(agent.getId()); ``` ## Best Practices 1. **Use DefaultAzureCredential** for production authentication 2. **Poll with appropriate delays** — 500ms recommended between status checks 3. **Clean up resources** — Delete threads and agents when done 4. **Handle all run statuses** — Check for RequiresAction, Failed, Cancelled 5. **Use async client** for better throughput in high-concurrency scenarios ## Error Handling ```java import com.azure.core.exception.HttpResponseException; try { PersistentAgent agent = client.createAgent(modelName, name, instructions); } catch (HttpResponseException e) { System.err.println("Error: " + e.getResponse().getStatusCode() + " - " + e.getMessage()); } ``` ## Reference Links | Resource | URL | |----------|-----| | Maven Package | https:\/\/central.sonatype.com\/artifact\/com.azure\/azure-ai-agents-persistent | | GitHub Source | https:\/\/github.com\/Azure\/azure-sdk-for-java\/tree\/main\/sdk\/ai\/azure-ai-agents-persistent |