azure-ai-agents-persistent-java

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Azure AI Agents Persistent SDK for Java

适用于Java的Azure AI Agents Persistent SDK

Low-level SDK for creating and managing persistent AI agents with threads, messages, runs, and tools.

用于创建和管理带有线程、消息、运行和工具的持久化AI Agent的底层SDK。

Installation

安装

xml

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

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>
MODEL_DEPLOYMENT_NAME=gpt-4o-mini

bash

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

Authentication

身份验证

java

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

java

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

Key Concepts

核心概念

The Azure AI Agents Persistent SDK provides a low-level API for managing persistent agents that can be reused across sessions.

Azure AI Agents Persistent SDK 提供了一个底层API，用于管理可跨会话复用的持久化Agent。

Client Hierarchy

客户端层次结构

Client	Purpose
`PersistentAgentsClient`	Sync client for agent operations
`PersistentAgentsAsyncClient`	Async client for agent operations

客户端	用途
`PersistentAgentsClient`	用于Agent操作的同步客户端
`PersistentAgentsAsyncClient`	用于Agent操作的异步客户端

Core Workflow

核心工作流

1. Create Agent

1. 创建Agent

java

// Create agent with tools
PersistentAgent agent = client.createAgent(
    modelDeploymentName,
    "Math Tutor",
    "You are a personal math tutor."
);

java

// Create agent with tools
PersistentAgent agent = client.createAgent(
    modelDeploymentName,
    "Math Tutor",
    "You are a personal math tutor."
);

2. Create Thread

2. 创建线程

java

PersistentAgentThread thread = client.createThread();

java

PersistentAgentThread thread = client.createThread();

3. Add Message

3. 添加消息

java

client.createMessage(
    thread.getId(),
    MessageRole.USER,
    "I need help with equations."
);

java

client.createMessage(
    thread.getId(),
    MessageRole.USER,
    "I need help with equations."
);

4. Run Agent

4. 运行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());
}

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

5. 获取响应

java

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

java

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

6. Cleanup

6. 清理

java

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

java

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

在生产环境身份验证中使用DefaultAzureCredential
使用适当的延迟进行轮询 — 建议状态检查间隔为500毫秒
清理资源 — 使用完毕后删除线程和Agent
处理所有运行状态 — 检查RequiresAction、Failed、Cancelled状态
在高并发场景中使用异步客户端以获得更好的吞吐量

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

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

资源	URL
Maven包	https://central.sonatype.com/artifact/com.azure/azure-ai-agents-persistent
GitHub源码	https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/ai/azure-ai-agents-persistent