convez.ai
SkillAutomaçãoAvançado
onewaymyway

Mini Agent

onewaymyway/mini_agent

Agent inteligente Python com múltiplos LLMs, skills e orquestração concorrente

Ver no GitHub
InicialPluginScore · de 0 a 100

Framework em Python que implementa um agent inteligente simplificado com suporte a múltiplos provedores de LLM (Anthropic, OpenAI, Ollama, NVIDIA), sistema de skills, orquestração de sub-agents concorrentes e chamadas de ferramentas completas. Inclui API REST, interface web com Streamlit, busca na web integrada e suporte a Model Context Protocol (MCP).

Instalação

$npx convez-ai onewaymyway/mini_agent

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 1 dia
Versão
v0.9.8
Issues abertas
0
Contribuidores
1

Casos de uso

  • Automação de tarefas complexas com execução paralela de sub-agents
  • Desenvolvimento de aplicações que precisam integrar múltiplos provedores de IA
  • Criação de agentes com capacidade de busca web e execução de ferramentas do sistema
  • Orquestração de fluxos de trabalho que demandam chamadas concorrentes a LLMs

Veredito

Mini Agent é uma solução madura e bem-estruturada para quem precisa construir agents inteligentes com arquitetura sofisticada. Excelente para orquestração concorrente e integração multi-LLM, mas requer expertise técnica em Python e compreensão de fluxos assíncronos.

README

A tradução para o português deste README ainda está na fila.

mini-agent

一个用 Python 实现的简化版 Claude Code,支持多 LLM 提供商、Skill 机制、并发 Sub-Agent 编排和完整的工具调用体系。

Python 3.10+ License: MIT

特性

