@polymorphism-tech/morph-spec 1.0.4 → 2.1.0

package/content/.claude/skills/specialists/ms-agent-expert.md

@@ -1,147 +1,198 @@
-# MS Agent Expert
+# Agent Framework Expert
 
-Especialista em Microsoft Agent Framework, Semantic Kernel e integração de IA em aplicações .NET.
+Especialista em Microsoft Agent Framework e integração de IA em aplicações .NET.
+
+> **IMPORTANTE:** O MORPH-SPEC usa **exclusivamente** Microsoft Agent Framework.
+> Semantic Kernel foi descontinuado.
 
 ## Responsabilidades
 
-1. **Integrar Microsoft Agent Framework** em projetos
-2. **Configurar Semantic Kernel** para orquestração
+1. **Integrar Microsoft Agent Framework** em projetos .NET 10
+2. **Criar agentes** com instruções e tools
 3. **Otimizar prompts** e gerenciar tokens
-4. **Criar agentes** com plugins e functions
+4. **Implementar RAG** com vector search
 
 ## Triggers
 
-Keywords: `agent`, `ai`, `semantic kernel`, `llm`, `openai`, `chat`, `prompt`, `plugin`, `function calling`
+Keywords: `agent`, `ai`, `llm`, `openai`, `chat`, `prompt`, `tool`, `function calling`, `rag`, `embedding`
 
-## Microsoft Agent Framework
+## Microsoft Agent Framework (.NET 10)
 
-> Novo framework oficial da Microsoft que unifica Semantic Kernel e AutoGen.
+> Framework oficial da Microsoft para criar agentes de IA.
+> Substitui Semantic Kernel com foco exclusivo em agentes.
 
 ### Estrutura Básica
 
 ```csharp
-// Agent com Semantic Kernel
-using Microsoft.SemanticKernel;
-using Microsoft.SemanticKernel.Agents;
+// Agent com Microsoft Agent Framework
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
 
 public class OrderAnalysisAgent
 {
-    private readonly Kernel _kernel;
+    private readonly IChatClient _chatClient;
+    private readonly ILogger<OrderAnalysisAgent> _logger;
 
-    public OrderAnalysisAgent(Kernel kernel)
+    public OrderAnalysisAgent(
+        IChatClient chatClient,
+        ILogger<OrderAnalysisAgent> logger)
     {
-        _kernel = kernel;
+        _chatClient = chatClient;
+        _logger = logger;
     }
 
-    public async Task<string> AnalyzeOrderAsync(Order order)
+    public async Task<string> AnalyzeOrderAsync(Order order, CancellationToken ct = default)
     {
-        var prompt = """
-            Analise o pedido abaixo e forneça insights:
-
-            Número: {{$orderNumber}}
-            Total: {{$total}}
-            Itens: {{$itemCount}}
-            Cliente: {{$customerName}}
-
-            Forneça:
-            1. Resumo do pedido
-            2. Sugestões de upsell
-            3. Risco de cancelamento (baixo/médio/alto)
+        var agent = _chatClient.CreateAgent(
+            instructions: """
+                Você é um especialista em análise de pedidos.
+
+                Analise o pedido fornecido e retorne:
+                1. Resumo do pedido
+                2. Sugestões de upsell baseadas nos itens
+                3. Risco de cancelamento (baixo/médio/alto) com justificativa
+
+                Seja conciso e objetivo.
+                """,
+            name: "OrderAnalyzer"
+        );
+
+        var prompt = $"""
+            Pedido: {order.OrderNumber}
+            Total: {order.Total:C}
+            Itens: {order.Items.Count}
+            Cliente: {order.Customer.Name}
+            Histórico: {order.Customer.TotalOrders} pedidos anteriores
+
+            Analise este pedido.
             """;
 
-        var function = _kernel.CreateFunctionFromPrompt(prompt);
-
-        var result = await _kernel.InvokeAsync(function, new()
-        {
-            ["orderNumber"] = order.OrderNumber,
-            ["total"] = order.Total.ToString("C"),
-            ["itemCount"] = order.Items.Count,
-            ["customerName"] = order.Customer.Name
-        });
+        _logger.LogInformation("Analisando pedido {OrderNumber}", order.OrderNumber);
 
-        return result.GetValue<string>() ?? "";
+        var response = await agent.RunAsync(prompt, cancellationToken: ct);
+        return response.Content;
     }
 }
 ```
 
-### Configuração do Kernel
+### Configuração do ChatClient
 
 ```csharp
 // Program.cs
-builder.Services.AddKernel()
-    .AddAzureOpenAIChatCompletion(
-        deploymentName: "gpt-4o-mini",
-        endpoint: builder.Configuration["AzureOpenAI:Endpoint"]!,
-        apiKey: builder.Configuration["AzureOpenAI:ApiKey"]!);
-
-// Ou OpenAI direto
-builder.Services.AddKernel()
-    .AddOpenAIChatCompletion(
-        modelId: "gpt-4o-mini",
-        apiKey: builder.Configuration["OpenAI:ApiKey"]!);
+using Microsoft.Extensions.AI;
+
+// Azure OpenAI
+builder.Services.AddSingleton<IChatClient>(sp =>
+{
+    var config = sp.GetRequiredService<IConfiguration>();
+
+    return new ChatClient(
+        model: "gpt-4o-mini",
+        credential: new ApiKeyCredential(config["AzureOpenAI:ApiKey"]!),
+        endpoint: new Uri(config["AzureOpenAI:Endpoint"]!)
+    );
+});
+
+// Registrar agent como service
+builder.Services.AddScoped<IOrderAnalysisAgent, OrderAnalysisAgent>();
 ```
 
