gbrain：开源 AI Agent 与工作流自动化平台

读完可以判断：

• 用一句话讲清 gbrain 和 LangChain / CrewAI 各自在什么位置，什么场景选哪个
• 画出 gbrain 三条主线（模型网关、Agent 编排、RAG（检索增强生成））的数据流，解释它们怎么组合、怎么独立使用
• 照着代码示例跑通一个多 Agent 协作任务，从安装到 crew.kickoff() 不超过 10 分钟
• 判断你的团队现在该不该上 gbrain，以及从哪里切入

学习目标

读完后你应当能够：

1. 说清 gbrain 的核心定位：模型网关、Agent 编排、RAG 三条主线如何协同工作
2. 在 Python 环境中完成 gbrain 的安装、第一个 Agent 的创建和多 Agent 协作任务的运行
3. 解释 gbrain 与 LangChain、CrewAI 的核心差异，以及各自的适用边界
4. 描述 gbrain 的四种 Agent 编排模式（层级协作、共享记忆、规则路由、并行执行）各自适合什么场景
5. 规划 gbrain 在团队中的采用路径：从试用到生产化的四个阶段

目录

• 学习目标
• 一、gbrain 解决什么问题
• 二、三条主线：系统总览
• 三、主线一：模型网关
• 四、主线二：多 Agent 编排
• 五、主线三：内置 RAG
• 六、工具系统
• 七、企业级功能
• 八、快速上手
• 九、配置与部署
• 十、实践建议
• 十一、常见问题
• 十二、采用建议
• FAQ
• 自测题
• 进阶路径

一、gbrain 解决什么问题

市面上的 AI Agent 框架不少，但多数在"调模型"和"编排 Agent"之间只能做好一头。LangChain 管抽象管得细，但工程落地需要自己补的东西很多；CrewAI 侧重多 Agent 角色分配，但模型切换和知识检索需要额外集成。

gbrain 走的是另一条路：把模型网关、Agent 编排和 RAG 做成三个内置模块，用同一套配置串起来。 你不用在三个库之间来回接管线——40+ 模型、60+ 工具、四种向量数据库，都在同一个进程里跑。

它的代价也很明确：抽象层比 LangChain 薄，定制深度不如自己搭 pipeline。但如果你需要的是"开工就能跑起来的多 Agent 系统"，这套代价是可接受的。

二、三条主线：系统总览

gbrain 内部有三条独立且可组合的主线，每条都有自己的生命周期和边界：

┌──────────────────────────────────────────────────┐
│                    gbrain                        │
│                                                  │
│  ┌──────────┐   ┌──────────────┐   ┌─────────┐  │
│  │ 模型网关  │   │ Agent 编排   │   │  RAG    │  │
│  │          │   │              │   │         │  │
│  │ 40+ 模型 │──▶│ Crew 调度    │──▶│ 向量检索 │  │
│  │ 统一 API │   │ 层级/并行    │   │ 4 种 DB │  │
│  └──────────┘   └──────────────┘   └─────────┘  │
│        │               │                │        │
│        ▼               ▼                ▼        │
│  ┌──────────────────────────────────────────┐    │
│  │          工具系统 (60+ 预置)              │    │
│  └──────────────────────────────────────────┘    │
│  ┌──────────────────────────────────────────┐    │
│  │        企业层 (SSO / RBAC / 审计)         │    │
│  └──────────────────────────────────────────┘    │
└──────────────────────────────────────────────────┘

三条主线各自独立——你可以只用模型网关来统一 LLM 调用，不碰 Agent 编排；也可以只用 RAG 做知识库检索，不进多 Agent 场景。但三者组合时，共享同一套工具系统和配置层。

三、主线一：模型网关

3.1 它做了什么

gbrain 的模型网关对外暴露一个 LLM 类，内部封装了各家 Provider 的认证、调用格式和返回结构。切换模型就是改一行字符串：

from gbrain import LLM

llm = LLM("gpt-4o")           # OpenAI
llm = LLM("claude-3-5-sonnet") # Anthropic
llm = LLM("llama-3.1-70b")    # Groq
llm = LLM("qwen-2.5-72b")     # Ollama 本地

response = llm.chat("用 Python 写一个快速排序")

3.2 为什么需要这一层

多模型切换的痛点不在"调用"，而在"切换成本"。每换一个 Provider，调用格式、token 计数、错误码都不一样。模型网关把这部分差异吃掉了，你的 Agent 逻辑不需要感知底层是 OpenAI 还是本地 Ollama。

这一点对生产环境尤其重要：你可以先用 Groq 的免费 API 做原型验证，确认逻辑通了再切到 OpenAI 正式跑——一行配置的事。

3.3 支持的 Provider

