Skip to content

README.zh_CN.md

Latest commit

 

History

History
611 lines (445 loc) · 27 KB

README.zh_CN.md

File metadata and controls

611 lines (445 loc) · 27 KB
Raw

English | 中文

tRPC-Agent-Python

PyPI Version Python Versions LICENSE Releases Coverage Documentation

深度融合 Python AI 生态的生产级 Agent 开发框架。
tRPC-Agent-Python 提供从 Agent 构建、编排、工具接入、会话记忆，到服务化部署与可观测的完整能力，帮助你快速落地可运行、可扩展、可维护的智能体应用。

为什么选择 tRPC-Agent-Python？

  • 多范式 Agent 编排：预设编排支持 ChainAgent / ParallelAgent / CycleAgent / TransferAgent，同时支持 GraphAgent 图编排
  • 图编排能力（GraphAgent）：通过 DSL 统一编排 Agent / Tool / MCP / Knowledge / CodeExecutor
  • 高效接入 Python AI 生态扩展：Agent 生态扩展（claude-agent-sdk / LangGraph 等）/ 工具生态扩展（mcp 等）/ 知识库生态扩展（LangChain 等）/ 模型生态扩展（LiteLLM 等）/ 记忆生态扩展（Mem0、Mempalace等）
  • Agent 生态扩展：支持 LangGraphAgent / ClaudeAgent / TeamAgent（Agno-Like）
  • Tool 生态扩展：FunctionTool / 文件工具 / MCPToolset / LangChain Tool / Agent-as-Tool
  • 完善的记忆能力（Session / Memory）：Session 负责单会话内的消息与状态管理，Memory 负责跨会话长期记忆与个性化信息沉淀。持久化支持 InMemory / Redis / SQL，Memory 还支持 Mem0、Mempalace
  • 生产级知识库能力：知识库能力基于 LangChain 组件构建，支持 RAG 场景
  • CodeExecutor 扩展能力：支持本地 / 容器执行器，用于支持 Agent 的代码执行与任务落地能力
  • Skills 扩展能力：支持 SKILL.md 技能体系，用于支持 Agent 的技能复用与动态工具化能力
  • 对接多种 LLM Provider：OpenAI-like / Anthropic / LiteLLM 路由
  • 服务化与可观测：支持通过 FastAPI 提供 HTTP / A2A / AG-UI 的服务，内置 OpenTelemetry 追踪
  • trpc-claw（OpenClaw-like Agent）：基于 nanobot 构建，tRPC-Agent 提供 trpc-claw 能力，方便快速开发一个支持 Telegram / 企业微信等通道的 OpenClaw-like 个人 AI Agent

使用场景

  • 智能客服与知识问答（RAG + 会话记忆）
  • 代码生成与工程自动化（ClaudeAgent）
  • 代码执行与自动化任务落地（CodeExecutor）
  • 使用 Agent Skills
  • 多角色协作任务（TeamAgent / Multi-Agent）
  • 跨协议 Agent 服务接入（A2A / AG-UI）
  • MCP 工具协议接入与工具生态扩展
  • 面向网关场景的统一接入与协议转换
  • 基于 GraphAgent 的组件化工作流编排
  • 复用已有 LangGraph 工作流并接入当前体系
  • 快速打造 OpenClaw-like 个人 AI Agent（trpc-claw）

目录

快速开始

前置条件

  • Python 3.10+（推荐 Python 3.12）
  • 可用的模型服务 API Key（OpenAI-like / Anthropic，或通过 LiteLLM 路由）

安装

pip install trpc-agent-py

按需安装扩展能力：

pip install "trpc-agent-py[a2a,ag-ui,knowledge,agent-claude,mem0,mempalace,langfuse]"

开发天气查询Agent

import asyncio
import os
import uuid

from trpc_agent_sdk.agents import LlmAgent
from trpc_agent_sdk.models import OpenAIModel
from trpc_agent_sdk.runners import Runner
from trpc_agent_sdk.sessions import InMemorySessionService
from trpc_agent_sdk.tools import FunctionTool
from trpc_agent_sdk.types import Content, Part


async def get_weather_report(city: str) -> dict:
    return {"city": city, "temperature": "25°C", "condition": "Sunny", "humidity": "60%"}


