Azure AI Persistent Agents for Java: Setup, Usage & Best Practices

The Azure AI Persistent Agents SDK for Java delivers low-level control over persistent agent lifecycles with explicit thread and run management. This SDK exposes the full agent API surface in Java, enabling you to create agents with custom instructions and tools, manage conversation threads, execute runs with polling, and handle responses programmatically.

What This Skill Does

This SDK provides direct access to Azure AI's persistent agent infrastructure from Java applications. You create agents via PersistentAgentsClient, defining their model, instructions, and available tools. Agents persist on Azure and can be reused across multiple conversations. Threads represent individual conversations, storing message history and context. When you create a run, the agent processes the thread's messages, potentially calling tools, and produces responses.

Unlike high-level frameworks that abstract away the agent lifecycle, this SDK requires explicit management of each step. You create threads, add messages to threads, create runs against threads, poll run status until completion, then retrieve response messages. This granularity enables integration with complex business logic, custom error handling, and precise control over agent execution timing.

The SDK supports both synchronous and asynchronous clients. The sync client (PersistentAgentsClient) blocks on API calls, suitable for simple scripts or request-response patterns. The async client (PersistentAgentsAsyncClient) returns reactive types, enabling high-throughput concurrent processing in modern Java applications using Project Reactor or similar frameworks.

Getting Started

Add the SDK dependency to your Maven pom.xml:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-ai-agents-persistent</artifactId>
    <version>1.0.0-beta.1</version>
</dependency>

Configure environment variables:

export PROJECT_ENDPOINT=https://<resource>.services.ai.azure.com/api/projects/<project>
export MODEL_DEPLOYMENT_NAME=gpt-4o-mini

Create a client with Azure authentication:

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();

DefaultAzureCredential handles authentication via Azure CLI (az login), managed identities, service principals, and other Azure identity sources automatically.

Key Features

Persistent Agent Management: Create agents once, reuse across sessions and threads. Agents maintain their configuration (model, instructions, tools) independently of specific conversations.

Thread-Based Conversations: Threads encapsulate conversation history. Create a thread per user session, add messages as users interact, and run agents against threads to generate responses.

Polling-Based Execution: After creating a run, poll its status until completion. This synchronous approach simplifies code flow for batch processing or request-response APIs.

Sync and Async Clients: Choose the client matching your application architecture. Sync client for simple sequential workflows, async client for high-concurrency reactive applications.

Error Handling: Catch HttpResponseException to handle API errors, rate limits, invalid requests, and service unavailability gracefully.

Resource Cleanup: Explicitly delete threads and agents when finished to avoid quota consumption and resource leaks.

Usage Examples

Create Agent and Run Conversation: Basic workflow demonstrating thread and run management:

import com.azure.ai.agents.persistent.*;
import com.azure.ai.agents.persistent.models.*;

String modelName = System.getenv("MODEL_DEPLOYMENT_NAME");

// Create agent
PersistentAgent agent = client.createAgent(
    modelName,
    "Math Tutor",
    "You are a helpful math tutor."
);

// Create thread
PersistentAgentThread thread = client.createThread();

// Add user message
client.createMessage(
    thread.getId(),
    MessageRole.USER,
    "What is 15% of 240?"
);

// Run agent
ThreadRun run = client.createRun(thread.getId(), agent.getId());

// Poll until complete
while (run.getStatus() == RunStatus.QUEUED || run.getStatus() == RunStatus.IN_PROGRESS) {
    Thread.sleep(500);
    run = client.getRun(thread.getId(), run.getId());
}

// Retrieve response
PagedIterable<PersistentThreadMessage> messages = client.listMessages(thread.getId());
for (PersistentThreadMessage message : messages) {
    System.out.println(message.getRole() + ": " + message.getContent());
}

// Cleanup
client.deleteThread(thread.getId());
client.deleteAgent(agent.getId());

Error Handling: Handle API failures gracefully:

import com.azure.core.exception.HttpResponseException;

try {
    PersistentAgent agent = client.createAgent(modelName, "Bot", "You help users.");
} catch (HttpResponseException e) {
    System.err.println("Error: " + e.getResponse().getStatusCode() + " - " + e.getMessage());
    // Implement retry logic, logging, or fallback behavior
}

Using Async Client: For high-concurrency scenarios:

import com.azure.ai.agents.persistent.PersistentAgentsAsyncClient;
import reactor.core.publisher.Mono;

PersistentAgentsAsyncClient asyncClient = new PersistentAgentsClientBuilder()
    .endpoint(endpoint)
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildAsyncClient();

Mono<PersistentAgent> agentMono = asyncClient.createAgent(modelName, "AsyncBot", "Instructions");
agentMono.subscribe(agent -> {
    System.out.println("Created agent: " + agent.getId());
});

Best Practices

Use DefaultAzureCredential in Production: This credential chain supports managed identities, service principals, and environment variables. It's the recommended authentication method for production deployments on Azure.

Poll with Appropriate Delays: Sleep 500ms between status checks. Faster polling wastes API quota; slower polling delays response delivery unnecessarily.

Clean Up Resources: Always delete threads and agents when finished. Orphaned resources consume quota and can cause billing surprises.

Handle All Run Statuses: Check for QUEUED, IN_PROGRESS, REQUIRES_ACTION (for function calling), COMPLETED, FAILED, and CANCELLED. Don't assume runs always complete successfully.

Use Async Client for Throughput: If processing multiple concurrent requests, the async client with reactive streams delivers better throughput than blocking sync calls.

Store Thread IDs: Persist thread IDs in your database to resume conversations across user sessions. Threads maintain message history automatically.

Implement Retry Logic: Handle transient failures (503, 429) with exponential backoff. Azure SDK's built-in retry policies help, but custom logic may be needed for business-specific scenarios.

When to Use / When NOT to Use

Use this SDK when:

• You're building Java applications targeting Azure AI


• You need low-level control over agent execution


• You're integrating agents into existing Java frameworks (Spring, Jakarta EE)


• You need explicit thread and run management


• You're implementing custom conversation persistence logic


• You prefer Java-native SDKs over REST API calls


• You need sync and async execution models

Avoid this SDK when:

• You're working in Python or .NET (use language-specific SDKs)


• You need high-level abstractions (use agent frameworks instead)


• You don't need conversation persistence (use Azure OpenAI client directly)


• You're building simple stateless chatbots


• You prefer declarative configuration over imperative code


• You need streaming responses (this SDK doesn't support streaming in beta.1)

Related Skills

• azure-ai-agents-persistent-dotnet: .NET version of this SDK
• agent-framework-azure-ai-py: Python high-level agent framework
• azure-ai-projects-java: Java SDK for Azure AI project management

Source

Maintained by Microsoft. View on GitHub