四、主线二：多 Agent 编排

4.1 它做了什么

Agent 编排引擎负责两件事：把任务拆给多个 Agent，以及管理 Agent 之间的上下文传递。核心概念是 Agent（角色定义 + 工具绑定）和 Crew（调度器）：

from gbrain import Agent, Crew

researcher = Agent(
    name="研究助手",
    role="信息收集与总结",
    backstory="你是一个专业的研究员，擅长从多个来源收集信息",
    tools=["tavily_search", "browser"]
)

writer = Agent(
    name="写作助手",
    role="内容创作",
    backstory="你是一个资深编辑，擅长撰写清晰、有说服力的文章",
    tools=["document_writer"]
)

crew = Crew(agents=[researcher, writer])
result = crew.kickoff("写一篇关于 AI Agent 的博客文章")

4.2 编排的四种模式

4.3 为什么需要编排层，而不是一个 Agent 干到底

单个 Agent 的有效上下文窗口和推理深度是有限的。把"收集信息"“写作"“校对"拆给三个 Agent，每个只背自己的角色和工具，比一个大 Agent 同时做三件事更可靠。这背后是注意力稀释问题——Agent 能用的工具越多、背的 prompt 越长，其输出质量下降越明显。

4.4 一个完整的任务流案例

拿「写一篇 AI Agent 博客文章」走一遍完整流程：

1. 用户发起 → crew.kickoff("写一篇关于 AI Agent 的博客文章")
2. Crew 拆解 → 识别出需要"信息收集→写作→校对"三个子任务
3. 研究助手执行 → 调用 tavily_search 搜索"AI Agent 2026 最新动态”，用 browser 抓取 3 篇参考文章，返回结构化摘要
4. 写作助手执行 → 拿到研究助手的摘要存入共享记忆，按"背景→技术原理→实践案例"的结构生成初稿
5. 自检 → Crew 检查输出是否完整，若缺章节则补写
6. 返回结果 → 组合后的完整文章返回给用户

这个流程里，模型网关负责每一步的 LLM 调用（模型可以在不同步骤用不同的 Provider），编排引擎负责调度和上下文传递，RAG 可选介入——如果写作助手需要参考公司内部文档，RAG 在步骤 4 之前注入检索结果。

五、主线三：内置 RAG

5.1 它做了什么

RAG 模块封装了文档入库、向量化和语义检索的完整链路：

from gbrain import RAG

rag = RAG(
    vectorstore="chroma",          # chroma / faiss / qdrant / milvus
    embedding_model="text-embedding-3-small"
)

rag.add_documents(
    documents=["技术文档...", "产品手册..."],
    metadata=[{"source": "docs"}, {"source": "manual"}]
)

results = rag.search("如何配置 SSO？", top_k=5)

5.2 为什么内置 RAG，而不是外挂

外挂 RAG 的典型问题是：Agent 需要上下文增强时，你得在 Agent 逻辑里手动调检索、塞 prompt、去重。内置 RAG 把这个过程自动化了——Agent 可以在执行步骤中声明"我需要检索知识库”，系统自动注入相关片段。

5.3 向量数据库选择

六、工具系统

gbrain 预置了 60+ 工具，覆盖搜索、数据抓取、云服务、数据库、支付和通信六类。Agent 通过 tools 参数绑定工具，运行时由编排引擎决定何时调用哪个工具。

from gbrain import Agent

agent = Agent(
    name="运营助手",
    tools=[
        "tavily_search",     # 搜索
        "firecrawl_scrape",  # 网页抓取
        "github_repo",       # GitHub 操作
        "slack_message",     # Slack 通知
        "notion_create",     # Notion 文档
        "linear_issue",      # Linear 工单
        "airtable_record",   # Airtable 记录
    ]
)

自定义工具也很直接——用 @tool 装饰器包装任意 Python 函数即可：

from gbrain import tool

@tool(name="天气查询", description="查询指定城市的天气")
def get_weather(city: str) -> str:
    import requests
    response = requests.get(f"https://api.weather.com?q={city}")
    return response.json()

七、企业级功能

7.1 安全与权限

from gbrain import Enterprise

enterprise = Enterprise(
    sso_enabled=True,
    sso_provider="okta",       # okta / azure / google

    rbac_enabled=True,
    roles={
        "admin": ["*"],
        "user": ["agent:run", "tool:use"],
        "viewer": ["agent:read"]
    },

    audit_enabled=True,
    ssl_enabled=True,
)

7.2 可观测性

from gbrain import observe

observe.langsmith(
    api_key="your-api-key",
    project="production-agents"
)

observe.otel(
    endpoint="http://otel-collector:4317",
    service_name="gbrain-agent"
)

八、快速上手

8.1 安装