async def main():
    model = OpenAIModel(
        model_name=os.environ["TRPC_AGENT_MODEL_NAME"],
        api_key=os.environ["TRPC_AGENT_API_KEY"],
        base_url=os.environ.get("TRPC_AGENT_BASE_URL", ""),
    )

    agent = LlmAgent(
        name="assistant",
        description="A helpful assistant",
        model=model,
        instruction="You are a helpful assistant.",
        tools=[FunctionTool(get_weather_report)],
    )

    session_service = InMemorySessionService()
    runner = Runner(app_name="demo_app", agent=agent, session_service=session_service)

    user_id = "demo_user"
    session_id = str(uuid.uuid4())
    user_content = Content(parts=[Part.from_text(text="What's the weather in Beijing?")])

    async for event in runner.run_async(user_id=user_id, session_id=session_id, new_message=user_content):
        if not event.content or not event.content.parts:
            continue
        for part in event.content.parts:
            if part.text and event.partial:
                print(part.text, end="", flush=True)
            elif part.function_call:
                print(f"\n🔧 [{part.function_call.name}({part.function_call.args})]", flush=True)
            elif part.function_response:
                print(f"📊 [{part.function_response.response}]", flush=True)

    print()

if __name__ == "__main__":
    asyncio.run(main())

运行Agent

export TRPC_AGENT_API_KEY=xxx
export TRPC_AGENT_BASE_URL=xxxx
export TRPC_AGENT_MODEL_NAME=xxxx
python quickstart.py

trpc-claw 用法

tRPC-Agent 基于 nanobot 提供了 trpc-claw 能力（trpc_agent_cmd openclaw），方便你快速打造一个 OpenClaw-like 的个人 AI Agent：配置好后一条命令启动，可 7×24 小时在线，通过 Telegram、企业微信等常用 IM 与 Agent 交互，或直接在本地 CLI / UI 使用。

详细配置与高级功能参见：openclaw.md

快速上手

1. 生成配置文件

mkdir -p ~/.trpc_claw
trpc_agent_cmd openclaw conf_temp > ~/.trpc_claw/config.yaml

2. 配置环境变量

export TRPC_AGENT_API_KEY=your_api_key
export TRPC_AGENT_BASE_URL=your_base_url
export TRPC_AGENT_MODEL_NAME=your_model

3. 本地运行

# 强制本地 CLI
trpc_agent_cmd openclaw chat -c ~/.trpc_claw/config.yaml

# 本地 UI
trpc_agent_cmd openclaw ui -c ~/.trpc_claw/config.yaml

4. 接入企业微信 / Telegram

在 config.yaml 中启用对应通道，然后 run 启动：

channels:
  wecom:
    enabled: true
    bot_id: ${WECOM_BOT_ID}
    secret: ${WECOM_BOT_SECRET}
  # 或 Telegram：
  # telegram:
  #   enabled: true
  #   token: ${TELEGRAM_BOT_TOKEN}
trpc_agent_cmd openclaw run -c ~/.trpc_claw/config.yaml

run 模式下若无可用通道会自动回退到本地 CLI，方便调试。

更多文档

示例

examples 目录里的示例都可以直接运行。下面按能力分组整理了“建议先看”的示例，并给了简短阅读提示，方便你按场景快速定位。

1. 入门与基础 Agent

建议先看：

相关文档：llm_agent.md / model.md

这组示例可以帮你：

  • 快速跑通从用户输入到工具调用再到模型输出的完整链路
  • 理解流式输出中 function_call / function_response 事件的处理方式
  • 掌握自定义 Prompt 和结构化输出的基础写法

可以先看这段代码（Runner + 流式事件）：

runner = Runner(app_name=app_name, agent=root_agent, session_service=session_service)
async for event in runner.run_async(user_id=user_id, session_id=current_session_id, new_message=user_content):
    if event.partial and event.content:
        ...

2. 多 Agent 预设编排

建议先看：

相关文档：multi_agents.md

这组示例可以帮你：

  • 看懂 Chain / Parallel / Cycle / Transfer 的职责差异
  • 按任务形态选择串行、并行、循环或交接的编排方式
  • 学会在已有结果基础上续跑与组合子流程

可以先看这段代码（ChainAgent）：

