SDK Persistente de Agentes de IA do Azure para Java

SDK de baixo nível para criar e gerenciar agentes de IA persistentes com threads, mensagens, execuções e ferramentas.

Instalação

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

Variáveis de Ambiente

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

Autenticação

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

Conceitos Principais

O SDK Persistente de Agentes de IA do Azure fornece uma API de baixo nível para gerenciar agentes persistentes que podem ser reutilizados entre sessões.

Hierarquia de Clientes

Fluxo de Trabalho Principal

1. Criar Agente

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

2. Criar Thread

PersistentAgentThread thread = threads.createThread();

3. Adicionar Mensagem

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

4. Executar Agente

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

Verifique o status resultante antes de ler uma resposta final: requires_action precisa de um manipulador de saída de ferramenta autorizado; failed, cancelled, expired ou outros estados não bem-sucedidos devem ser relatados explicitamente. Um tempo limite de sondagem não cancela a execução na nuvem.

5. Obter Resposta

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

6. Limpeza

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

Melhores Práticas

1. Use DefaultAzureCredential para autenticação em produção
2. Sonde com atrasos apropriados — 500ms recomendado entre verificações de status
3. Limpe os recursos — Exclua threads e agentes quando terminar
4. Manipule todos os status de execução — Verifique se há RequiresAction, Failed, Cancelled
5. Use o cliente assíncrono para melhor taxa de transferência em cenários de alta concorrência

Tratamento de Erros

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

Links de Referência

…