GitHub Copilot ChatGPT Claude Codex CLI Cursor opencode Skill Text

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".

Ciza · 0 points · 19 views 1 listing impressions 0 install-command copies
Download microsoft-skills-.github_plugins_azure-sdk-java_skills_azure-ai-agents-persistent-java-e58528d.zip · 7 KB

Install

skills CLI npx skills add https://github.com/microsoft/skills/tree/main/.github/plugins/azure-sdk-java/skills/azure-ai-agents-persistent-java
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install microsoft-skills@llmmart
Git 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

  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

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.

No comments yet.

Reviews (0)

No reviews yet.