pip install gbrain            # 基础安装
uv add gbrain                 # 或用 uv（更快）

pip install gbrain[enterprise]  # 企业功能
pip install gbrain[all]         # 全部功能

8.2 第一个 Agent

from gbrain import Agent

assistant = Agent(
    name="助手",
    role="通用助手",
    backstory="你是一个有用的人工智能助手"
)

result = assistant.run("用 Python 写一个 Hello World")
print(result)

8.3 第一个工作流

from gbrain import Workflow

workflow = Workflow(
    name="博客写作流程",
    steps=[
        {"agent": "researcher", "task": "收集 AI Agent 最新动态"},
        {"agent": "writer", "task": "撰写博客文章"},
        {"agent": "editor", "task": "校对和发布"}
    ]
)

result = workflow.execute()

九、配置与部署

# gbrain.yaml
llm:
  default_provider: openai
  models:
    gpt-4o:
      provider: openai
      api_key: ${OPENAI_API_KEY}
    claude-3-5-sonnet:
      provider: anthropic
      api_key: ${ANTHROPIC_API_KEY}

vectorstore:
  type: chroma
  persist_directory: ./data/chroma

enterprise:
  sso_enabled: true
  rbac_enabled: true

observability:
  langsmith_enabled: true
  otel_enabled: true

# .env
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
LANGCHAIN_API_KEY=ls-...

十、实践建议

10.1 设计 Agent 的经验

角色定义要窄。 一个 Agent 的 role 和 backstory 越宽泛，输出越容易偏移。宁可多用几个专注的 Agent，也不要让一个 Agent 背太多身份。

控制工具数量。 给 Agent 10 个工具，它选错的概率远高于给 3 个。按场景拆 Agent，每个只带该场景需要的工具。

善用共享记忆。 多步骤任务中，后面的 Agent 能不能拿到前序结果，直接影响最终质量。别让每个 Agent 都从零开始推理。

from gbrain import Agent, Memory

agent = Agent(
    name="客服助手",
    role="客户支持",
    backstory="你是一个耐心的客服，擅长解决客户问题",
    tools=["search_kb", "create_ticket", "send_email"],
    memory=Memory(
        max_turns=10,
        summary=True
    )
)

10.2 工作流优化

并行执行适合独立任务（比如同时从三个数据源拉数据），条件路由适合分类→分发场景：

from gbrain import Crew, Workflow

crew = Crew(
    agents=[researcher1, researcher2, researcher3],
    execution_mode="parallel"
)

workflow = Workflow(
    steps=[
        {"agent": "classifier", "task": "分类输入"},
        {"agent": "technical", "condition": "type=='技术'"},
        {"agent": "business", "condition": "type=='商务'"}
    ]
)

十一、常见问题

Q: gbrain 和 LangChain / CrewAI 的边界在哪？

A: 假设你刚接手一个新项目，要在一个月内上线一个带 RAG 的多 Agent 客服系统。LangChain 给你更细粒度的抽象层（Chain、Tool、Memory 各自独立），适合需要深度定制的团队，但你需要自己把这三块拼起来。CrewAI 专注多 Agent 角色扮演，但模型切换和知识检索需要额外集成。gbrain 把这三块做成内置模块——省了集成时间，但抽象层比 LangChain 薄。如果你的团队已经在用 LangChain 生态且有一套成熟的 pipeline，迁移成本可能高于收益。

Q: 支持本地模型吗？

A: 支持，通过 Ollama 或 LM Studio 集成。比如你在处理医疗或金融数据，合规要求数据不能出内网——这种场景下，本地模型是唯一选项。不过本地模型在复杂推理任务上的表现通常弱于云端大模型，建议简单任务（摘要、分类）用本地模型，复杂推理任务（多步逻辑、代码生成）走云端。

Q: 数据安全怎么保证？

A: 假设你的团队需要通过 SOC2 审计或客户要求数据驻留声明。企业版提供 SSO、RBAC、审计日志和 SSL 加密。数据默认存储在本地 SQLite 数据库，不经过 gbrain 的服务器。但要注意：如果你用云端 Provider（如 OpenAI），prompt 和响应仍然会经过第三方 API——敏感数据场景记得切到 Ollama 本地模型。

Q: 能接入自己的模型吗？

A: 可以。比如公司自研了一个针对垂直领域的模型，或者微调过的 Llama——实现 gbrain 的 LLM 接口规范即可接入，不需要改 Agent 编排或 RAG 层的代码。接入后，Agent 和 RAG 可以无缝使用你的私有模型，切换方式跟切换 OpenAI/Anthropic 一样，改一行配置。

Q: Agent 数量多了以后怎么管理？

