# 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*