-### Plugins e Functions
+### Tools (Function Calling)
 
 ```csharp
-// Plugins/OrderPlugin.cs
-public class OrderPlugin
+using Microsoft.Agents.AI;
+
+public class OrderAgent
 {
+    private readonly IChatClient _chatClient;
     private readonly IOrderService _orderService;
 
-    public OrderPlugin(IOrderService orderService)
+    public OrderAgent(IChatClient chatClient, IOrderService orderService)
     {
+        _chatClient = chatClient;
         _orderService = orderService;
     }
 
-    [KernelFunction("get_order")]
+    [AgentTool("get_order")]
     [Description("Busca um pedido pelo número")]
     public async Task<Order?> GetOrderAsync(
-        [Description("Número do pedido")] string orderNumber)
+        [Description("Número do pedido")] string orderNumber,
+        CancellationToken ct = default)
     {
-        return await _orderService.GetByNumberAsync(orderNumber);
+        return await _orderService.GetByNumberAsync(orderNumber, ct);
     }
 
-    [KernelFunction("calculate_discount")]
+    [AgentTool("calculate_discount")]
     [Description("Calcula desconto baseado no histórico do cliente")]
     public decimal CalculateDiscount(
         [Description("ID do cliente")] int customerId,
         [Description("Valor do pedido")] decimal orderTotal)
     {
-        // Lógica de desconto
+        // Lógica de desconto baseada em histórico
         return orderTotal * 0.1m;
     }
-}
 
-// Registrar plugin
-kernel.Plugins.AddFromObject(new OrderPlugin(orderService));
+    public async Task<string> ChatAsync(string userMessage, CancellationToken ct = default)
+    {
+        var agent = _chatClient.CreateAgent(
+            instructions: """
+                Você é um assistente de pedidos.
+                Use as tools disponíveis para ajudar os usuários.
+                Seja conciso e profissional.
+                """,
+            name: "OrderAssistant",
+            tools: new[]
+            {
+                AgentTool.FromMethod(nameof(GetOrderAsync), this),
+                AgentTool.FromMethod(nameof(CalculateDiscount), this)
+            }
+        );
+
+        var response = await agent.RunAsync(userMessage, cancellationToken: ct);
+        return response.Content;
+    }
+}
 ```
 
-### Agent Framework (Preview)
+### Threads (Conversação Persistente)
 
 ```csharp
-// Usando Microsoft.SemanticKernel.Agents
-var agent = new ChatCompletionAgent
-{
-    Name = "OrderAssistant",
-    Instructions = """
-        Você é um assistente de pedidos. Ajude os usuários a:
-        - Consultar status de pedidos
-        - Calcular descontos
-        - Sugerir produtos relacionados
-
-        Seja conciso e profissional.
-        """,
-    Kernel = kernel
-};
-
-// Conversa
-var history = new ChatHistory();
-history.AddUserMessage("Qual o status do pedido #12345?");
-
-await foreach (var message in agent.InvokeAsync(history))
+public class ChatService
 {
-    Console.WriteLine(message.Content);
+    private readonly IChatClient _chatClient;
+    private readonly Dictionary<string, AgentThread> _threads = new();
+
+    public async Task<string> CreateConversationAsync(string userId)
+    {
+        var agent = _chatClient.CreateAgent(
+            instructions: "Você é um assistente útil e amigável.",
+            name: "ChatAssistant"
+        );
+
+        var thread = await agent.CreateThreadAsync();
+        _threads[userId] = thread;
+
+        return thread.Id;
+    }
+
+    public async Task<string> SendMessageAsync(
+        string userId,
+        string message,
+        CancellationToken ct = default)
+    {
+        if (!_threads.TryGetValue(userId, out var thread))
+            throw new InvalidOperationException("Thread não encontrada");
+
+        var agent = _chatClient.CreateAgent(
+            instructions: "Você é um assistente útil e amigável.",
+            name: "ChatAssistant"
+        );
+
+        await thread.AddMessageAsync(message, ct);
+        var response = await agent.RunAsync(thread, cancellationToken: ct);
+
+        return response.Content;
+    }
 }
 ```
 
@@ -187,22 +238,25 @@ var systemPrompt = """
 
 ## Documentação de Referência
 
-- [Microsoft Agent Framework](https://learn.microsoft.com/en-us/agent-framework/overview/agent-framework-overview)
+- [Microsoft Agent Framework](https://learn.microsoft.com/agent-framework/)
 - [Agent Framework GitHub](https://github.com/microsoft/agent-framework)
-- [Semantic Kernel](https://learn.microsoft.com/en-us/semantic-kernel/overview/)
-- [Semantic Kernel GitHub](https://github.com/microsoft/semantic-kernel)
-- [Azure OpenAI](https://learn.microsoft.com/en-us/azure/ai-services/openai/)
+- [Microsoft.Extensions.AI](https://learn.microsoft.com/dotnet/ai/ai-extensions)
+- [Azure OpenAI Service](https://learn.microsoft.com/azure/ai-services/openai/)
+- **[Guia Completo: Agent Framework Setup](../../.morph/standards/agent-framework-setup.md)**
 
 ## Checklist de Integração AI
 
-- [ ] Kernel configurado com DI
+- [ ] Package `Microsoft.Agents.AI` instalado
+- [ ] `IChatClient` configurado com DI
 - [ ] Modelo gpt-4o-mini como padrão
 - [ ] API keys no Key Vault (não hardcoded)
-- [ ] Plugins registrados
+- [ ] Agents registrados como services
+- [ ] Tools registradas manualmente
 - [ ] System prompt estruturado
 - [ ] Error handling para rate limits
 - [ ] Logging de prompts/responses (dev only)
 - [ ] Custos estimados por operação
+- [ ] **NÃO usar Semantic Kernel**
 
 ---