PraAgent

基于智能代理架构二次开发的 Agent 框架，内置子代理生命周期检测、Token 预算监控、类 mem0 长期向量记忆与插件系统。

安装

一条命令安装（自动创建虚拟环境并安装，装好后可用 pra / praagent 命令）：

python install.py

# 可选：附带语义向量依赖 / 开发依赖 / 用户级安装
python install.py --embeddings
python install.py --dev --editable
python install.py --user

Windows PowerShell：

# 本地
.\install.ps1

# 远程一条命令
irm https://raw.githubusercontent.com/lemonorangeapple/PraAgent/master/install.ps1 | iex

Linux / macOS：

# 本地
./install.sh

# 远程一条命令
curl -fsSL https://raw.githubusercontent.com/lemonorangeapple/PraAgent/master/install.sh | bash

已配置好 pip 环境也可直接：

pip install .
pip install -e ".[embeddings,dev]"

启动

pra                # 直接打开交互式会话（等价于 pra chat；首次运行自动引导配置）
praagent chat
praagent config    # 主动运行配置向导
praagent chat --offline
praagent tui       # 全屏 TUI 界面

CLI 指令

• /config : 配置提供商、BaseURL、APIKey 与模型
• /provider / /models : 查看、切换提供商与模型
• /lang <zh-CN|en> : 切换界面语言
• /plugins install|uninstall|info : 管理插件/Skill/Agent
• /skills / /agents / /subagents : 查看已加载的 Skill、Agent、子代理
• /subagent <名称> <模型> : 为子代理指定独立模型；/subagent default <模型> 设置默认
• /perm <readonly|review|full> : 查看/切换权限级别
• /budget [tokens] : 查看/设置 Token 预算
• /goal <目标> : 自主目标模式，自动规划并执行；/goal resume|clear
• /memory / /remember <事实> : 查看/写入长期记忆
• /new / /sessions ... : 新建对话、切换/存档/删除会话
• /help / /exit : 帮助 / 退出

代码示例

自定义 Agent

import asyncio
from praagent.core.agent import BaseAgent, Message, AgentContext
from praagent.core.llm import LLMClient
from praagent.core.orchestrator import AgentOrchestrator
from praagent.config import PraConfig

class MyAgent(BaseAgent):
    def __init__(self, llm_client: LLMClient):
        super().__init__(
            name="my-agent",
            description="示例代理",
            system_prompt="你是一个助手。",
        )
        self.orchestrator = AgentOrchestrator(llm_client)

    async def run(self, user_input: str, context=None, **kwargs) -> str:
        messages = [Message(role="user", content=user_input)]
        return await self.orchestrator.execute_turn(self, messages, context)

config = PraConfig.load()
llm_client = LLMClient(config.llm)
agent = MyAgent(llm_client)
print(asyncio.run(agent.run("你好")))

自定义工具

工具即普通函数，参数须为 JSON 可序列化类型，返回字符串；orchestrator 会根据签名与 docstring 自动生成 JSON Schema：

def my_tool(query: str, limit: int = 5) -> str:
    """Search the codebase.

    Args:
        query: What to search for.
        limit: Max results.
    """
    import json
    return json.dumps({"results": []})

agent.register_tool(my_tool)

自定义插件

from praagent.plugins import PraPlugin

class MyPlugin(PraPlugin):
    name = "my-plugin"
    version = "0.1.0"

    def on_init(self, agent=None) -> None:
        pass

    def get_tools(self) -> dict:
        return {"my_tool": my_tool}

    def get_locales(self) -> dict:
        return {"zh-CN": {"strings": {"hello": "你好"}, "name": "简体中文"}}

    def get_providers(self) -> dict:
        return {}

    def get_cli_commands(self) -> dict:
        return {}

将插件文件放入 ./plugins/ 或 ~/.config/PraAgent/plugins/ 即可被自动加载；也可通过 PluginManager.register_plugin(MyPlugin(), agent) 编程注册。扩展插件类型见 praagent/plugins/plugin_types.py：MCPPlugin、LSPPlugin、UIPlugin、RefactorPlugin。

Markdown Agent

mode: primary 的文件注册为主代理（Tab / /agent <名称> 切换）；mode: subagent（或缺省）注册为可被 spawn_subagent 调度的子代理：

---
name: my-agent
description: 描述何时使用该代理
mode: primary
temperature: 0.1
model: deepseek-chat
---

系统提示词正文……

会话管理

from praagent.core.sessions import SessionManager

sessions = SessionManager("<workdir>/.pra/sessions")
session = sessions.new_session()
sessions.append_messages(session, messages)
for s in sessions.list_sessions():
    print(s)

接口

核心类

类	模块	说明
PraConfig	praagent.config	全局配置，PraConfig.load(config_path=None) 按序查找 ./praagent.json、~/.config/PraAgent/config.json 等
LLMConfig / ProviderProfile	praagent.config	模型配置与配置档，apply_profile(name) 切换
LLMClient	praagent.core.llm	LLM 客户端，chat_completion(messages, tools=None, ...)；register_provider_class(type, cls) 注册提供商
BaseAgent	praagent.core.agent	代理基类，register_tool(func)、run(user_input, context=None)
Message / AgentContext	praagent.core.agent	消息与上下文模型
AgentOrchestrator	praagent.core.orchestrator	多轮推理与工具调用循环，execute_turn(agent, messages, context=None, max_turns=5)
SubagentManager	praagent.core.subagent	子代理注册、调度与生命周期检测
SessionManager	praagent.core.sessions	会话持久化，new_session() / latest() / resolve(pattern)
MemoryRetriever / ShortTermMemory / LongTermMemory	praagent.memory	短期/长期记忆与语义检索
PermissionManager	praagent.core.permissions	三级权限（readonly / review / full）
TokenCounter / AlertManager	praagent.tracking	Token 计量与预算告警
MasterPraAgent	praagent.cli.main	CLI/TUI 使用的主代理

插件接口

PraPlugin（praagent.plugins.plugin_manager）可覆写：

def on_init(self, agent=None) -> None
def get_tools(self) -> Dict[str, Callable]        # {"tool_name": func}
def get_subagents(self) -> List[BaseAgent]
def get_locales(self) -> Dict[str, Any]           # {locale: {"strings": dict, "name": str}}
def get_providers(self) -> Dict[str, Any]         # {provider_type: ProviderClass}
def get_cli_commands(self) -> Dict[str, Callable]

加载：PluginManager(plugin_dirs) 自动扫描 ./plugins 与 ~/.config/PraAgent/plugins；PluginRuntime 负责生命周期（load_builtin / discover_external / discover_local / apply_all）。

提供商协议

provider_type 支持：openai_completions、openai_responses、anthropic_messages、gemini；自定义提供商继承 praagent.core.providers.base.BaseLLMProvider。

配置文件示例

{
  "llm": {
    "active_profile": "my-provider",
    "profiles": {
      "my-provider": {
        "name": "my-provider",
        "provider_type": "openai_completions",
        "model": "gpt-4o",
        "api_key": "sk-...",
        "base_url": "https://api.example.com/v1"
      }
    }
  }
}

环境变量覆盖：PRAAGENT_API_KEY、PRAAGENT_BASE_URL、PRAAGENT_MODEL、PRAAGENT_PROVIDER、PRAAGENT_LOCALE。

存储路径

• 项目级：<项目>/.pra/（sessions/、todos.json、skill/、agent/）
• 用户级：~/.config/PraAgent/（memory.db、config.json、PRA.md、plugins/、skills/、agents/）
• 项目级提示词：项目根目录 PRA.md