Spaces:

Agents-MCP-Hackathon
/

GALITA2

Configuration error

App Files Files Community

GALITA2 / README.md

ALag

Upload 10 files

d4ea4e5 verified 5 months ago

preview code

raw

history blame contribute delete

12.5 kB

Gradio-hackathon : Generalist self-evolving ai agent inspired by Alita

This is my team project for the gradio hackathon 2025 This Project is inspired by research paper : https://arxiv.org/abs/2505.20286

📁 Structure du projet

alita_agent/
│
├── main.py                           # Point d'entrée principal : exécute un TaskPrompt via le ManagerAgent
├── manager_agent.py                  # Logique de coordination centrale, il orchestre tous les composants
├── task_prompt.py                    # Définit la classe TaskPrompt, contenant la requête utilisateur initiale
│
├── components/                       # Contient tous les composants fonctionnels modulaires
│   ├── __init__.py                   # Rends le dossier importable comme un package
│   ├── script_generator.py           # Génère dynamiquement du code Python à partir d'un MCPToolSpec
│   ├── code_runner.py                # Exécute un script dans un environnement isolé et capture le résultat
│   ├── mcp_registry.py               # Gère l'enregistrement, la recherche et la réutilisation des outils MCP
│   ├── web_agent.py                  # Effectue des recherches web ou GitHub pour aider à la génération de code
│   └── mcp_brainstormer.py           # Génère des MCPToolSpec en analysant la tâche utilisateur
│
├── models/                           # Contient les classes de données (dataclasses) utilisées dans tout le système
│   ├── __init__.py                   # Rends le dossier importable comme un package
│   ├── mcp_tool_spec.py              # Définition de MCPToolSpec (dataclass) : nom, schémas I/O, description, pseudo-code, etc.
│   └── mcp_execution_result.py       # Définition de MCPExecutionResult (dataclass) : succès, sortie, logs, erreur
│
├── tests/                            # Contient les tests unitaires pour chaque module
│   ├── __init__.py                   # Rends le dossier importable comme un package
│   ├── test_script_generator.py      # Tests pour vérifier la génération correcte de code et d'environnements
│   ├── test_code_runner.py           # Tests pour s'assurer de la bonne exécution des scripts et gestion d'erreurs
│   ├── test_mcp_registry.py          # Tests de l'enregistrement, recherche et appel d'outils dans le registre MCP
│   └── test_manager_agent.py         # Tests d'intégration sur le comportement global du ManagerAgent
│
└── README.md                         # Documentation du projet, instructions, pipeline, inspirations et lien vers le papier

Project Pipeline

🔄 Le flux complet avec vérification de l'existence

L'utilisateur envoie un TaskPrompt
Le Manager Agent demande au MCPBrainstormer : "Quels outils faudrait-il pour résoudre cette tâche ?"
Le Brainstormer propose une ou plusieurs specs (MCPToolSpec)
Le Manager Agent consulte le MCPRegistry : "Ai-je déjà un outil enregistré dont le nom + I/O matchent cette spec ?"
- Oui ? ➜ réutilise l'outil existant
- Non ? ➜ il appel le web agent pour une recherche d'outils open-source pour implementer. Puis, le Manager prend la recherche et la donne a Brainstormer pour commencer la construction.

🔍 Comment détecter que l'outil existe déjà ?

Par matching sur la spec MCPToolSpec :

Nom exact (ou identifiant unique comme un hash)
Ou plus intelligemment :
- même structure input_schema
- même output_schema
- mêmes rôles ou description proche (avec embedding / vector search)

def check_existing_tool(spec: MCPToolSpec, registry: MCPRegistry) -> Optional[str]:
    for registered_spec in registry.list_tools():
        if registered_spec.input_schema == spec.input_schema and \
           registered_spec.output_schema == spec.output_schema:
            return registry.get_tool_endpoint(registered_spec.name)
    return None

💬 Que fait l'agent s'il le trouve ?

Il ne régénère rien :

Il ajoute l'appel de l'outil MCP existant dans son plan
Il formate l'entrée JSON
Il appelle POST /predict directement
Il utilise la réponse dans la suite de son raisonnement

💡 Cas pratiques

Differents cas et Réaction attendue de l'agent

Situation réelle	Réaction de l'agent
L'outil `"SubtitleExtractor"` existe déjà	L'agent appelle directement l'endpoint
Le spec est proche mais pas identique	L'agent peut quand même le réutiliser (avec adaptation)
L'outil existe mais a échoué	L'agent peut fallback vers génération d'un nouvel outil MCP
L'outil existe mais est obsolète	Le Registry peut signaler une mise à jour ou déclencher une régénération

Fonctions attendues

Classe	Méthode attendue	Présente ?	Commentaire
`ManagerAgent`	`run_task(prompt)`	✅	OK
`MCPBrainstormer`	`brainstorm(prompt)`	✅	OK
`WebAgent`	`search_github`, `retrieve_readme`	✅	OK
`ScriptGenerator`	`generate_code`, `generate_env_script`	✅	OK
`CodeRunner`	`execute`, `setup_environment`	✅	OK
`MCPRegistry`	`register_tool`, `list_tools`, `call_tool`	✅	OK
`MCPExecutionResult`	attributs `success`, `output`, `logs`	✅	OK
`MCPToolSpec`	`name`, `input_schema`, etc.	✅	OK

Ici Le ManagerAgent coordonne tout. Il délègue à :

