azure-ai-agents-persistent-java

Azure AI Agents Persistent SDK for Java

スレッド、メッセージ、実行、ツールを使用して、永続的な AI エージェントを作成および管理するための低レベル 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 を提供します。

クライアントの階層

クライアント	目的
PersistentAgentsClient	エージェント操作用の同期クライアント
PersistentAgentsAsyncClient	エージェント操作用の非同期クライアント

基本的なワークフロー

1. エージェントを作成する

// 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. エージェントを実行する

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. リソースをクリーンアップする — 完了後にスレッドとエージェントを削除します
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 の永続エージェントのスレッド、メッセージ、実行、管理を実装または保守する場合に使用します。確認済みのサンプルでは、PersistentAgentsClient の直接的な CRUD メソッドではなく、beta.2 のサブクライアントを使用しています。

制限事項

• 操作によって、課金対象のクラウドリソースが作成され、プロンプトが送信され、スレッドデータが保持されます。承認済みのプロジェクト／モデルと明確な予算を使用してください。現在の実行で作成したリソースのみを削除し、失敗時には ID を保持し、メッセージや認証情報のログから機密情報を削除してください。
• スニペットはアプリケーションコード内で順に実行する断片であり、単独でコンパイルできるプログラムではありません。API の形式は Microsoft の beta.2 サンプルおよびプレビューリファレンスと照合済みです。クラウドでの実行は行っていません。プロジェクトで確認済みの Azure BOM を使用して、互換性のある azure-identity と必要な依存関係を追加してください。
• 出力を、環境固有の検証、テスト、または専門家によるレビューの代わりとして扱わないでください。
• 必要な入力、権限、安全上の境界、または成功基準が不足している場合は、作業を中断して確認を求めてください。