Manage Persistent AI Agents in Java

This skill covers the Azure AI Agents Persistent SDK for Java, a low-level API for creating and managing persistent AI agents that can be reused across sessions via threads, messages, runs, and tools. It walks through the client hierarchy (PersistentAgentsClient for sync operations, PersistentAgentsAsyncClient for async) and the core workflow: create an agent bound to a model deployment with a name and instructions, create a thread, add a user message to that thread, create a run against the thread and agent, poll the run status until it leaves QUEUED or IN_PROGRESS, list the resulting messages, then delete the thread and agent to clean up. It also lists best practices: use DefaultAzureCredential for production authentication, poll with the recommended 500ms delay between status checks, always clean up threads and agents when done, check for RequiresAction/Failed/Cancelled run statuses rather than only the happy path, and prefer the async client for better throughput under high concurrency.

Use it when building or maintaining a Java integration against Azure's persistent-agent API - authentication via DefaultAzureCredential, the create-agent/create-thread/add-message/run/poll/cleanup lifecycle, or error handling for HttpResponseException. It documents a low-level SDK, not a higher-level agent framework, so reach for it when you want direct control over threads, messages, and runs rather than an abstraction layered on top of them.

Configuration is two environment variables: PROJECT_ENDPOINT (the Azure AI Foundry project endpoint URL) and MODEL_DEPLOYMENT_NAME (for example gpt-4o-mini). The Maven dependency is com.azure:azure-ai-agents-persistent:1.0.0-beta.1. A minimal client looks like this:

String endpoint = System.getenv("PROJECT_ENDPOINT");
PersistentAgentsClient client = new PersistentAgentsClientBuilder()
    .endpoint(endpoint)
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

Output at each step is a client-side object: a PersistentAgent from createAgent, a PersistentAgentThread from createThread, a ThreadRun from createRun (polled via getRun until its RunStatus leaves QUEUED or IN_PROGRESS), and a paged iterable of PersistentThreadMessage from listMessages once the run finishes. Errors surface as an HttpResponseException carrying an HTTP status code and message, which callers should catch around calls like createAgent.

Built on Azure Identity's DefaultAzureCredentialBuilder for production authentication, and distributed via the Maven Central com.azure:azure-ai-agents-persistent artifact, with source in the Azure/azure-sdk-for-java GitHub repository.

Java developers building on Azure AI Foundry who need direct, low-level control over agent threads, messages, and runs - including handling RequiresAction, Failed, and Cancelled run statuses, and choosing the async client for higher-concurrency workloads - rather than a pre-built orchestration layer.