pipeline = ChainAgent(
    name="document_processor",
    sub_agents=[extractor_agent, translator_agent],
)

3. Team 协作

建议先看：

相关文档：team.md / human_in_the_loop.md / cancel.md

这组示例可以帮你：

  • 理解 Team 的 Leader / Member 协作模式
  • 学会在 Team 中接入 Skills、子 Team、外部 Agent
  • 覆盖消息过滤、人机协同、取消控制等常见工程需求

可以先看这段代码（TeamAgent）：

content_team = TeamAgent(
    name="content_team",
    model=model,
    members=[researcher, writer],
    instruction=LEADER_INSTRUCTION,
    share_member_interactions=True,
)

4. 图编排能力（GraphAgent / DSL）

建议先看：

相关文档：graph.md / dsl.md

这组示例可以帮你：

  • 适合需要显式流程控制的任务（分支、合并、中断、续跑）
  • 支持在同一图中混合 Agent / Tool / MCP / CodeExecutor / Knowledge
  • 用 DSL 更快搭建可读、可维护的工作流

可以先看这段代码（条件路由）：

graph.add_conditional_edges(
    "decide",
    create_route_choice(set(path_map.keys())),
    path_map,
)

5. Agent 生态扩展（LangGraphAgent / ClaudeAgent）

建议先看：

相关文档：langgraph_agent.md / claude_agent.md / human_in_the_loop.md / cancel.md

这组示例可以帮你：

  • 用 LangGraphAgent 复用已有 LangGraph 实现并接入当前运行时
  • 用 ClaudeAgent 处理代码生成、工程自动化、流式工具调用
  • 覆盖人机协同与取消控制，便于落地真实业务流程

可以先看这段代码（ClaudeAgent）：

root_agent = ClaudeAgent(
    name="claude_weather_agent",
    model=_create_model(),
    instruction=INSTRUCTION,
    tools=[FunctionTool(get_weather)],
    enable_session=True,
)

6. Tool 与 MCP

建议先看：

相关文档：tool.md

这组示例可以帮你：

  • 从函数工具到协议工具（MCP）再到组合工具，接入路径完整
  • 覆盖流式工具调用与 Agent-as-Tool 等高级模式
  • 便于把现有工具实现复用到多 Agent 场景

可以先看这段代码（MCPToolset）：

class StdioMCPToolset(MCPToolset):
    def __init__(self):
        super().__init__()
        self._connection_params = StdioConnectionParams(
            server_params=McpStdioServerParameters(command="python3", args=["mcp_server.py"]),
            timeout=5,
        )

7. Skills

建议先看：

相关文档：skill.md

这组示例可以帮你：

  • 把可复用能力沉淀为 Skills，减少重复开发
  • 支持按场景动态装配工具能力
  • 便于沉淀可复用的业务技能模块

可以先看这段代码（SkillToolSet）：

workspace_runtime = create_local_workspace_runtime()
repository = create_default_skill_repository(skill_paths, workspace_runtime=workspace_runtime)
skill_tool_set = SkillToolSet(repository=repository, run_tool_kwargs=tool_kwargs)

8. CodeExecutor

建议先看：

相关文档：code_executor.md

这组示例可以帮你：

  • 按执行环境选择本地或容器执行器
  • 让 Agent 在可控边界内完成代码执行与任务落地
  • 与 Skills/Tool 组合形成“规划 + 执行”闭环

9. Session / Memory / Knowledge

建议先看：

相关文档：

这组示例可以帮你：

  • Session：管理单会话的消息、摘要与状态
  • Memory：管理跨会话长期记忆（含 Mem0, Mempalace）
  • Knowledge：覆盖文档加载、检索、RAG、提示模板等链路

10. 服务化与协议

建议先看：

相关文档：a2a.md / agui.md / cancel.md

这组示例可以帮你：

  • 演示 HTTP / A2A / AG-UI 三种服务暴露方式
  • 覆盖流式返回与取消机制，便于接入网关和前端
  • 可直接作为服务化落地的最小模板

11. 过滤器与执行控制

建议先看：

相关文档：filter.md / cancel.md

这组示例可以帮你：

  • 展示 Model / Tool / Agent 三层过滤策略
  • 覆盖分支过滤、时间线过滤、执行取消等控制能力
  • 适合治理、审计、风控等强约束场景

