Skill v1.0.0
currentAutomated scan100/100name: 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. risk: critical source: community date_added: '2026-02-27' metadata: version: "1.0.0"
Azure AI Agents Persistent SDK for Java
Low-level SDK for creating and managing persistent AI agents with threads, messages, runs, and tools.
Installation
<dependency><groupId>com.azure</groupId><artifactId>azure-ai-agents-persistent</artifactId><version>1.0.0-beta.2</version></dependency>
Environment Variables
export PROJECT_ENDPOINT="https://<resource>.services.ai.azure.com/api/projects/<project>"export MODEL_DEPLOYMENT_NAME="gpt-4o-mini"
Authentication
import com.azure.ai.agents.persistent.PersistentAgentsClient;import com.azure.ai.agents.persistent.PersistentAgentsClientBuilder;import com.azure.ai.agents.persistent.*;import com.azure.ai.agents.persistent.models.*;import com.azure.core.http.rest.PagedIterable;import com.azure.identity.DefaultAzureCredentialBuilder;String endpoint = System.getenv("PROJECT_ENDPOINT");PersistentAgentsClient client = new PersistentAgentsClientBuilder().endpoint(endpoint).credential(new DefaultAzureCredentialBuilder().build()).buildClient();String modelDeploymentName = System.getenv("MODEL_DEPLOYMENT_NAME");PersistentAgentsAdministrationClient administration = client.getPersistentAgentsAdministrationClient();ThreadsClient threads = client.getThreadsClient();MessagesClient messageClient = client.getMessagesClient();RunsClient runs = client.getRunsClient();
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
// Create agent with toolsPersistentAgent agent = administration.createAgent(new CreateAgentOptions(modelDeploymentName).setName("Math Tutor").setInstructions("You are a personal math tutor."));
2. Create Thread
PersistentAgentThread thread = threads.createThread();
3. Add Message
messageClient.createMessage(thread.getId(),MessageRole.USER,"I need help with equations.");
4. Run Agent
ThreadRun run = runs.createRun(new CreateRunOptions(thread.getId(), agent.getId()));// Bound polling; a terminal non-success state is not a completed answer.long deadline = System.nanoTime() + java.util.concurrent.TimeUnit.SECONDS.toNanos(60);while (run.getStatus() == RunStatus.QUEUED || run.getStatus() == RunStatus.IN_PROGRESS) {if (System.nanoTime() > deadline) {throw new IllegalStateException("Run polling timed out; inspect/cancel the owned run separately");}Thread.sleep(500);run = runs.getRun(thread.getId(), run.getId());}
Check the resulting status before reading a final response: requires_action needs an authorized tool-output handler; failed, cancelled, expired or other non-success states must be reported explicitly. A polling timeout does not cancel the cloud run.
5. Get Response
PagedIterable<ThreadMessage> messages = messageClient.listMessages(thread.getId());for (ThreadMessage message : messages) {System.out.println("Message role: " + message.getRole()); // Do not log retained prompt/response payloads.}
6. Cleanup
threads.deleteThread(thread.getId());administration.deleteAgent(agent.getId());
Best Practices
- Use DefaultAzureCredential for production authentication
- Poll with appropriate delays — 500ms recommended between status checks
- Clean up resources — Delete threads and agents when done
- Handle all run statuses — Check for RequiresAction, Failed, Cancelled
- Use async client for better throughput in high-concurrency scenarios
Error Handling
import com.azure.core.exception.HttpResponseException;try {PersistentAgent exampleAgent = administration.createAgent(new CreateAgentOptions(modelDeploymentName).setName("Example").setInstructions("Answer briefly"));} 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 |
When to Use
Use when implementing or maintaining Java persistent-agent threads, messages, runs and administration with the preview SDK. The reviewed example uses beta.2 subclients, not direct CRUD methods on PersistentAgentsClient.
Limitations
- Operations create billable cloud resources, send prompts and retain thread data. Use an authorized project/model and explicit budgets; delete only resources created for the current run, preserve IDs on failure, and redact message/credential logs.
- Snippets are sequential fragments inside application code, not a standalone compiled program. API shape was checked against Microsoft’s beta.2 sample and preview reference; no cloud run was performed. Add compatible azure-identity and required dependencies using the project’s reviewed Azure BOM.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.