Nexttag.Ai.Agents 1.6.0

Nexttag.Ai.Agents

Loop de agente com tool-calling, streaming, gating de aprovação e busca web — plugue qualquer LLM OpenAI-compatível.

Instalar

dotnet add package Nexttag.Ai.Agents

Requer .NET 10. Depende de: Microsoft.Extensions.AI, Microsoft.Extensions.AI.OpenAI.

Registrar (Program.cs)

Não há método de DI obrigatório. Instancie diretamente ou registre como singleton:

// Program.cs — singleton recomendado (client é thread-safe)
builder.Services.AddSingleton<IChatClient>(_ =>
    NexttagChatClient.OpenAiCompativel(
        endpoint: builder.Configuration["Ai:Endpoint"]!,
        model:    builder.Configuration["Ai:Model"]!,
        apiKey:   builder.Configuration["Ai:ApiKey"]));

builder.Services.AddScoped<AgentRunner>();

Configurar

{
  "Ai": {
    "Endpoint": "http://localhost:4000/v1",
    "Model":    "qwen3:14b",
    "ApiKey":   "sk-..."
  }
}

O modelo precisa suportar tool-calling. maxIteracoes (default 12) limita rodadas do loop.

Usar

Execução simples

using Microsoft.Extensions.AI;
using Nexttag.Ai.Agents;

IChatClient client = NexttagChatClient.OpenAiCompativel(
    endpoint: "http://localhost:4000/v1",
    model:    "qwen3:14b");

var runner  = new AgentRunner(client);
var context = new AgentRunContext();

AgentRunResult r = await runner.RunAsync(
    systemPrompt: "Você é um assistente objetivo. Responda em português.",
    task:         "Explique o que é idempotência em 2 frases.",
    tools:        [],
    context:      context);

Console.WriteLine(r.FinalText);

Adicionando tools

using System.ComponentModel;
using Microsoft.Extensions.AI;

var context = new AgentRunContext();

AITool horaAtual = AIFunctionFactory.Create(
    () =>
    {
        context.Step("hora_servidor", "consultou hora");
        return DateTimeOffset.UtcNow.ToString("o");
    },
    "hora_servidor",
    "Retorna a data e hora atual do servidor (UTC ISO 8601).");

AITool buscarDocs = AIFunctionFactory.Create(
    async ([Description("termos de busca")] string consulta) =>
    {
        var trechos = await meuRag.BuscarAsync(consulta, topK: 5);
        context.Step("buscar_documentos", $"{trechos.Count} trechos");
        return System.Text.Json.JsonSerializer.Serialize(trechos);
    },
    "buscar_documentos",
    "Busca trechos relevantes nos documentos. Cite o título na resposta.");

AgentRunResult r = await runner.RunAsync(systemPrompt, task,
    tools: [horaAtual, buscarDocs], context: context);

Streaming (SSE / WebSocket)

await foreach (AgentEvent ev in runner.RunStreamingAsync(systemPrompt, task, tools, context))
{
    switch (ev)
    {
        case AgentTextEvent t:     Console.Write(t.Delta);           break;
        case AgentStepEvent s:     Log(s.Step.Tool, s.Step.Summary); break;
        case AgentProposalEvent p: Log(p.Proposal.Title);            break;
        case AgentDoneEvent d:     Log($"fim ({d.FinalText.Length} chars)"); break;
        case AgentErrorEvent e:    Log($"erro: {e.Message}");        break;
    }
}

Histórico de conversa

var mensagens = new List<ChatMessage>
{
    new(ChatRole.System, systemPrompt),
    new(ChatRole.User,   "turno anterior..."),
    new(ChatRole.Assistant, "resposta anterior..."),
    new(ChatRole.User,   novaPergunta),
};

AgentRunResult r = await runner.RunAsync(mensagens, tools, context);

Gating de aprovação (propor em vez de aplicar)

AITool renomear = AIFunctionFactory.Create(
    ([Description("id do documento")] string docId,
     [Description("novo título")]     string titulo) =>
    {
        var id = context.Propose(
            kind: "renomear_documento",
            title: $"Renomear para "{titulo}"",
            rationale: "Usuário pediu título mais claro.",
            data: new Dictionary<string, string?> { ["docId"] = docId, ["titulo"] = titulo });
        return $"Proposta registrada (id {id}). Aguardando aprovação.";
    },
    "renomear_documento",
    "Propõe renomear um documento. Só é aplicado após aprovação.");

// após o Run:
foreach (var p in r.Proposals)
    // host aplica usando p.Kind + p.Data quando usuário aprovar
    Console.WriteLine($"[{p.Kind}] {p.Title}");

Receitas

Agente com busca web (Tavily):

var web = new HttpWebSearch(http, new WebSearchOptions { Provider = "tavily", ApiKey = tavilyKey });
if (web.Enabled)
    tools.Add(AIFunctionFactory.Create(
        async ([Description("termos")] string q) =>
            System.Text.Json.JsonSerializer.Serialize(await web.SearchAsync(q, 5)),
        "buscar_web", "Busca atuais na web. Cite a fonte (url)."));

Telemetria (registrar o ActivitySource):

tracerProviderBuilder.AddSource(AgentTelemetry.SourceName); // "Nexttag.Ai.Agents"

IChatClient client = NexttagChatClient.OpenAiCompativel(endpoint, model, apiKey,
    configurarPipeline: b => b.UseOpenTelemetry().UseLogging(loggerFactory));

Rastreio por usuário/sessão (Langfuse via litellm):

var options = new AgentRunOptions(UserId: userId, SessionId: sessionId);
AgentRunResult r = await runner.RunAsync(mensagens, tools, context, options);

Notas

• Crie um AgentRunContext por execução — ele acumula passos/propostas daquela rodada.
• Tools de leitura executam direto; tools de escrita devem usar context.Propose(...).
• A lib é stateless por execução — persistência de conversa é responsabilidade do host.
• NexttagChatClient.OpenAiCompativel já habilita o loop de tool-calling (FunctionInvokingChatClient).
• Embeddings, RAG e banco vetorial estão em Nexttag.Ai.Embeddings — fora do escopo desta lib.