@polymorphism-tech/morph-spec 2.4.0 → 3.0.0

package/content/.morph/examples/multi-agent/README.md

@@ -1,309 +1,309 @@
-# Multi-Agent Example
-
-Exemplo de sistema multi-agente usando Microsoft Agent Framework com Semantic Kernel.
-
-## Stack
-
-| Camada | Tecnologia |
-|--------|------------|
-| **Framework** | Microsoft Agent Framework |
-| **AI Kernel** | Semantic Kernel |
-| **LLM** | Azure OpenAI / OpenAI |
-| **Orchestration** | Agent Orchestrator |
-| **Storage** | Azure Cosmos DB / SQL |
-| **Infra** | Azure Container Apps |
-
-## Visão Geral
-
-Sistema de agentes cooperativos que trabalham juntos para resolver tarefas complexas.
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    User Request                              │
-└─────────────────────────────────────────────────────────────┘
-                              │
-                              ▼
-┌─────────────────────────────────────────────────────────────┐
-│                    Orchestrator Agent                        │
-│  - Analisa requisição                                       │
-│  - Decompõe em subtarefas                                   │
-│  - Delega para agentes especialistas                        │
-│  - Consolida resultados                                     │
-└─────────────────────────────────────────────────────────────┘
-                              │
-              ┌───────────────┼───────────────┐
-              ▼               ▼               ▼
-┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
-│  Research Agent  │ │  Analysis Agent  │ │  Writing Agent   │
-│  - Web search    │ │  - Data analysis │ │  - Text generation│
-│  - Doc retrieval │ │  - Comparisons   │ │  - Summaries     │
-│  - RAG           │ │  - Insights      │ │  - Reports       │
-└──────────────────┘ └──────────────────┘ └──────────────────┘
-              │               │               │
-              └───────────────┼───────────────┘
-                              ▼
-┌─────────────────────────────────────────────────────────────┐
-│                    Consolidated Response                     │
-└─────────────────────────────────────────────────────────────┘
-```
-
-## Estrutura do Projeto
-
-```
-src/
-├── MultiAgent.Core/
-│   ├── Agents/
-│   │   ├── OrchestratorAgent.cs
-│   │   ├── ResearchAgent.cs
-│   │   ├── AnalysisAgent.cs
-│   │   └── WritingAgent.cs
-│   ├── Plugins/
-│   │   ├── WebSearchPlugin.cs
-│   │   ├── DocumentPlugin.cs
-│   │   └── DataAnalysisPlugin.cs
-│   ├── Memory/
-│   │   ├── ConversationMemory.cs
-│   │   └── SemanticMemory.cs
-│   └── Orchestration/
-│       ├── TaskDecomposer.cs
-│       └── ResultAggregator.cs
-│
-├── MultiAgent.Infrastructure/
-│   ├── Services/
-│   │   ├── AzureOpenAIService.cs
-│   │   └── EmbeddingService.cs
-│   └── Storage/
-│       ├── ConversationStore.cs
-│       └── VectorStore.cs
-│
-└── MultiAgent.Api/
-    ├── Endpoints/
-    │   ├── ChatEndpoints.cs
-    │   └── AgentEndpoints.cs
-    └── Program.cs
-```
-
-## Quick Start
-
-```bash
-# 1. Configure Azure OpenAI
-# Crie um recurso Azure OpenAI e configure:
-# - Deployment para gpt-4
-# - Deployment para text-embedding-ada-002
-
-# 2. Configure appsettings.json
-cp appsettings.example.json appsettings.json
-# Edite com suas credenciais
-
-# 3. Run
-cd src/MultiAgent.Api
-dotnet run
-
-# 4. Test
-curl -X POST http://localhost:5000/api/chat \
-  -H "Content-Type: application/json" \
-  -d '{"message": "Compare the top 3 cloud providers for a SaaS startup"}'
-```
-
-## Agentes
-
-### 1. Orchestrator Agent
-
-O agente principal que coordena todos os outros.
-
-**Responsabilidades**:
-- Analisar a intenção do usuário
-- Decompor tarefas complexas
-- Delegar para agentes especialistas
-- Consolidar respostas
-
-### 2. Research Agent
-
-Especialista em busca e recuperação de informações.
-
-**Capabilities**:
-- Web search (Bing API)
-- Document retrieval (RAG)
-- Knowledge base queries
-
-### 3. Analysis Agent
-
-Especialista em análise de dados e comparações.
-
-**Capabilities**:
-- Data analysis
-- Trend identification
-- Comparative analysis
-- Insight generation
-
-### 4. Writing Agent
-
-Especialista em geração de conteúdo.
-
-**Capabilities**:
-- Text summarization
-- Report generation
-- Content formatting
-- Translation
-
-## Plugins
-
-### WebSearchPlugin
-
-```csharp
-[KernelFunction("search_web")]
-[Description("Search the web for information")]
-public async Task<string> SearchWebAsync(
-    [Description("The search query")] string query,
-    [Description("Number of results")] int maxResults = 5)
-{
-    // Implementação com Bing Search API
-}
-```
-
-### DocumentPlugin
-
-```csharp
-[KernelFunction("retrieve_documents")]
-[Description("Retrieve relevant documents from the knowledge base")]
-public async Task<IEnumerable<Document>> RetrieveDocumentsAsync(
-    [Description("The query to search for")] string query,
-    [Description("Maximum documents to return")] int limit = 3)
-{
-    // Implementação com Vector Store
-}
-```
-
-## Fluxo de Execução
-
-```mermaid
-sequenceDiagram
-    participant User
-    participant API
-    participant Orchestrator
-    participant Research
-    participant Analysis
-    participant Writing
-
-    User->>API: "Compare cloud providers for SaaS"
-    API->>Orchestrator: Process request
-
-    Orchestrator->>Orchestrator: Decompose task
-    Note over Orchestrator: 1. Research providers<br/>2. Analyze features<br/>3. Write comparison
-
-    Orchestrator->>Research: Get info on AWS, Azure, GCP
-    Research->>Research: Web search + RAG
-    Research-->>Orchestrator: Provider data
-
-    Orchestrator->>Analysis: Compare features, pricing
-    Analysis->>Analysis: Analyze data
-    Analysis-->>Orchestrator: Comparison insights
-
-    Orchestrator->>Writing: Create comparison report
-    Writing->>Writing: Generate formatted report
-    Writing-->>Orchestrator: Final report
-
-    Orchestrator-->>API: Consolidated response
-    API-->>User: Comparison report
-```
-
-## Configuração
-
-### appsettings.json
-
-```json
-{
-  "AzureOpenAI": {
-    "Endpoint": "https://your-resource.openai.azure.com/",
-    "ApiKey": "your-api-key",
-    "ChatDeployment": "gpt-4",
-    "EmbeddingDeployment": "text-embedding-ada-002"
-  },
-  "BingSearch": {
-    "ApiKey": "your-bing-api-key",
-    "Endpoint": "https://api.bing.microsoft.com/v7.0/search"
-  },
-  "VectorStore": {
-    "Type": "InMemory",
-    "CosmosDbEndpoint": "",
-    "CosmosDbKey": ""
-  }
-}
-```
-
-## Custos Estimados
-
-| Recurso | Tier | Custo Estimado |
-|---------|------|----------------|
-| Azure OpenAI (GPT-4) | Pay-per-token | ~$0.03/1K tokens |
-| Azure OpenAI (Embeddings) | Pay-per-token | ~$0.0001/1K tokens |
-| Bing Search API | S1 | $7/1K transactions |
-| Container Apps | Consumption | ~$0-10/mês |
-| Cosmos DB (opcional) | Serverless | ~$0-5/mês |
-
-**Nota**: Custos variam significativamente com uso. Para desenvolvimento, use modelos menores (GPT-3.5-turbo).
-
-## Extensibilidade
-
-### Adicionando um Novo Agente
-
-```csharp
-public class CustomAgent : BaseAgent
-{
-    public CustomAgent(Kernel kernel) : base(kernel)
-    {
-        SystemPrompt = """
-            You are a specialized agent for [purpose].
-            Your capabilities include:
-            - [capability 1]
-            - [capability 2]
-            """;
-    }
-
-    public override async Task<AgentResponse> ProcessAsync(AgentRequest request)
-    {
-        // Implementação específica
-    }
-}
-```
-
-### Adicionando um Novo Plugin
-
-```csharp
-public class CustomPlugin
-{
-    [KernelFunction("custom_function")]
-    [Description("Description of what this function does")]
-    public async Task<string> CustomFunctionAsync(
-        [Description("Parameter description")] string param)
-    {
-        // Implementação
-    }
-}
-```
-
-## Padrões de Comunicação
-
-### 1. Request-Response
-
-Agente recebe request, processa e retorna response.
-
-### 2. Pub-Sub (Event-Driven)
-
-Agentes publicam eventos que outros agentes podem consumir.
-
-### 3. Handoff
-
-Agente transfere contexto completo para outro agente.
-
-## Boas Práticas
-
-1. **Prompts claros**: Defina system prompts específicos para cada agente
-2. **Fallbacks**: Implemente fallbacks quando um agente falhar
-3. **Rate limiting**: Controle chamadas à API para evitar throttling
-4. **Logging**: Log todas as interações para debugging
-5. **Cost tracking**: Monitore tokens consumidos
-
----
-
-*MORPH-SPEC by Polymorphism Tech*
+# Multi-Agent Example
+
+Exemplo de sistema multi-agente usando Microsoft Agent Framework com Semantic Kernel.
+
+## Stack
+
+| Camada | Tecnologia |
+|--------|------------|
+| **Framework** | Microsoft Agent Framework |
+| **AI Kernel** | Semantic Kernel |
+| **LLM** | Azure OpenAI / OpenAI |
+| **Orchestration** | Agent Orchestrator |
+| **Storage** | Azure Cosmos DB / SQL |
+| **Infra** | Azure Container Apps |
+
+## Visão Geral
+
+Sistema de agentes cooperativos que trabalham juntos para resolver tarefas complexas.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    User Request                              │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    Orchestrator Agent                        │
+│  - Analisa requisição                                       │
+│  - Decompõe em subtarefas                                   │
+│  - Delega para agentes especialistas                        │
+│  - Consolida resultados                                     │
+└─────────────────────────────────────────────────────────────┘
+                              │
+              ┌───────────────┼───────────────┐
+              ▼               ▼               ▼
+┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
+│  Research Agent  │ │  Analysis Agent  │ │  Writing Agent   │
+│  - Web search    │ │  - Data analysis │ │  - Text generation│
+│  - Doc retrieval │ │  - Comparisons   │ │  - Summaries     │
+│  - RAG           │ │  - Insights      │ │  - Reports       │
+└──────────────────┘ └──────────────────┘ └──────────────────┘
+              │               │               │
+              └───────────────┼───────────────┘
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    Consolidated Response                     │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Estrutura do Projeto
+
+```
+src/
+├── MultiAgent.Core/
+│   ├── Agents/
+│   │   ├── OrchestratorAgent.cs
+│   │   ├── ResearchAgent.cs
+│   │   ├── AnalysisAgent.cs
+│   │   └── WritingAgent.cs
+│   ├── Plugins/
+│   │   ├── WebSearchPlugin.cs
+│   │   ├── DocumentPlugin.cs
+│   │   └── DataAnalysisPlugin.cs
+│   ├── Memory/
+│   │   ├── ConversationMemory.cs
+│   │   └── SemanticMemory.cs
+│   └── Orchestration/
+│       ├── TaskDecomposer.cs
+│       └── ResultAggregator.cs
+│
+├── MultiAgent.Infrastructure/
+│   ├── Services/
+│   │   ├── AzureOpenAIService.cs
+│   │   └── EmbeddingService.cs
+│   └── Storage/
+│       ├── ConversationStore.cs
+│       └── VectorStore.cs
+│
+└── MultiAgent.Api/
+    ├── Endpoints/
+    │   ├── ChatEndpoints.cs
+    │   └── AgentEndpoints.cs
+    └── Program.cs
+```
+
+## Quick Start
+
+```bash
+# 1. Configure Azure OpenAI
+# Crie um recurso Azure OpenAI e configure:
+# - Deployment para gpt-4
+# - Deployment para text-embedding-ada-002
+
+# 2. Configure appsettings.json
+cp appsettings.example.json appsettings.json
+# Edite com suas credenciais
+
+# 3. Run
+cd src/MultiAgent.Api
+dotnet run
+
+# 4. Test
+curl -X POST http://localhost:5000/api/chat \
+  -H "Content-Type: application/json" \
+  -d '{"message": "Compare the top 3 cloud providers for a SaaS startup"}'
+```
+
+## Agentes
+
+### 1. Orchestrator Agent
+
+O agente principal que coordena todos os outros.
+
+**Responsabilidades**:
+- Analisar a intenção do usuário
+- Decompor tarefas complexas
+- Delegar para agentes especialistas
+- Consolidar respostas
+
+### 2. Research Agent
+
+Especialista em busca e recuperação de informações.
+
+**Capabilities**:
+- Web search (Bing API)
+- Document retrieval (RAG)
+- Knowledge base queries
+
+### 3. Analysis Agent
+
+Especialista em análise de dados e comparações.
+
+**Capabilities**:
+- Data analysis
+- Trend identification
+- Comparative analysis
+- Insight generation
+
+### 4. Writing Agent
+
+Especialista em geração de conteúdo.
+
+**Capabilities**:
+- Text summarization
+- Report generation
+- Content formatting
+- Translation
+
+## Plugins
+
+### WebSearchPlugin
+
+```csharp
+[KernelFunction("search_web")]
+[Description("Search the web for information")]
+public async Task<string> SearchWebAsync(
+    [Description("The search query")] string query,
+    [Description("Number of results")] int maxResults = 5)
+{
+    // Implementação com Bing Search API
+}
+```
+
+### DocumentPlugin
+
+```csharp
+[KernelFunction("retrieve_documents")]
+[Description("Retrieve relevant documents from the knowledge base")]
+public async Task<IEnumerable<Document>> RetrieveDocumentsAsync(
+    [Description("The query to search for")] string query,
+    [Description("Maximum documents to return")] int limit = 3)
+{
+    // Implementação com Vector Store
+}
+```
+
+## Fluxo de Execução
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant API
+    participant Orchestrator
+    participant Research
+    participant Analysis
+    participant Writing
+
+    User->>API: "Compare cloud providers for SaaS"
+    API->>Orchestrator: Process request
+
+    Orchestrator->>Orchestrator: Decompose task
+    Note over Orchestrator: 1. Research providers<br/>2. Analyze features<br/>3. Write comparison
+
+    Orchestrator->>Research: Get info on AWS, Azure, GCP
+    Research->>Research: Web search + RAG
+    Research-->>Orchestrator: Provider data
+
+    Orchestrator->>Analysis: Compare features, pricing
+    Analysis->>Analysis: Analyze data
+    Analysis-->>Orchestrator: Comparison insights
+
+    Orchestrator->>Writing: Create comparison report
+    Writing->>Writing: Generate formatted report
+    Writing-->>Orchestrator: Final report
+
+    Orchestrator-->>API: Consolidated response
+    API-->>User: Comparison report
+```
+
+## Configuração
+
+### appsettings.json
+
+```json
+{
+  "AzureOpenAI": {
+    "Endpoint": "https://your-resource.openai.azure.com/",
+    "ApiKey": "your-api-key",
+    "ChatDeployment": "gpt-4",
+    "EmbeddingDeployment": "text-embedding-ada-002"
+  },
+  "BingSearch": {
+    "ApiKey": "your-bing-api-key",
+    "Endpoint": "https://api.bing.microsoft.com/v7.0/search"
+  },
+  "VectorStore": {
+    "Type": "InMemory",
+    "CosmosDbEndpoint": "",
+    "CosmosDbKey": ""
+  }
+}
+```
+
+## Custos Estimados
+
+| Recurso | Tier | Custo Estimado |
+|---------|------|----------------|
+| Azure OpenAI (GPT-4) | Pay-per-token | ~$0.03/1K tokens |
+| Azure OpenAI (Embeddings) | Pay-per-token | ~$0.0001/1K tokens |
+| Bing Search API | S1 | $7/1K transactions |
+| Container Apps | Consumption | ~$0-10/mês |
+| Cosmos DB (opcional) | Serverless | ~$0-5/mês |
+
+**Nota**: Custos variam significativamente com uso. Para desenvolvimento, use modelos menores (GPT-3.5-turbo).
+
+## Extensibilidade
+
+### Adicionando um Novo Agente
+
+```csharp
+public class CustomAgent : BaseAgent
+{
+    public CustomAgent(Kernel kernel) : base(kernel)
+    {
+        SystemPrompt = """
+            You are a specialized agent for [purpose].
+            Your capabilities include:
+            - [capability 1]
+            - [capability 2]
+            """;
+    }
+
+    public override async Task<AgentResponse> ProcessAsync(AgentRequest request)
+    {
+        // Implementação específica
+    }
+}
+```
+
+### Adicionando um Novo Plugin
+
+```csharp
+public class CustomPlugin
+{
+    [KernelFunction("custom_function")]
+    [Description("Description of what this function does")]
+    public async Task<string> CustomFunctionAsync(
+        [Description("Parameter description")] string param)
+    {
+        // Implementação
+    }
+}
+```
+
+## Padrões de Comunicação
+
+### 1. Request-Response
+
+Agente recebe request, processa e retorna response.
+
+### 2. Pub-Sub (Event-Driven)
+
+Agentes publicam eventos que outros agentes podem consumir.
+
+### 3. Handoff
+
+Agente transfere contexto completo para outro agente.
+
+## Boas Práticas
+
+1. **Prompts claros**: Defina system prompts específicos para cada agente
+2. **Fallbacks**: Implemente fallbacks quando um agente falhar
+3. **Rate limiting**: Controle chamadas à API para evitar throttling
+4. **Logging**: Log todas as interações para debugging
+5. **Cost tracking**: Monitore tokens consumidos
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*