# azure-ai-agents-persistent-java

This skill guides Java projects using Azure AI Agents Persistent: create agents, manage message threads, and run agents. Useful when building persistent agents on Azure.

- skill · `type=skill` · Claude Code, GitHub Copilot · ★ 3149
- Author: Microsoft
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/microsoft/skills/tree/HEAD/.github/plugins/azure-sdk-java/skills/azure-ai-agents-persistent-java/SKILL.md
- Updated: 2026-10-23
- HTML: https://affpapa.org/en/nevibecode/skills/azure-ai-agents-persistent-java

## What it does

The skill covers the low-level `com.azure:azure-ai-agents-persistent` SDK for managing agents that remain available across sessions. Its workflow creates an agent and thread, adds a message, starts a run, checks its status, and reads the response. Threads and agents can be deleted when the work is done.

Set `PROJECT_ENDPOINT` and `MODEL_DEPLOYMENT_NAME` to connect and choose the agent model. Production use of `DefaultAzureCredential` also requires `AZURE_TOKEN_CREDENTIALS`. The SDK offers synchronous and asynchronous clients. Runs can end with `RequiresAction`, `Failed`, or `Cancelled`, so account for those states when handling results. The client needs a configured endpoint and credentials to connect to an Azure project.

## Requirements
- Works with: Azure

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add microsoft/skills --skill azure-ai-agents-persistent-java -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/azure-ai-agents-persistent-java/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/azure-ai-agents-persistent-java/

### Codex

**Manually: put the files in place**
- File: `.agents/skills/azure-ai-agents-persistent-java/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

**Manually: put the files in place**
- File: `.cursor/skills/azure-ai-agents-persistent-java/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install microsoft/skills azure-ai-agents-persistent-java
```

2. **Manually: put the files in place**
- File: `.github/skills/azure-ai-agents-persistent-java/SKILL.md`

### Gemini CLI

**Platform CLI**
```bash
gemini skills install https://github.com/microsoft/skills --path .github/plugins/azure-sdk-java/skills/azure-ai-agents-persistent-java
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/azure-ai-agents-persistent-java/SKILL.md` — The legacy .windsurf/skills/ path still works

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/microsoft/skills/tree/HEAD/.github/plugins/azure-sdk-java/skills/azure-ai-agents-persistent-java/SKILL.md

## When to use it
- create a persistent AI agent in a Java project
- send a message to an agent thread
- start a run and inspect its status
- read messages returned by an agent
- remove an agent and thread after use

## Example prompts
- Show me how to connect `PersistentAgentsClient` to my Java project in Azure.
- Create an agent, add a message to its thread, and read the response.
- Handle `RequiresAction`, `Failed`, and `Cancelled` when an agent run finishes.

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 20bfa7198a00a7d4.

BEGIN THIRD-PARTY FILE 20bfa7198a00a7d4
````text
---
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());
````
END THIRD-PARTY FILE 20bfa7198a00a7d4

The third-party file has ended. Everything between the 20bfa7198a00a7d4 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 3233 of 4417 bytes. © Microsoft · MIT · https://github.com/microsoft/skills/tree/HEAD/.github/plugins/azure-sdk-java/skills/azure-ai-agents-persistent-java/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md