Azure AI Agents 持久化 Java 实现

azure-ai-agents-persistent-java
分类通用
作者Agentic Awesome Skills 社区
许可MIT
评分4.20/5
使用9.3K

Azure AI Agents Persistent SDK for Java

用于创建和管理具有线程、消息、运行和工具的持久化 AI 代理的低级 SDK。

安装

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

环境变量

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

身份验证

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

核心概念

Azure AI Agents Persistent SDK 提供了一个低级 API，用于管理可在不同会话之间复用的持久化代理。

客户端层级

| 客户端 | 用途 |
|--------|---------|
| PersistentAgentsClient | 用于代理操作的同步客户端 |
| PersistentAgentsAsyncClient | 用于代理操作的异步客户端 |

核心工作流

1. 创建代理

java
// 创建带有工具的代理
PersistentAgent agent = client.createAgent(
    modelDeploymentName,
    "Math Tutor",
    "You are a personal math tutor."
);

2. 创建线程

java
PersistentAgentThread thread = client.createThread();

3. 添加消息

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

4. 运行代理

java
ThreadRun run = client.createRun(thread.getId(), agent.getId());

// 轮询直到完成
while (run.getStatus() == RunStatus.QUEUED || run.getStatus() == RunStatus.IN_PROGRESS) {
    Thread.sleep(500);
    run = client.getRun(thread.getId(), run.getId());
}

5. 获取响应

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

6. 清理

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

最佳实践

1. 使用 DefaultAzureCredential 进行生产环境身份验证。
2. 设置合理的轮询延迟 —— 建议状态检查间隔为 500ms。
3. 清理资源 —— 完成后删除线程和代理。
4. 处理所有运行状态 —— 检查 RequiresAction、Failed 和 Cancelled 状态。
5. 在高并发场景下使用异步客户端 以提高吞吐量。

错误处理

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

参考链接

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

使用场景

当需要执行概览中所描述的工作流或操作时，适用此技能。

局限性

  • 仅在任务明确符合上述范围时使用此技能。
  • 不要将输出结果视为特定环境验证、测试或专家评审的替代方案。
  • 如果缺少必要的输入、权限、安全边界或成功标准，请停止操作并请求澄清。