12. LlmAgent 进阶能力

建议先看：

相关文档：llm_agent.md / model.md / custom_agent.md

这组示例可以帮你：

  • 聚焦 LlmAgent 在上下文、提示词、模型路由上的可扩展点
  • 适合把通用 Agent 调整为贴近业务策略的 Agent
  • 便于沉淀可复用的行为模板

13. LlmAgent 工具调用与交互

建议先看：

相关文档：llm_agent.md / tool.md / human_in_the_loop.md

这组示例可以帮你：

  • 覆盖简单 / 复杂两类流式工具调用模式
  • 演示并行工具调度与人机协同确认节点
  • 可与过滤器、取消机制组合，形成更稳的执行链路

更多示例请查看 examples 目录下各子目录 README.md。

架构概览

tRPC-Agent-Python Architecture

框架采用事件驱动方式组织组件，各层可独立扩展：

  • Agent 层：LlmAgent / ChainAgent / ParallelAgent / CycleAgent / TransferAgent
  • Agent 生态扩展层：LangGraphAgent / ClaudeAgent / TeamAgent
  • 图能力层：GraphAgent / trpc_agent_sdk.dsl.graph（DSL 组件编排能力）
  • Runner 层：统一执行入口，负责 Session/Memory/Artifact 等服务协同
  • Tool 层：FunctionTool / 文件工具 / MCPToolset / Skill 工具
  • Model 层：OpenAIModel / AnthropicModel / LiteLLMModel
  • Memory 层：SessionService / MemoryService / SessionSummarizer / Mem0MemoryService / MempalaceMemoryService
  • Knowledge 层：基于 LangChain 的生产级知识库能力（RAG）
  • 执行与技能层：CodeExecutor（本地/容器）/ Skills
  • 服务层：FastAPI / A2A / AG-UI
  • 观测层：OpenTelemetry tracing/metrics，可对接 Langfuse 等平台
  • 生态适配层：claude-agent-sdk / mcp / LangChain / LiteLLM / Mem0 / MemoryService，通过模型/工具/记忆适配器接入主链路

关键包一览：

Package 主要职责
trpc_agent_sdk.agents Agent 抽象 / 多 Agent 编排 / 生态扩展（LangGraphAgent / ClaudeAgent / TeamAgent）
trpc_agent_sdk.runners 统一执行与事件输出
trpc_agent_sdk.models 模型适配层
trpc_agent_sdk.tools 工具体系与 MCP 支持
trpc_agent_sdk.sessions 会话管理与总结压缩
trpc_agent_sdk.memory 长期记忆服务
trpc_agent_sdk.dsl.graph DSL 图编排引擎
trpc_agent_sdk.teams Team 协作模式
trpc_agent_sdk.code_executors 代码执行与工作区运行时
trpc_agent_sdk.skills Skill 仓库 / Skill 工具
trpc_agent_sdk.server FastAPI / A2A / AG-UI 等服务能力

贡献

我们热爱贡献！加入我们不断壮大的开发者社区，共同构建 AI Agent 的未来。

贡献方式

  • 报告 bug 或通过 Issues 建议新功能
  • 改进文档 - 帮助他人更快学习
  • 提交 PR - bug 修复、新功能或示例
  • 分享您的用例 - 用您的 Agent 应用启发他人

快速贡献设置

# Fork 并克隆仓库
git clone https://github.com/YOUR_USERNAME/trpc-agent-python.git
cd trpc-agent-python

# 安装开发依赖并运行测试
pip install -e ".[dev]"
pytest

# 进行您的更改并提交 PR！

请阅读 CONTRIBUTING.md 了解详细指南和编码标准。
请遵循 CODE-OF-CONDUCT.md 共同维护友好、尊重、包容的社区。

致谢

企业验证

感谢腾讯理财通、腾讯广告等业务团队在真实业务场景中的持续验证与反馈，帮助我们不断打磨框架能力。

开源灵感

也感谢 ADK、Agno、CrewAI、AutoGen 等优秀开源框架带来的启发，让我们能够站在巨人的肩膀上持续前进。

如果这个项目对你有帮助，欢迎在 GitHub 上点个 Star，这是对我们最直接的鼓励，也能帮助更多开发者发现这个项目。