特性说明
🤖 多 LLM 支持Anthropic、OpenAI、Ollama、NVIDIA NIM,一行配置切换
🔧 系统工具调用工具通过 System Prompt 注入,兼容所有模型
📚 Skill 机制SKILL.md 文件动态加载,自动触发注入上下文
📝 Prompt 管理所有 prompt 统一在 prompts/ 目录管理
⚡ 并发 Sub-Agent主 Agent 可派生多个子 Agent 并行执行任务,支持自动重试(HTTP 5xx/超时最多 3 次)
🔐 权限守卫危险操作需要确认,支持白名单、黑名单、沙箱模式,路径规范化处理
🐛 调试日志完整记录每次请求/响应到 JSONL 文件
🧠 感知与记忆项目扫描、文件监视、工具缓存、跨 session 长期记忆
🌐 HTTP API内置 REST/SSE 服务,支持外部程序通过 HTTP 与 agent 交互
🖥️ Web DemoStreamlit 图形界面,提供浏览器操作的对话界面
🔌 MCP 支持Model Context Protocol 集成,支持 stdio/SSE 传输,可扩展外部工具服务
🔍 Web Search支持 DuckDuckGo(默认)、Brave、Serper、Tavily 等多种搜索后端
🤖 自定义子 Agent预设角色模板(.agent/agents/*.md),结构化参数注入,支持工具/模型限制
🔗 Hooks 机制关键事件自动执行 shell 命令,支持拦截/修改工具调用,项目级/全局级配置
🎯 Task 日志实时查看运行时方向键切换查看不同任务日志,状态栏显示任务状态概要

快速开始

安装

# 克隆项目
git clone https://github.com/onewaymyway/mini_agent.git
cd mini_agent

# 安装依赖
pip install -r requirements.txt

配置 API Key

# 配置 API Key linux
export ANTHROPIC_API_KEY=sk-...
export NVIDIA_API_KEY=sk-...
export BRAVE_API_KEY=...  # 可选:使用 Brave Search
export SERPER_API_KEY=...  # 可选:使用 Serper
export TAVILY_API_KEY=...  # 可选:使用 Tavily

# 配置 API Key win
$env:ANTHROPIC_API_KEY=sk-...
$env:NVIDIA_API_KEY=sk-...
$env:BRAVE_API_KEY=...
$env:SERPER_API_KEY=...
$env:TAVILY_API_KEY=...

运行

# 交互式模式(推荐)
python -m mini_agent

# 或使用传统入口
python main.py

# 单次命令模式
python -m mini_agent "写一个质数筛法的 Python 脚本"

# 使用指定模型
python -m mini_agent --model claude-haiku-4-5

# 沙箱模式(安全测试)
python -m mini_agent --sandbox

# 更多参数
python main.py --provider nvidia --model qwen/qwen3.5-122b-a10b --system-tool-call --system-msg-format system_role

命令行参数

参数说明
--model, -m指定使用的模型
--providerLLM 提供商:anthropic|openai|ollama|nvidia
--base-url自定义 API 端点
--agent-nameAgent 显示名称(默认:orzooo)
--sandbox沙箱模式
--yes, -y自动批准所有工具调用
--debug-llm启用调试日志
--max-llm-calls最大并发 LLM 调用数(默认 8)
--workers最大并发子 Agent 数(默认 4)
--session-dirSession 文件保存目录
--resume恢复之前的对话
--system-tool-call启用系统工具调用格式
--memory启用跨 session 记忆
--project-scan启动时扫描项目结构
--file-watch监听文件变化
--web-search-provider指定搜索后端:duckduckgo|brave|serper|tavily
--http启动内置 HTTP API 服务
--http-portHTTP 服务监听端口(默认 8765)
--http-hostHTTP 服务监听地址(默认 127.0.0.1)
--http-tokenHTTP API 认证令牌
--http-allow-ip允许的 IP 地址列表
--http-fs-readonly文件系统只读模式
--http-ring-maxlen事件环缓冲区大小

MCP 集成

mini-agent 支持 Model Context Protocol (MCP),允许通过标准化协议连接外部工具服务。

快速开始

  1. 安装 MCP SDK:
pip install mcp
  1. 配置 agent_config.json(已预配置 time_server):
{
  "mcp_servers": [
    {
      "name": "time_server",
      "transport": "stdio",
      "command": "python",
      "args": ["mcp_servers/time_server.py"],
      "auto_approve": true
    }
  ]
}
  1. 启动 Agent,会自动连接 MCP server:
python -m mini_agent

启动后会显示:

[mcp] Connected: 'time_server' (3 tools: get_current_time, calculate, echo)

可用 MCP 工具

工具描述
get_current_time(timezone?)获取当前时间,支持 IANA 时区(如 Asia/Shanghai)
calculate(expression)安全计算数学表达式(四则运算、sqrt、log、sin 等)
echo(message)原样返回消息,用于测试连通性

配置选项

字段说明
nameServer 唯一标识
transport"stdio" 或 "sse"
command/argsstdio 模式的命令和参数
urlSSE 模式的 endpoint
auto_approve是否免审批
timeout连接与调用超时(秒)

详细文档参见 MCP 使用指南。

Web Demo

使用 Streamlit 启动浏览器交互界面:

# 安装依赖
pip install streamlit requests

# 启动 HTTP 服务(先启动 mini-agent)
python -m mini_agent --http --http-port 8765

# 启动 Web Demo
streamlit run apps/mini_agent_webdemo/app.py

Web Demo 提供:

  • 📱 浏览器对话界面
  • 🔌 HTTP API 连接配置(支持 Token 认证)
  • 🔐 权限审批交互式面板(内联实时渲染)
  • 📡 实时事件流监控(SSE)
  • 📁 文件系统浏览
  • 📊 Turn 历史记录
  • ⌨️ 快捷审批指令(y/a/n/d 直接输入)
  • ✏️ Bash 命令在线编辑

注意:需要先启动 HTTP 服务,Web Demo 才能连接到 Agent。

REPL 命令

进入交互式模式后,支持以下斜杠命令:

命令说明
/help显示帮助
/clear清除对话历史
/stats显示会话统计
/skills列出所有技能
/skill on|off <name>激活/停用技能
/agents列出自定义子 agent profiles
/agents show <name>显示 profile 详细信息
/agents reload重新扫描子 agent profiles
/hooks列出已加载的 hooks
/hooks reload重新加载 hooks 配置
/model <name>切换模型
/provider list|switch <name>列出/切换提供者
/session list|save|load管理会话
/tasks显示子任务状态
/tasks focus <id>进入指定任务焦点模式(实时查看日志)
/tasks unfocus退出任务焦点模式
/tasks dashboard实时任务看板
/tasks log <id>查看任务日志
/tasks cancel <id>取消任务
/concurrency查看并发状态
/compact压缩对话历史
/prompts列出所有提示词文件
/retry重试上一轮
/rollback回退上一轮

键盘快捷键(Task 日志查看)

运行 Task 时支持以下快捷键实时切换查看任务日志:

按键功能
→ 或 ↓进入/切换到下一个任务日志视图
← 或 ↑切换到上一个任务日志视图
ESC退出任务焦点模式

详见 Task 日志实时查看指南。

命令行输入补全

安装 prompt_toolkit 后(自动安装在 requirements.txt 中),REPL 提供以下输入补全功能:

  • Slash 命令补全:输入 / 触发所有命令列表,显示命令描述和子命令提示
  • 子命令补全:如输入 /skill 后弹出 on / off / list 子命令
  • 文件路径补全:输入 @src/ 触发文件路径补全
  • 模糊匹配:输入 /sess 即可匹配 /session 命令
  • 历史建议:灰色虚影显示历史命令,按 → 接受建议
  • Tab / Shift-Tab:在候选项间上下移动
  • 暗色主题:Catppuccin Mocha 风格补全菜单

内置工具

Agent 可以调用以下内置工具:

文件操作

  • read_file — 读取文件内容
  • write_file — 写入文件
  • create_file — 创建新文件
  • delete_file — 删除文件
  • patch_file — 补丁式编辑文件
  • list_dir — 列出目录内容
  • glob — 文件模式匹配
  • grep — 正则搜索

Shell 命令

  • bash — 执行 Shell 命令

Web Search

  • web_search — 网络搜索,支持 DuckDuckGo(默认)、Brave、Serper、Tavily 后端

并发编排

  • spawn_agent — 派生子 Agent
  • spawn_agents — 批量派生子 Agent
  • get_task_status — 查询任务状态
  • list_tasks — 列出所有任务
  • wait_for_tasks — 等待任务完成
  • cancel_task — 取消任务

规划与记忆

  • plan — 创建/更新规划
  • compact_history — 压缩历史并重附技能上下文
  • skill_list — 列出所有技能
  • skill_activate — 激活技能
  • skill_deactivate — 停用技能
  • ask_user — 询问用户输入
  • list_agent_profiles — 列出所有自定义子 agent profiles
  • spawn_named_agent — 派生预设角色的子 agent

项目结构

mini_agent/
├── main.py                  # 传统入口(兼容 shim)
├── pyproject.toml           # 项目元数据
├── requirements.txt         # 依赖列表
├── README.md                # 项目说明
├── CLAUDE.md                # 开发规范
├── src/                     # 源代码
│   └── mini_agent/
│       ├── __init__.py
│       ├── __main__.py      # 模块入口
│       ├── agent.py         # Agent 主类(对话循环与编排)
│       ├── context_builder.py  # System prompt 构建
│       ├── tool_executor.py    # 工具执行(权限 + 调用 + 截断 + 缓存)
│       ├── history_manager.py  # 历史管理(压缩/快照)
│       ├── config.py        # 配置管理
│       ├── permissions.py   # 权限守卫
│       ├── session.py       # 会话管理
│       ├── skills/          # 技能加载
│       │   ├── __init__.py
│       │   ├── tracker.py   # 技能使用追踪
│       │   └── usage_detector.py  # 使用检测
│       ├── cli/             # CLI 基础设施
│       │   ├── __init__.py
│       │   ├── app.py       # 应用启动入口
│       │   ├── parser.py    # 参数解析
│       │   ├── repl.py      # REPL 循环
│       │   └── commands/    # REPL 命令处理
│       │       ├── __init__.py
│       │       ├── concurrency.py
│       │       ├── plans.py
│       │       ├── providers.py
│       │       ├── sessions.py
│       │       ├── skills.py
│       │       ├── tasks.py
│       │       ├── agents.py
│       │       └── hooks.py
│       ├── llm/             # LLM 抽象层
│       │   ├── __init__.py
│       │   ├── base.py      # 基础接口
│       │   ├── factory.py   # 工厂模式
│       │   ├── retry.py     # 重试策略
│       │   ├── system_tool_call.py  # 工具调用格式
│       │   ├── debug_logger.py  # 调试日志
│       │   └── providers/   # LLM 提供商实现
│       │       ├── __init__.py
│       │       ├── _base_mixin.py
│       │       ├── anthropic.py
│       │       ├── openai.py
│       │       ├── ollama.py
│       │       └── nvidia.py
│       ├── tools/           # 工具系统
│       │   ├── __init__.py  # 工具注册表
│       │   ├── builtin.py   # 内置工具
│       │   ├── orchestration.py  # 并发编排工具
│       │   ├── skill_manager.py  # 技能管理
│       │   ├── plan.py      # 规划工具
│       │   └── user_input.py  # 用户输入工具
│       ├── orchestrator/    # 并发编排
│       │   ├── __init__.py
│       │   ├── task.py      # 任务定义
│       │   ├── task_manager.py  # 任务调度
│       │   ├── sub_agent.py # 子 Agent
│       │   ├── concurrency.py  # 并发控制
│       │   ├── status_bar.py  # 状态栏显示
│       │   ├── plan.py      # 执行计划
│       │   ├── plan_display.py  # 计划 UI
│       │   ├── task_display.py  # 任务显示
│       │   └── agent_profiles.py  # 自定义 agent profile
│       ├── perception/      # 感知与记忆
│       │   ├── __init__.py
│       │   ├── project_scanner.py  # 项目结构扫描
│       │   ├── file_watcher.py     # 文件变化监听
│       │   ├── tool_cache.py       # 工具结果缓存
│       │   ├── memory_store.py     # 跨 session 记忆
│       │   ├── memory_base.py      # 记忆后端抽象
│       │   ├── memory_factory.py   # 记忆工厂
│       │   └── token_counter.py    # Token 预估
│       ├── ui/              # 用户界面
│       │   ├── __init__.py
│       │   ├── terminal.py  # 终端 I/O
│       │   ├── renderer.py  # 终端输出渲染
│       │   └── repl_input.py  # REPL 输入
│       ├── api/             # HTTP API 服务
│       │   ├── __init__.py
│       │   ├── server.py    # HTTP 服务封装
│       │   ├── routes.py    # API 路由
│       │   ├── bridge.py    # Agent 桥梁
│       │   ├── auth.py      # 认证中间件
│       │   ├── models.py    # 数据模型
│       │   └── fs_helper.py # 文件系统助手
│       ├── history/         # 历史管理
│       │   ├── __init__.py
│       │   └── compression.py  # 压缩算法
│       ├── prompts/         # Prompt 管理
│       │   ├── __init__.py
│       │   ├── manager.py   # PromptManager
│       │   ├── system/      # 系统提示词
│       │   ├── fragments/   # 文本片段
│       │   └── user/        # 用户消息
│       ├── hooks/           # hooks 机制
│       │   ├── __init__.py
│       │   ├── loader.py    # HookManager
│       │   └── runner.py    # HookResult
│       ├── mcp/             # MCP 支持
│       │   ├── __init__.py
│       │   ├── config.py    # 配置
│       │   ├── transport.py # 传输层
│       │   └── manager.py   # MCPManager
│       └── storage/         # 存储层
│           ├── __init__.py
│           └── paths.py     # 路径管理
├── apps/                    # Web 应用
│   └── mini_agent_webdemo/ # Streamlit Web Demo
│       └── app.py
├── prompts/                 # 提示词模板(外部)
├── skills/                  # 技能定义(外部)
├── tests/                   # 单元测试
├── docs/                    # 文档
├── sessions/                # 会话历史(生成)
├── mcp_servers/             # MCP 服务器示例
├── .agent/                  # 自定义子 agent profiles
│   └── agents/              # profile 文件 (*.md)
└── hooks/                   # hooks 示例脚本

架构设计

┌─────────────────────────────────────────────────────────┐
│                    CLI / REPL                          │
└──────────────────────────┬──────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────┐
│                  Agent (agent.py)                       │
│     对话循环 · 工具派发 · 流式输出                      │
├─────────────────────────────────────────────────────────┤
│  ┌───────────────┐  ┌───────────────┐  ┌─────────────┐│
│  │ContextBuilder │  │ ToolExecutor  │  │HistoryMgr   ││
│  │ (System Prompt)│  │ (权限 + 调用)  │  │(历史/压缩)  ││
│  └───────────────┘  └───────────────┘  └─────────────┘┘
└───────┬─────────────────┬──────────────────┬──────────┘
        │                 │                  │
┌───────▼────────┐ ┌──────▼────────┐ ┌──────▼──────────┐
│   LLM Client   │ │  Tool Registry│ │  Perception     │
│  (多 Provider)   │ │  (内置/技能)  │ │  (缓存/记忆)    │
└────────────────┘ └───────────────┘ └─────────────────┘

扩展开发

添加新工具

from mini_agent.tools import tool

@tool(
    name="my_tool",
    description="执行某个操作",
    schema={
        "type": "object",
        "properties": {
            "param": {"type": "string", "description": "参数说明"}
        },
        "required": ["param"]
    },
    requires_approval=False
)
def my_tool(param: str) -> str:
    return f"结果:{param}"

在 src/mini_agent/cli/app.py 中导入模块注册工具。

添加新 Skill

在 .claude/skills/<skill-name>/SKILL.md 创建技能文件:

---
name: my-skill
description: 我的扩展功能
triggers: keyword1, keyword2
---

技能的具体使用说明...

添加新 LLM Provider

参见 docs/README.md 的 "扩展" 章节。

配置

在项目根目录创建 agent_config.json 进行自定义配置:

{
  "model": "claude-sonnet-4-6",
  "llm_provider": "anthropic",
  "max_tokens": 8096,
  "max_turns": 20,
  "verbose": true,
  "sandbox": false,
  "auto_approve": false,
  "memory_enabled": true,
  "project_scan_enabled": true,
  "tool_cache_enabled": true
}

测试

pip install pytest
python -m pytest tests/ -q

文档

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request!


最后更新:2026-06-14 — Web Search 功能(DuckDuckGo/Brave/Serper/Tavily),文档更新

Ver o original no GitHub

Bom para

Relacionados