azure-ai-agents-persistent-java

Azure AI Agents Persistent SDK for Java

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

安装

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

环境变量

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

身份验证

import com.azure.ai.agents.persistent.PersistentAgentsClient;
import com.azure.ai.agents.persistent.PersistentAgentsClientBuilder;
import com.azure.ai.agents.persistent.*;
import com.azure.ai.agents.persistent.models.*;
import com.azure.core.http.rest.PagedIterable;
import com.azure.identity.DefaultAzureCredentialBuilder;

String endpoint = System.getenv("PROJECT_ENDPOINT");
PersistentAgentsClient client = new PersistentAgentsClientBuilder()
    .endpoint(endpoint)
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();
String modelDeploymentName = System.getenv("MODEL_DEPLOYMENT_NAME");
PersistentAgentsAdministrationClient administration = client.getPersistentAgentsAdministrationClient();
ThreadsClient threads = client.getThreadsClient();
MessagesClient messageClient = client.getMessagesClient();
RunsClient runs = client.getRunsClient();

核心概念

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

客户端层级

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

核心工作流

1. 创建 Agent

// Create agent with tools
PersistentAgent agent = administration.createAgent(
    new CreateAgentOptions(modelDeploymentName)
        .setName("Math Tutor")
        .setInstructions("You are a personal math tutor.")
);

2. 创建线程

PersistentAgentThread thread = threads.createThread();

3. 添加消息

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

4. 运行 Agent

ThreadRun run = runs.createRun(new CreateRunOptions(thread.getId(), agent.getId()));

// Bound polling; a terminal non-success state is not a completed answer.
long deadline = System.nanoTime() + java.util.concurrent.TimeUnit.SECONDS.toNanos(60);
while (run.getStatus() == RunStatus.QUEUED || run.getStatus() == RunStatus.IN_PROGRESS) {
    if (System.nanoTime() > deadline) {
        throw new IllegalStateException("Run polling timed out; inspect/cancel the owned run separately");
    }
    Thread.sleep(500);
    run = runs.getRun(thread.getId(), run.getId());
}

读取最终响应前，请检查运行状态：requires_action 需要经过授权的工具输出处理程序；failed、cancelled、expired 或其他非成功状态必须明确报告。轮询超时不会取消云端运行。

5. 获取响应

PagedIterable<ThreadMessage> messages = messageClient.listMessages(thread.getId());
for (ThreadMessage message : messages) {
    System.out.println("Message role: " + message.getRole()); // Do not log retained prompt/response payloads.
}

6. 清理

threads.deleteThread(thread.getId());
administration.deleteAgent(agent.getId());

最佳实践

1. 生产环境身份验证使用 DefaultAzureCredential
2. 适当延迟轮询——建议每次状态检查间隔 500ms
3. 清理资源——完成后删除线程和 Agent
4. 处理所有运行状态——检查 RequiresAction、Failed、Cancelled
5. 使用异步客户端，在高并发场景下可获得更高吞吐量

错误处理

import com.azure.core.exception.HttpResponseException;

try {
    PersistentAgent exampleAgent = administration.createAgent(
        new CreateAgentOptions(modelDeploymentName).setName("Example").setInstructions("Answer briefly"));
} catch (HttpResponseException e) {
    System.err.println("Error: " + e.getResponse().getStatusCode() + " - " + e.getMessage());
}

参考链接

资源	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

适用场景

使用预览版 SDK 实现或维护 Java 持久化 Agent 的线程、消息、运行和管理功能时使用。经审查的示例使用 beta.2 子客户端，而非 PersistentAgentsClient 上的直接 CRUD 方法。

限制

• 操作会创建需付费的云资源、发送提示词并保留线程数据。请使用已获授权的项目/模型并设置明确的预算；仅删除当前运行所创建的资源，失败时保留 ID，并对消息/凭据日志进行脱敏。
• 代码片段是应用程序代码中的连续片段，并非可独立编译的程序。API 结构已根据 Microsoft 的 beta.2 示例和预览版参考资料进行核对；未执行云端运行。请使用项目中经过审查的 Azure BOM，添加兼容的 azure-identity 和所需依赖项。
• 请勿将输出视为环境特定验证、测试或专家审查的替代品。
• 如果缺少必需的输入、权限、安全边界或成功标准，请停止并请求澄清。