MCPBrainstormer → pour générer des specs d'outils.
ScriptGenerator → pour générer du code.
CodeRunner → pour tester le code.
WebAgent → pour récupérer du contexte externe.
MCPRegistry → pour enregistrer et réutiliser les outils.

plantuml -tsvg README.md

Voir le script PlantUML

```plantuml @startuml alitaDiagram

skinparam classAttributeIconSize 0

' === Classes de données === class TaskPrompt { - text: str }

class MCPToolSpec { - name: str - input_schema: dict - output_schema: dict - description: str - pseudo_code: str - source_hint: str }

class MCPExecutionResult { - success: bool - output: dict - logs: str - error_message: str }

class ToolCall {

tool_name: str
input_data: dict
result: dict }

' === Agents principaux === class ManagerAgent { - brainstormer: MCPBrainstormer - web_agent: WebAgent - generator: ScriptGenerator - runner: CodeRunner - registry: MCPRegistry + run_task(prompt: TaskPrompt): dict + check_existing_tool(spec: MCPToolSpec) -> Optional[str] }

class MCPBrainstormer { + brainstorm(prompt: TaskPrompt): List }

class WebAgent { + search_github(query: str): str + retrieve_readme(repo_url: str): str }

class ScriptGenerator { + generate_code(spec: MCPToolSpec): str + generate_env_script(spec: MCPToolSpec): str }

class CodeRunner { + execute(script: str): MCPExecutionResult + setup_environment(env_script: str): bool }

class MCPRegistry { + register_tool(spec: MCPToolSpec, endpoint_url: str): void + list_tools(): List + call_tool(tool: str): object }

' === Relations avec types + cardinalités ===

' Le Manager reçoit une tâche utilisateur TaskPrompt --> "1" ManagerAgent : provides query

' Manager appelle le Brainstormer ManagerAgent --> "1" MCPBrainstormer : calls

' Manager utilise WebAgent ManagerAgent "1" <--> "1" WebAgent : queries/answers

' Brainstormer appelle ScriptGenerator et CodeRunner MCPBrainstormer --> "1" ScriptGenerator : plans MCPBrainstormer --> "1" CodeRunner : validates

' Manager consulte ou enregistre dans le Registry ManagerAgent --> "1" MCPRegistry : checks/updates

' Manager construit un plan d'appel d'outils ManagerAgent --> "0..*" ToolCall : creates

' Brainstormer retourne des MCPToolSpec MCPBrainstormer --> "1..*" MCPToolSpec : returns

' ScriptGenerator utilise MCPToolSpec pour générer ScriptGenerator --> "1" MCPToolSpec : consumes

' Registry enregistre des ToolSpecs MCPRegistry --> "0..*" MCPToolSpec : stores

' CodeRunner renvoie un résultat d'exécution CodeRunner --> "1" MCPExecutionResult : returns

' CodeRunner peut utiliser des outils enregistrés CodeRunner --> "0..*" MCPRegistry : queries

@enduml

</details> 
</div>

# ALITA Research Functionality

This README explains how to use the comprehensive research capabilities of the ALITA ManagerAgent.

## Overview

ALITA can now perform deep, autonomous web research using the WebAgent's research functionality. This allows ALITA to gather information from multiple sources, analyze it, and synthesize a comprehensive report on any topic.

## Usage Methods

There are two ways to use the research functionality:

### 1. Direct Research Method

Call the `research` method directly on the ManagerAgent instance:

```python
from manager_agent2 import ManagerAgent
from llama_index.llms.anthropic import Anthropic

# Initialize the LLM and ManagerAgent
llm = Anthropic(model="claude-3-5-sonnet-20241022", api_key="your-api-key")
manager = ManagerAgent(llm=llm)

# Perform research directly
report = manager.research(
    query="What are the latest developments in quantum computing?",
    max_iterations=50,  # Optional: limit the number of research steps
    verbose=True        # Optional: show detailed progress
)

# The report variable now contains a comprehensive research report
print(report)

2. Tool-Based Research through ReActAgent

Let the ManagerAgent's internal ReActAgent decide when to use research:

from manager_agent2 import ManagerAgent
from models import TaskPrompt
from llama_index.llms.anthropic import Anthropic

# Initialize the LLM and ManagerAgent
llm = Anthropic(model="claude-3-5-sonnet-20241022", api_key="your-api-key")
manager = ManagerAgent(llm=llm)

# Create a task prompt
task_prompt = TaskPrompt(text="I need a comprehensive report on recent developments in quantum computing.")

# Run the task through the agent
response = manager.run_task(task_prompt)

# The response will include the research report if the agent determined research was needed
print(response)

The agent will automatically detect when deep research is required based on keywords like "comprehensive," "thorough," "research," etc.

Running the Test Script

A test script is provided to demonstrate both usage methods:

python test_research.py

Make sure to set your Anthropic API key in the environment or in a .env file before running the script.

System Prompt Configuration

The ManagerAgent's system prompt has been updated to include guidance on when to use the research tool:

For simple information needs: use 'web_search' for quick answers
For complex research topics: use 'perform_web_research' for comprehensive autonomous research

How Research Works

When ALITA performs research:

It first analyzes the research query to understand what information is needed
It uses web search to gather relevant sources
It visits and reads the content of each source
It downloads and analyzes relevant documents if needed
It evaluates the credibility and relevance of each source
It synthesizes the information into a comprehensive report
It includes citations and references to the sources used

This enables ALITA to provide high-quality, well-researched answers to complex questions.