# Competências de Agentes Auto-Aprimoradas

> Otimize automaticamente as competências do seu agente usando um sistema multi-agente construído com o Google ADK e Gemini.

- Fonte: https://doutorai.pt/apps/self-improving-agent-skills
- Categoria: Skills de Agentes
- Dificuldade: Médio
- Modelos: Gemini
- Frameworks: Google ADK
- Corre local?: Precisa de APIs cloud
- Chaves necessárias: GOOGLE_API_KEY
- Licença: Apache-2.0
- Site: Doutor AI (https://doutorai.pt) - ferramentas de IA para pequenos negócios em português

## Tutorial completo

# Habilidades de Agente Auto-Aprimoradas

Optimiza automaticamente as habilidades do teu agente utilizando um sistema multi-agente construído com **Google ADK (Agent Development Kit)** e **Gemini**. Carrega uma habilidade, deixa os agentes gerarem cenários de teste e critérios de avaliação, e depois observa como três agentes especializados do ADK colaboram para melhorar a tua habilidade através de otimização iterativa.

<img width="960" height="718" alt="Screenshot 2026-04-12 at 7 26 04 PM" src="https://github.com/user-attachments/assets/35a31f1a-398d-4797-a5d8-de538b4391e5" />

## Como Funciona

Esta aplicação implementa um ciclo automatizado de melhoria de habilidades inspirado na metodologia de autoresearch de Karpathy, alimentado por uma equipa de agentes ADK:

1. **Carregar**: Coloca a tua pasta de habilidades (seguindo a especificação de [agentskills.io](https://agentskills.io))
2. **Configurar**: O agente Executor gera cenários de teste e critérios de avaliação. Edita, adiciona ou regenera conforme necessário
3. **Otimizar**: Três agentes ADK colaboram - um executa e pontua, um diagnostica falhas, um aplica correções
4. **Resultados**: Descarrega a tua habilidade melhorada com um registo de alterações detalhado

### A Equipa de Agentes ADK

| Agente | Função | O Que Faz |
|-------|------|-------------|
| **Executor** | Executor de Habilidade & Pontuador | Executa a habilidade contra cenários de teste, pontua as saídas de acordo com os critérios de avaliação e gera cenários de teste iniciais durante a análise |
| **Analista** | Diagnóstico de Falhas | Examina avaliações falhadas, identifica causas raiz e recomenda uma estratégia de mutação. Usa o `output_schema` do Pydantic para garantir JSON estruturado |
| **Mutador** | Editor de Prompt | Faz exatamente UMA alteração direcionada ao prompt da habilidade com base no diagnóstico do analista. Usa o `output_schema` do Pydantic para garantir JSON estruturado |

### O Ciclo de Otimização

- O agente **Executor** executa a habilidade contra todos os cenários de teste
- O **Executor** então pontua cada saída de acordo com critérios de avaliação binários sim/não
- O agente **Analista** diagnostica padrões de falha e escolhe uma estratégia (`add_example`, `add_constraint`, `restructure`, ou `add_edge_case`)
- O agente **Mutador** aplica UMA correção cirúrgica ao prompt da habilidade
- O **Executor** re-executa e re-pontua a habilidade modificada
- As alterações são mantidas se a pontuação melhorar, revertidas se não
- Repete até que a taxa de aprovação alvo seja alcançada ou o número máximo de rondas seja atingido

## Arquitetura

```
self-improving-agent-skills/
├── backend/                 # FastAPI server + ADK optimization engine
│   ├── app.py              # REST API endpoints + SSE streaming
│   ├── adk_optimizer.py    # Multi-agent optimizer (Executor, Analyst, Mutator)
│   └── requirements.txt
├── frontend/               # Next.js + React + Tailwind
│   ├── src/
│   │   ├── app/            # Main page + layout
│   │   └── components/     # Upload, Config, Running, Results steps
│   ├── package.json
│   └── *.config.ts
│   ├── code-reviewer/
│   └── content-writer/
└── README.md
```

## Tech Stack

- **Backend**: Python 3.10+, FastAPI, Google ADK, Pydantic
- **Frontend**: Next.js 15, React 19, Tailwind CSS v4, Recharts
- **AI**: Google ADK sistema multi-agente com Gemini (`gemini-3-flash-preview`) - saída estruturada via `output_schema` nos agentes Analyst e Mutator
- **Tempo real**: Server-Sent Events (SSE) para progresso de otimização ao vivo

## Quick Start

### Configuração do Backend

```bash
cd backend

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Set up environment (optional - the app will prompt for your API key in the UI)
cp .env.example .env
# Edit .env and add your GOOGLE_API_KEY

# Run server
python app.py
# Server runs on http://localhost:8891
```

### Configuração do Frontend

Para configurar o frontend, segue os passos abaixo:

1. **Instalação das Dependências**
   ```bash
   npm install
   ```

2. **Iniciar o Servidor de Desenvolvimento**
   ```bash
   npm start
   ```

3. **Aceder à Aplicação**
   Abre o teu navegador e vai a `http://localhost:3000`.

### Estrutura de Ficheiros

A estrutura de ficheiros do projeto é a seguinte:

```
/src
  /components
  /pages
  /styles
  /utils
```

### Comandos Úteis

| Comando               | Descrição                          |
|----------------------|------------------------------------|
| `npm start`          | Inicia o servidor de desenvolvimento |
| `npm run build`      | Cria uma versão otimizada para produção |
| `npm test`           | Executa os testes do projeto       |

### Contribuição

Se quiseres contribuir para o projeto, segue os passos abaixo:

1. Faz um fork do repositório.
2. Cria uma nova branch para a tua funcionalidade:
   ```bash
   git checkout -b minha-funcionalidade
   ```
3. Faz as tuas alterações e commit:
   ```bash
   git commit -m "Adiciona nova funcionalidade"
   ```
4. Faz push da tua branch:
   ```bash
   git push origin minha-funcionalidade
   ```
5. Cria um Pull Request.

### Licença

Este projeto está licenciado sob a Licença MIT. Para mais detalhes, consulta o ficheiro `LICENSE`.

```bash
cd frontend

# Install dependencies
npm install

# Run development server
npm run dev
# App runs on http://localhost:3000
```

### Utilização

1. Obtém uma chave de API Gemini a partir de [Google AI Studio](https://aistudio.google.com/apikey)
2. Abre http://localhost:3000
3. Carrega uma pasta de skill como um ficheiro .zip (ou tenta um exemplo)
4. Introduz a tua chave de API Gemini
5. Revê e edita os cenários de teste gerados e os critérios de avaliação
6. Clica em "Iniciar Otimização" e observa os agentes a colaborar para melhorar a tua skill
7. Descarrega a tua skill melhorada quando estiver completa

## Formato da Skill

As skills seguem a especificação de [agentskills.io](https://agentskills.io):

```
my-skill/
├── SKILL.md           # Required: YAML frontmatter + instructions
├── scripts/           # Optional: executable code
├── references/        # Optional: additional docs
└── assets/            # Optional: templates, resources
```

```markdown
# SKILL

## Introdução

Este documento descreve como utilizar a SKILL para realizar tarefas específicas.

## Instalação

Para instalar a SKILL, utiliza o seguinte comando:

```bash
pip install skill
```

## Configuração

Após a instalação, deves configurar a SKILL. Cria um ficheiro de configuração em `~/.config/skill/config.yml` com o seguinte conteúdo:

```yaml
api_key: "YOUR_API_KEY"
```

Substitui `YOUR_API_KEY` pela tua chave de API.

## Uso

Para utilizar a SKILL, executa o seguinte comando:

```bash
skill run
```

### Comandos disponíveis

- `skill run`: Executa a SKILL.
- `skill status`: Mostra o estado atual da SKILL.
- `skill help`: Mostra a ajuda sobre os comandos disponíveis.

## Exemplos

Aqui estão alguns exemplos de como utilizar a SKILL:

### Exemplo 1

Para executar a SKILL com um parâmetro específico, utiliza:

```bash
skill run --param value
```

### Exemplo 2

Para verificar o estado da SKILL, utiliza:

```bash
skill status
```

## Contribuição

Se desejas contribuir para a SKILL, por favor, cria um fork do repositório e envia um pull request com as tuas alterações.

## Licença

Este projeto está licenciado sob a Licença MIT. Consulta o ficheiro `LICENSE` para mais informações.
```

```markdown
---
name: my-skill
description: What this skill does and when to use it
license: MIT
metadata:
  author: your-name
  version: "1.0"
---

# My Skill

Your skill instructions here...
```

## Experimenta

Comprime qualquer pasta de skill e faz o upload - por exemplo, a própria pasta project-graveyard deste repositório:

```bash
cd agent_skills
zip -r project-graveyard.zip project-graveyard/
```

## Como Funciona a Otimização Multi-Agente

### 1. Fase de Análise
O agente **Executor** analisa a tua skill e gera:
- 3-4 cenários de teste diversos
- 4-6 critérios de avaliação binários (perguntas sim/não)

Podes editar, adicionar ou remover cenários e critérios antes de a otimização começar.

### 2. Execução Base
O agente **Executor** executa a skill em todos os cenários e pontua cada saída em relação a todos os critérios de avaliação. Isto estabelece a pontuação inicial.

### 3. Ciclo de Otimização
Para cada ronda, os três agentes colaboram:
1. O **Executor** executa a skill em todos os cenários de teste e pontua as saídas
2. O **Analista** examina falhas, identifica a causa raiz e seleciona uma estratégia de mutação (retorna JSON estruturado via `output_schema`)
3. O **Mutador** aplica UMA alteração específica para melhorar a skill (retorna JSON estruturado via `output_schema`)
4. O **Executor** executa novamente e reavalia a skill modificada
5. A pontuação é comparada - mantém a alteração se houver melhoria, reverte se não
6. Repete até atingir a taxa de aprovação alvo ou o número máximo de rondas

### 4. Saída
- SKILL.md melhorada com todas as alterações bem-sucedidas aplicadas
- Registo detalhado das alterações e razões
- Comparação de desempenho (base vs final)

## Endpoints da API

| Método | Endpoint | Descrição |
|--------|----------|-------------|
| `POST` | `/api/upload` | Carregar ficheiro zip da skill (máx 10MB, apenas ficheiros de texto) |
| `POST` | `/api/upload-files` | Carregar múltiplos ficheiros (carregamento de pasta) |
| `POST` | `/api/analyze` | Gerar cenários e avaliações (requer chave da API Gemini) |
| `POST` | `/api/regenerate` | Regenerar cenários e avaliações |
| `POST` | `/api/update-config` | Guardar a configuração selecionada/editada pelo utilizador |
| `POST` | `/api/start/{session_id}` | Iniciar otimização |
| `GET` | `/api/stream/{session_id}` | Stream SSE do progresso da otimização |
| `POST` | `/api/stop/{session_id}` | Parar otimização |
| `GET` | `/api/download/{session_id}` | Descarregar skill melhorada |
| `GET` | `/api/examples` | Listar skills de exemplo disponíveis |
| `POST` | `/api/examples/{name}/load` | Carregar uma skill de exemplo |
| `GET` | `/api/status/{session_id}` | Endpoint de status baseado em polling |
| `GET` | `/health` | Verificação de saúde |

## Configuração

### Backend

A chave da API Gemini é passada do frontend com cada pedido. Opcionalmente, define `GOOGLE_API_KEY` em `.env` para desenvolvimento local. O servidor corre na porta **8891**.

Limites de upload:
- **10MB** tamanho total máximo de upload
- **1MB** máximo por ficheiro
- **50** máximo de ficheiros por upload
- Apenas ficheiros de texto (`.md`, `.txt`, `.json`, `.yaml`, `.py`, `.js`, `.ts`, etc.)

As sessões expiram automaticamente após **1 hora**.

### Frontend

A chave da API é introduzida na interface, armazenada no estado do componente (não persistente) e enviada com cada pedido. A chave é passada para o backend que define `GOOGLE_API_KEY` para autenticação do agente ADK.

### Parâmetros de Otimização

Em `RunningStep.tsx`, ajusta `max_rounds` (limitado a 50):

```typescript
body: JSON.stringify({
  max_rounds: 20,  // Default: 20, max: 50
}),
```

```markdown
# Ajustar o Modelo em `adk_optimizer.py`

Para ajustar o modelo em `adk_optimizer.py`, segue os passos abaixo:

## Passo 1: Importar Bibliotecas Necessárias

Certifica-te de que importas as bibliotecas necessárias no início do teu ficheiro:

```python
import numpy as np
import pandas as pd
from sklearn.model_selection import train_test_split
from sklearn.ensemble import RandomForestClassifier
```

## Passo 2: Carregar os Dados

Carrega os dados que pretendes utilizar para o ajuste do modelo:

```python
data = pd.read_csv('caminho/para/o/teu/dataset.csv')
```

## Passo 3: Pré-processar os Dados

Realiza o pré-processamento necessário nos dados:

```python
X = data.drop('target', axis=1)
y = data['target']
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=42)
```

## Passo 4: Ajustar o Modelo

Agora, ajusta o modelo utilizando o `RandomForestClassifier`:

```python
model = RandomForestClassifier(n_estimators=100, random_state=42)
model.fit(X_train, y_train)
```

## Passo 5: Avaliar o Modelo

Por fim, avalia o desempenho do modelo:

```python
accuracy = model.score(X_test, y_test)
print(f'Acurácia do modelo: {accuracy:.2f}')
```

Seguindo estes passos, deves conseguir ajustar o modelo em `adk_optimizer.py` com sucesso.
```

```python
def __init__(self, api_key: str, model: str = "gemini-3-flash-preview"):
```

## Desenvolvimento

### Testes de Backend

```bash
cd backend
python -c "from adk_optimizer import SkillOptimizer; print('OK')"
```

### Construção do Frontend

Para construir o frontend, segue os passos abaixo:

1. **Instalação das Dependências**
   ```bash
   npm install
   ```

2. **Construção do Projeto**
   Para construir o projeto, executa o seguinte comando:
   ```bash
   npm run build
   ```

3. **Executar o Servidor de Desenvolvimento**
   Para iniciar o servidor de desenvolvimento, utiliza:
   ```bash
   npm start
   ```

### Estrutura de Diretórios

A estrutura de diretórios do projeto é a seguinte:

```
/src
  /components
  /pages
  /styles
/public
  index.html
```

### Scripts Disponíveis

| Comando           | Descrição                          |
|-------------------|------------------------------------|
| `npm start`       | Inicia o servidor de desenvolvimento |
| `npm run build`   | Cria uma versão otimizada para produção |
| `npm test`        | Executa os testes do projeto       |

### Contribuição

Se quiseres contribuir para o projeto, segue estas etapas:

1. Faz um fork do repositório.
2. Cria uma nova branch para a tua funcionalidade:
   ```bash
   git checkout -b minha-nova-funcionalidade
   ```
3. Faz as tuas alterações e commit:
   ```bash
   git commit -m 'Adiciona nova funcionalidade'
   ```
4. Faz push para a branch:
   ```bash
   git push origin minha-nova-funcionalidade
   ```
5. Abre um Pull Request.

```bash
cd frontend
npm run build
```

### Desenvolvimento em Tempo Real

Ambos os servidores suportam recarregamento a quente. Edita o código e vê as alterações imediatamente.

## Baseado na Autoresearch de Karpathy

Esta ferramenta aplica a metodologia de autoresearch de Andrej Karpathy (usando LLMs para melhorar iterativamente os seus próprios prompts) às habilidades dos agentes. A chave: em vez de ajustar manualmente os prompts, define critérios de sucesso e deixa a IA otimizar-se - agora potenciada por uma equipa de agentes ADK especializados.

Conceito original: [https://github.com/karpathy/autoresearch](https://github.com/karpathy/autoresearch)

## Poupe horas todas as semanas com IA, sem complicações

O **Doutor AI** dá-lhe 1859 prompts de IA prontos a copiar, por indústria e em português simples - mais uma biblioteca técnica completa para quem quer ir mais longe. [Ver planos →](https://doutorai.pt/precos)

---
Conteúdo de Doutor AI (https://doutorai.pt). Ao citar, indique a fonte: https://doutorai.pt/apps/self-improving-agent-skills