https://github.com/femto/minion
👷‍♂️Minion is Agent's Brain. Minion is designed to execute any type of queries, offering a variety of features that demonstrate its flexibility and intelligence.
https://github.com/femto/minion
agent ai python
Last synced: 6 months ago
JSON representation
👷‍♂️Minion is Agent's Brain. Minion is designed to execute any type of queries, offering a variety of features that demonstrate its flexibility and intelligence.
- Host: GitHub
- URL: https://github.com/femto/minion
- Owner: femto
- License: mit
- Created: 2024-08-11T12:05:35.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2026-01-06T04:52:03.000Z (6 months ago)
- Last Synced: 2026-01-08T10:14:17.168Z (6 months ago)
- Topics: agent, ai, python
- Language: Python
- Homepage:
- Size: 3.42 MB
- Stars: 94
- Watchers: 3
- Forks: 12
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Security: SECURITY.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
[](https://github.com/femto/minion)
[](https://github.com/femto/minion#get-started)
[](https://discord.gg/HUC6xEK9aT)
[](https://x.com/femtowin)
[](https://deepwiki.com/femto/minion)
# Minion
[](https://smithery.ai/skills?ns=femto&utm_source=github&utm_medium=badge)
Minion is Agent's Brain. Minion is designed to execute any type of queries, offering a variety of features that demonstrate its flexibility and intelligence.
## Installation
### Basic Installation
```bash
git clone https://github.com/femto/minion.git && cd minion
pip install -e .
cp config/config.yaml.example config/config.yaml
cp config/.env.example config/.env
```
### Optional Dependencies
The project uses optional dependency groups to avoid installing unnecessary packages. Install only what you need:
```bash
# Development tools (pytest, black, ruff)
pip install -e ".[dev]"
# Google ADK and LiteLLM support
pip install -e ".[google]"
# Browser automation (browser-use)
pip install -e ".[browser]"
# Gradio web UI
pip install -e ".[gradio]"
# UTCP support
pip install -e ".[utcp]"
# AWS Bedrock support
pip install -e ".[bedrock]"
# Anthropic Claude support
pip install -e ".[anthropic]"
# Web tools (httpx, beautifulsoup4, etc.)
pip install -e ".[web]"
# Install ALL optional dependencies
pip install -e ".[all]"
# You can also combine multiple groups:
pip install -e ".[dev,gradio,anthropic]"
```
Edit `config/config.yaml`:
```yaml
models:
"default":
api_type: "openai"
base_url: "${DEFAULT_BASE_URL}"
api_key: "${DEFAULT_API_KEY}"
model: "gpt-4.1"
temperature: 0
```
See [Configuration](#configuration) for more details on configuration options.
## Quick Start
### Using CodeAgent (Recommended)
```python
from minion.main.agent import CodeAgent
# Create agent
agent = await CodeAgent.create(
name="Minion Code Assistant",
llm="your-model",
tools=all_tools, # optional
)
# Run task
async for event in await agent.run_async("your task here"):
print(event)
```
See [examples/mcp/mcp_agent_example.py](examples/mcp/mcp_agent_example.py) for a complete example with MCP tools.
### Using Brain
```python
from minion.main.brain import Brain
brain = Brain()
obs, score, *_ = await brain.step(query="what's the solution 234*568")
print(obs)
```
See [Brain Usage Guide](docs/brain_usage.md) for more examples.
## Quick Demo
[](https://youtu.be/-LW7TCMUfLs?si=-pL9GhNfbjFtNagJ)
*Click to watch the demo video on YouTube.*
## Working Principle
The flowchart demonstrates the complete process from query to final result:
1. First receives the user query (Query)
2. System generates a solution (Solution)
3. Performs solution verification (Check)
4. If unsatisfactory, makes improvements (Improve) and returns to generate new solutions
5. If satisfactory, outputs the final result (Final Result)
## Documentation
- [CodeAgent Documentation](docs/merged_code_agent.md) - Powerful Python code execution agent
- [Brain Usage Guide](docs/brain_usage.md) - Using brain.step() for various tasks
- [Skills Guide](docs/skills.md) - Extend agent capabilities with modular skills
- [Benchmarks](docs/benchmarks.md) - Performance results on GSM8K, Game of 24, AIME, Humaneval
- [Route Parameter Guide](docs/agent_route_parameter_guide.md) - Route options for different reasoning strategies
- [Gradio UI Guide](docs/gradio_ui_guide.md) - Web interface for Minion
## Configuration
### Configuration File Locations
1. **Project Config**: `MINION_ROOT/config/config.yaml` - Default project configuration
2. **User Config**: `~/.minion/config.yaml` - User-specific overrides
### Configuration Priority
When both configuration files exist:
- **Project Config** takes precedence over **User Config**
This allows you to:
- Keep sensitive data (API keys) in your user config
- Share project defaults through the project config
### Environment Variables
**Variable Substitution**: Use `${VAR_NAME}` syntax to reference environment variables directly in config values:
```yaml
models:
"default":
api_key: "${OPENAI_API_KEY}"
base_url: "${OPENAI_BASE_URL}"
api_type: "openai"
model: "gpt-4.1"
temperature: 0.3
```
**Loading .env Files**: Use `env_file` to load environment variables from `.env` files (follows Docker `.env` file format):
```yaml
env_file:
- .env
- .env.local
```
Variables defined in these files will be available for `${VAR_NAME}` substitution throughout the configuration.
### MINION_ROOT Detection
`MINION_ROOT` is determined automatically:
1. Checks `MINION_ROOT` environment variable (if set)
2. Auto-detects by finding `.git`, `.project_root`, or `.gitignore` in parent directories
3. Falls back to current working directory
Check the startup log:
```
INFO | minion.const:get_minion_root:44 - MINION_ROOT set to:
```
> **Warning**: Be cautious - LLM can generate potentially harmful code.
## Community and Support
[](https://discord.gg/HUC6xEK9aT)
[](https://x.com/femtowin)
WeChat Group (minion-agent discussion):
