azure-ai-agents-persistent-java
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".
Install
npx skills add https://github.com/microsoft/skills/tree/main/.github/plugins/azure-sdk-java/skills/azure-ai-agents-persistent-java
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install microsoft-skills@llmmart
git clone https://github.com/microsoft/skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole microsoft/skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
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.1</version>
</dependency>
Environment Variables
PROJECT_ENDPOINT=https://<resource>.services.ai.azure.com/api/projects/<project> # Required for project configuration
MODEL_DEPLOYMENT_NAME=gpt-4o-mini # Required for agent model selection
AZURE_TOKEN_CREDENTIALS=prod # Required only if DefaultAzureCredential is used in production
Authentication
import com.azure.ai.agents.persistent.PersistentAgentsClient;
import com.azure.ai.agents.persistent.PersistentAgentsClientBuilder;
import com.azure.core.credential.TokenCredential;
import com.azure.identity.AzureIdentityEnvVars;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.identity.ManagedIdentityCredentialBuilder;
String endpoint = System.getenv("PROJECT_ENDPOINT");
TokenCredential credential = new DefaultAzureCredentialBuilder()
.requireEnvVars(AzureIdentityEnvVars.AZURE_TOKEN_CREDENTIALS)
.build();
// Or use a specific credential directly in production:
// See https://learn.microsoft.com/java/api/overview/azure/identity-readme?view=azure-java-stable#credential-classes
// TokenCredential credential = new ManagedIdentityCredentialBuilder().build();
PersistentAgentsClient client = new PersistentAgentsClientBuilder()
.endpoint(endpoint)
.credential(credential)
.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
// Create agent with tools
PersistentAgent agent = client.createAgent(
modelDeploymentName,
"Math Tutor",
"You are a personal math tutor."
);
2. Create Thread
PersistentAgentThread thread = client.createThread();
3. Add Message
client.createMessage(
thread.getId(),
MessageRole.USER,
"I need help with equations."
);
4. Run Agent
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
PagedIterable<PersistentThreadMessage> messages = client.listMessages(thread.getId());
for (PersistentThreadMessage message : messages) {
System.out.println(message.getRole() + ": " + message.getContent());
}
6. Cleanup
client.deleteThread(thread.getId());
client.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 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 |
Files (skills)
-
references
-
examples.md 22.2 KB
Loading…
-
-
SKILL.md 4.3 KB
--- 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". license: MIT metadata: author: Microsoft version: "1.0.0" 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 <dependency> <groupId>com.azure</groupId> <artifactId>azure-ai-agents-persistent</artifactId> <version>1.0.0-beta.1</version> </dependency> ``` ## Environment Variables ```bash PROJECT_ENDPOINT=https://<resource>.services.ai.azure.com/api/projects/<project> # Required for project configuration MODEL_DEPLOYMENT_NAME=gpt-4o-mini # Required for agent model selection AZURE_TOKEN_CREDENTIALS=prod # Required only if DefaultAzureCredential is used in production ``` ## Authentication ```java import com.azure.ai.agents.persistent.PersistentAgentsClient; import com.azure.ai.agents.persistent.PersistentAgentsClientBuilder; import com.azure.core.credential.TokenCredential; import com.azure.identity.AzureIdentityEnvVars; import com.azure.identity.DefaultAzureCredentialBuilder; import com.azure.identity.ManagedIdentityCredentialBuilder; String endpoint = System.getenv("PROJECT_ENDPOINT"); TokenCredential credential = new DefaultAzureCredentialBuilder() .requireEnvVars(AzureIdentityEnvVars.AZURE_TOKEN_CREDENTIALS) .build(); // Or use a specific credential directly in production: // See https://learn.microsoft.com/java/api/overview/azure/identity-readme?view=azure-java-stable#credential-classes // TokenCredential credential = new ManagedIdentityCredentialBuilder().build(); PersistentAgentsClient client = new PersistentAgentsClientBuilder() .endpoint(endpoint) .credential(credential) .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<PersistentThreadMessage> 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 |
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.