Competências de Agentes 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.

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)
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

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

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

npm install

2. Iniciar o Servidor de Desenvolvimento

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

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:

git checkout -b minha-funcionalidade

3. Faz as tuas alterações e commit:

git commit -m "Adiciona nova funcionalidade"

4. Faz push da tua branch:

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.

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
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:

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

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:

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:

api_key: "YOUR_API_KEY"

Substitui YOUR_API_KEY pela tua chave de API.

Uso

Para utilizar a SKILL, executa o seguinte comando:

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:

skill run --param value

Exemplo 2

Para verificar o estado da SKILL, utiliza:

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.

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:

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

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):

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

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:

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:

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

Passo 3: Pré-processar os Dados

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

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:

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:

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.

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

Desenvolvimento

Testes de Backend

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

npm install

2. Construção do Projeto

Para construir o projeto, executa o seguinte comando:

npm run build

3. Executar o Servidor de Desenvolvimento

Para iniciar o servidor de desenvolvimento, utiliza:

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

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:

git checkout -b minha-nova-funcionalidade

3. Faz as tuas alterações e commit:

git commit -m 'Adiciona nova funcionalidade'

4. Faz push para a branch:

git push origin minha-nova-funcionalidade

5. Abre um Pull Request.

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