A: 从 2 个 Agent 扩展到 8 个以后，常见的坑是上下文混乱和工具调用冲突。建议三条：角色定义保持窄（一个 Agent 只做一件事），工具数量控制在 3-5 个，善用共享记忆而不是让每个 Agent 重新推理。如果发现输出质量下降，先检查是不是某个 Agent 背了太多工具或角色，而不是急着加 Agent。

十二、采用建议

先上的团队：

• 需要快速搭建多 Agent 协作系统的中小团队，不想在 LangChain/CrewAI 之间做集成选型。
• 有多个 LLM Provider 切换需求（比如开发用 Groq、生产用 OpenAI）的团队。
• 需要把 RAG 和 Agent 无缝衔接，而不是分别维护两套系统的场景。

可以等等的团队：

• 已经在 LangChain 生态有成熟 pipeline，迁移成本大于收益。
• 需要深度定制 Agent 推理逻辑（比如自定义 ReAct 循环、复杂工具调用链），gbrain 的抽象层还不够厚。
• 对本地模型推理性能有极致要求，需要自己控制推理引擎的每个环节。

从哪开始：

1. 先用 pip install gbrain 跑通第一个 Agent（5 分钟）
2. 接上你的数据源，跑通 RAG 检索链路
3. 拆出 2-3 个 Agent，用 Crew 编排一个最小工作流
4. 确认逻辑可行后，再加企业功能（SSO、审计）和可观测性

FAQ

Q: gbrain 的 Agent 和 LangChain 的 Chain 有什么区别？

A: LangChain 的 Chain 是固定的执行链路，每一步做什么在代码里写死；gbrain 的 Agent 是有角色、有工具、能自主决策的执行单元。Chain 适合确定性的流水线，Agent 适合需要判断、需要工具调用的任务。

Q: 多 Agent 协作时，上下文怎么传递？

A: gbrain 通过共享记忆机制传递上下文。前面的 Agent 把结果写入共享记忆，后面的 Agent 从共享记忆读取。你也可以显式通过 Crew 的输出传递。

Q: 本地模型的效果会不会很差？

A: 取决于任务。摘要、分类、简单提取这类任务，本地模型（如 Llama 3.1 70B）效果已经不错；复杂推理、代码生成、多步逻辑，还是云端大模型更稳。建议简单任务用本地，复杂任务走云端。

Q: gbrain 支持异步执行吗？

A: 支持。从 v0.3.0 开始，gbrain 的 Agent 和 Crew 都支持 async/await 异步执行，适合高并发场景。

Q: 如果 Agent 执行失败了，怎么调试？

A: gbrain 提供可观测性集成（LangSmith、OpenTelemetry）。你可以在 LangSmith 里看到每个 Agent 的思考过程、工具调用、输入输出；也可以开启详细日志，看每一步的执行情况。

自测题

1. gbrain 的三条主线分别是什么？如果你只需要统一 LLM 调用入口，不碰多 Agent 编排，你需要用到哪条主线？
2. 一个 Agent 的 role 和 backstory 写得太宽泛会有什么后果？如果你要给 Agent 配 10 个工具，更大的风险是什么？
3. 假设你要做一个「搜新闻 → 写摘要 → 发 Slack」的自动化流程，在 gbrain 里应该用 Crew 还是 Workflow？为什么？
4. 什么情况下你该选 gbrain 而不是 LangChain？什么情况下该反过来？
5. gbrain 的四种编排模式（层级协作、共享记忆、规则路由、并行执行）各自适合什么场景？举一个具体例子。

进阶路径

阶段一：跑起来（1-2 天）

• 安装 gbrain（pip install gbrain）
• 跑通第一个 Agent（5 分钟快速上手）
• 接上你的数据源，跑通 RAG 检索链路
• 在 AI Studio 或本地环境完成第一次多 Agent 协作

阶段二：接到自己的项目（3-7 天）

• 把 gbrain 集成到现有 Python 项目
• 设计 Agent 角色分工（参考实践建议）
• 配置工具绑定（避免工具过多导致选择错误）
• 实现第一个多步骤工作流

阶段三：生产优化（1-2 周）

• 配置企业功能（SSO、RBAC、审计）
• 接入可观测性（LangSmith / OpenTelemetry）
• 优化 Agent 编排（选择合适的编排模式）
• 配置错误处理和重试机制

阶段四：团队推广（持续）

• 制定团队内部的 Agent 设计规范
• 建立共享的工具库和 Agent 模板
• 监控 Agent 执行成本和性能
• 持续优化 Agent 角色定义和工具配置

推荐资源：

• gbrain GitHub
• gbrain 文档
• LangChain 对比分析
• 多 Agent 设计模式

相关资源

🦞 本文由钳岳星君撰写，基于 gbrain v0.4.3