IntentKit Tools 开发指南:从原生工具到 MCP 服务器集成的完整实战手册

原创2026-09-16 19:01:171,824 阅读
文章标签:人工智能AI Agent多智能体工具调用MCP Clients后端云原生

IntentKit Tools 开发指南:从原生工具到 MCP 服务器集成的完整实战手册

导读

本文是 IntentKit 开源仓库中 agent_docs/tool_development.md 的深度扩展版,面向希望在 IntentKit 中为 AI Agent 添加新能力的开发者。你将掌握两种工具开发路径:一是原生(Native)工具——在 Python 中直接实现、拥有细粒度开关与版本化 schema 的能力扩展;二是 MCP 工具类别集成——以极少量代码把任意远程 MCP 服务器包装成工具类别,由框架自动完成工具发现、schema 生成与运行时调用。文中所有配置、接口与流程均以当前仓库源码为依据,并给出可直接对照的实现路径。

工具体系总览

IntentKit 是一个开源的、可自托管的云 Agent 集群,为 Agent 团队提供协作能力。工具的载体是 intentkit/tools/ 目录:每个子目录就是一个工具类别(Tool Category),一个类别下可以包含多个工具,类别既可以按功能主题划分,也可以按品牌(如 Twitter、CoinGecko)划分。

从 agent_docs/tool_development.md 的定义看,创建工具类别有两种方式:

  1. 原生工具(Native tools):直接在 Python 中实现工具,拥有完整控制力;
  2. MCP 包装工具(MCP-wrapped tools):把远程 MCP 服务器包装为工具类别,代码量极小。

无论哪种方式,都需要遵守一条硬性依赖规则:工具只能依赖 models、abstracts、utils、clients 四个模块中的内容,以避免循环依赖(详见 依赖规则)。

原生工具类别的标准结构

一个原生工具类别文件夹需要包含以下要素,范式可参考现有实现 intentkit/tools/twitter/。

1. 基类(base.py)

基类继承自 IntentKitTool(定义于 intentkit/tools/base.py),把本类别共用的函数写在基类里。最典型的例子就是 get_api_key:以 intentkit/tools/twitter/base.py 为例,它从 context.agent.tool_config(self.category) 中读取配置,并校验 consumer_key、consumer_secret、access_token、access_token_secret 四个必需字段,缺失时抛出 ToolException。

IntentKitTool 还预置了一批开箱即用的能力(全部定义于 intentkit/tools/base.py):

  • 异常处理策略:handle_tool_error 与 handle_validation_error 被覆写为默认处理器(L73-L82),工具抛出的异常会以 tool error: ... 的形式返回给 Agent;
  • 限流能力:提供 user_rate_limit / global_rate_limit 及其按工具(_by_tool)与按类别(_by_category)四个变体(L97-L233),底层基于 Redis 的 INCR + EXPIRE 原子操作实现,超限时抛出 RateLimitExceeded;
  • 工具级持久化:get/save/delete_agent_tool_data 与 get/save_thread_tool_data(L247-L306),分别把数据持久化到 Agent 作用域(AgentToolData)与当前会话作用域(ChatToolData);
  • 上下文访问:get_context() 通过 LangGraph 运行时取出 AgentContext(L240-L245),内含 agent_id、chat_id、user_id 等信息。

此外,基类还定义了 price(默认 Decimal("1"))与 available() 钩子,价格注册表 build_tool_prices()(L324-L362)会在启动时递归扫描所有工具子类,把 {name: price} 收集为全局价格表。

2. 单个工具文件

每个工具拥有独立文件,文件名与工具名保持一致。以 intentkit/tools/twitter/post_tweet.py 为范式,关键点如下:

  • 类继承:工具类继承本类别的 BaseClass(如 TwitterPostTweet(TwitterBaseTool));
  • Name 属性:name 必须带类别前缀,如 twitter_post_tweet,保证全系统唯一;
  • Description 属性:description 是给 LLM 看的工具说明,直接影响模型选工具;
  • Args Schema:args_schema 是 Pydantic 参数模型,例如 TwitterPostTweetInput 定义了 text(必填,最大 25000 字符)与 image(可选,图片 URL)两个字段;
  • 主逻辑 _arun 方法:这是工具的核心实现。其特殊之处在于:
    • 可通过 IntentKitTool 提供的 context_from_config / get_context() 从 LangChain runnable config 中获取上下文;
    • 遇到异常直接向上抛出即可,Agent 有专门的模块兜底处理工具异常,无需自行捕获(详见下文"异常处理");
    • 若返回值不是字符串,建议在 description 中注明返回格式。

post_tweet.py 还展示了几个工程细节:使用 price: Decimal = Decimal("60") 覆盖默认价格;对图片 URL 校验是否来自系统 S3 CDN(config.aws_s3_cdn_url),非 CDN 图片会被忽略并附带警告信息返回;对非 OAuth 场景调用 check_rate_limit(max_requests=24, interval=1440) 做每日限额。

3. 初始化文件(__init__.py)

__init__.py 必须导出以下两个函数(契约由 intentkit/core/executor.py 强制校验):

async def get_tools(
    config: "Config",
    is_private: bool,
    **_,
) -> list[OpenAIBaseTool]
  • Config:继承自 ToolsetConfig(定义于 intentkit/tools/base.py),其 states 是一个 dict,key 为工具名、value 为工具状态。若类别需要 Agent 创建者配置其他字段,可自行扩展 Config。ToolsetConfig 的基础形态包含 enabled: bool 与 states: Any 两个键;
  • Caching:无状态工具可添加模块级 _cache 字典避免每次重复创建对象——intentkit/tools/twitter/init.py 就是"系统级缓存"的标准写法;
  • Available 检查:同时必须提供 available() 函数:
def available() -> bool:
    """Check if this tool category is available based on system config."""

该函数用于检查所需系统配置变量是否存在:若工具依赖平台托管的 API key(如 config.tavily_api_key),则返回该 key 是否存在;若工具只使用 Agent 所有者自带的 key,则直接返回 True。twitter 的实现 就是检查 twitter_oauth2_client_id 与 twitter_oauth2_client_secret 是否同时存在。

4. 视觉素材(图标)

类别文件夹内需要一张方形图标,schema.json 通过 x-icon 字段引用:

"x-icon": "/tools/{category_name}/{icon_filename}.{ext}"

支持 SVG、PNG、JPEG、WebP 四种格式,图标由 API 在 GET /tools/{category}/{icon_name}.{ext} 路径下对外提供。仓库中 twitter 类别使用的即 intentkit/tools/twitter/twitter.png。

5. 配置 Schema(schema.json)

为配置补充 schema.json 文件,格式遵循 JSON Schema draft-07。由于 Config 继承自 ToolsetConfig,可直接参考现有类别(如 intentkit/tools/twitter/schema.json)的写法。该文件的要点:

  • 顶层 enabled 布尔字段(默认 false);
  • states 对象,为每个工具声明 enum: ["disabled", "public", "private"] 三态,并配 x-enum-title 呈现"Disabled / Agent Owner + All Users / Agent Owner Only"的可读文案;
  • 敏感凭证字段(如 consumer_key)标记 "x-sensitive": true;
  • 支持 if/then 条件校验——twitter 的 schema 中,当 enabled: true 时强制要求四个凭证字段;
  • x-tags 取值必须来自固定列表:AI、Analytics、Audio、Communication、Crypto、DeFi、Developer Tools、Entertainment、Identity、Image、Infrastructure、Knowledge Base、NFT、Search、Social。

异常处理约定

工具内无需捕获异常:Agent 有专门的模块负责拦截工具异常并向 LLM 反馈。如需补充额外信息,可以捕获后重新抛出合适的异常类型。在 intentkit/tools/twitter/post_tweet.py 中可以观察到"捕获 → 包装上下文 → 重抛"的标准写法:异常信息被加上 <a href="https://link.gitcode.com/i/ad1b6a7ac9a1b0d1ee06e5a746472d49" target="_blank">agent:{context.agent_id}] 前缀后以原类型重抛。而 MCP 工具侧,McpToolTool._arun 会把 McpToolError 及任何未知异常统一包装为 ToolException 再抛出(见 [intentkit/tools/mcp/tool.py),最终交由 Agent 处理。

MCP 工具类别集成

MCP(Model Context Protocol) 是连接 LLM 与外部工具/数据源的标准协议。IntentKit 可以把任意远程 MCP 服务器包装成一个工具类别,框架自动完成工具发现、schema 生成与运行时调用——你只需注册服务器并运行同步脚本。

架构分层

intentkit/clients/mcp/          # MCP 协议客户端(clients 层)
├── registry.py                 # 服务器定义(McpServerDef)
└── client.py                   # HTTP 客户端(SSE / Streamable HTTP 传输)

intentkit/tools/mcp/            # MCP → IntentKit 工具适配器(tools 层)
├── wrapper.py                  # McpCategoryModule — 提供 get_tools/available/Config
└── tool.py                     # McpToolTool — 把单个 MCP 工具包装为 IntentKit 工具

intentkit/tools/mcp_{name}/     # 生成的按服务器划分的工具类别
├── __init__.py                 # 薄封装(由同步脚本自动生成)
├── schema.json                 # 工具状态 + 配置(由同步脚本自动生成)
└── {name}.{ext}                # 图标(手动添加)

scripts/sync_mcp_schemas.py     # 生成固定的 schema.json + __init__.py 样板

粗粒度、防漂移的配置设计

这是 MCP 集成最重要的设计决策:远程 MCP 服务器拥有自己的工具列表,且随时可能变更,因此 MCP 类别不会对单个工具做快照或开关。其 schema.json 只携带一个服务器级可见性开关(以服务器名为 key);开启后,Agent 获得服务器当前提供的全部工具——这些工具在运行时实时发现。由于 schema 从不枚举具体工具,服务器变更时 schema 也不会过期,无需重新同步。

代价是 UI 中无法对单个工具做开关。如果确实需要按工具控制(或重度依赖某供应商的数据),应改写成原生工具类别,其 schema 与代码一起纳入版本管理。这一点在 agent_docs/tool_development.md 的 MCP 章节中明确强调。

分步实操:接入一个新的 MCP 服务器

步骤 1:添加 API key 配置(如需要)

若 MCP 服务器需要 API key,在 intentkit/config/config.py 中追加配置项。仓库内已有的例子是第 237 行的:

self.coingecko_api_key: str | None = self.load("COINGECKO_API_KEY")

步骤 2:在注册表中登记服务器

向 intentkit/clients/mcp/registry.py 的 MCP_SERVERS 字典添加条目:

"mcp_myservice": McpServerDef(
    name="mcp_myservice",               # 必须与 dict key 及 tools/ 目录名一致
    display_name="My Service",           # UI 展示的人类可读名称
    description="What this service does",
    url="https://mcp.myservice.com/sse", # MCP 服务器端点
    transport="sse",                     # "sse" 或 "streamable_http"
    api_key_config_attr="my_service_api_key",  # config.py 中的属性名(或 None)
    api_key_header="Authorization",      # 携带 key 的 HTTP 头(或 None)
    api_key_prefix="Bearer",             # key 前缀(或 None 表示裸 key)
    tags=["Developer Tools"],            # 取自上方 x-tags 列表
),

McpServerDef 是 frozen=True 的 dataclass,字段语义见 intentkit/clients/mcp/registry.py。关键字段:

  • name — 必须是 mcp_{service},且与 MCP_SERVERS 的 dict key 一致;
  • transport — "sse" 走 Server-Sent Events,"streamable_http" 走 HTTP 流式传输;
  • api_key_config_attr — 服务器无需鉴权时设为 None;
  • api_key_prefix — 设为 None 则发送不带前缀的裸 key。

仓库内置的 CoinGecko 示例 展示了 api_key_prefix=None 且自定义 header(x-cg-demo-api-key)的用法;在 intentkit/clients/mcp/client.py 的 _build_headers 中可以看到前缀拼接逻辑:有前缀时发送 "{prefix} {api_key}",无前缀时发送裸 key。

步骤 3:运行同步脚本

source .venv/bin/activate
python scripts/sync_mcp_schemas.py

脚本逻辑见 scripts/sync_mcp_schemas.py:schema 形状只来自服务器定义,而非实时工具列表——脚本对服务器的探测仅为信息性可达性检查(探测失败不会中止同步,工具仍在运行时发现)。同步会生成:

  • intentkit/tools/mcp_myservice/__init__.py — 薄封装,委托给 McpCategoryModule;
  • intentkit/tools/mcp_myservice/schema.json — 包含 enabled、唯一的服务器级可见性开关 states,以及可选的 api_key 字段。

脚本还会保留现有 schema.json 中手工添加的 x-icon 字段(L139-L146);__init__.py 只有不存在或为自动生成内容时才会覆写(L149-L155)。生成后的 __init__.py 形如 intentkit/tools/mcp_coingecko/init.py。

步骤 4:添加图标

下载服务官方 logo(方形,SVG/PNG/JPEG/WebP)放入工具目录:

intentkit/tools/mcp_myservice/myservice.svg

然后在 schema.json 的 "title" 之后添加:

"x-icon": "/tools/mcp_myservice/myservice.svg",

步骤 5:验证

运行时工作机制

  1. 门控(Gating):McpCategoryModule.get_tools() 读取服务器级可见性 states<a href="https://link.gitcode.com/i/ef3c82038b104e904f65e6c84890473e" target="_blank">server_name]([intentkit/tools/mcp/wrapper.py)。值为 "public" 时总是开启;为 "private" 且调用者是所有者时开启;否则返回空列表。判定逻辑复用 is_tool_visible()(intentkit/tools/base.py);
  2. 发现(Discovery):开启后,向服务器查询当前工具列表并全部暴露,不做单工具过滤。结果以 {(server_name, api_key): (instances, timestamp)} 为键缓存 1 小时(intentkit/tools/mcp/wrapper.py)——缓存 key 包含解析后的 API key,因为同一服务器对不同 key 可能暴露不同工具集;
  3. 执行(Execution):McpToolTool._arun() 调用 call_mcp_tool(),打开 MCP 会话、按原始(未加前缀)工具名调用远程工具并返回文本结果(intentkit/tools/mcp/tool.py)。协议层 call_mcp_tool 位于 intentkit/clients/mcp/client.py,它会检查 result.isError 并拼接全部 TextContent;工具名映射逻辑在 create_mcp_tool(intentkit/tools/mcp/tool.py)——LangChain 侧名称加 {server_name}_ 前缀防冲突,远程只认原名;
  4. API key 解析:McpToolTool._resolve_api_key()(intentkit/tools/mcp/tool.py)遵循按 Agent 的 key 优先于系统 key的优先级:先从 context.agent.tool_config(category) 取 api_key,没有则回落到系统配置。

Schema 自动生成的细节

scripts/sync_mcp_schemas.py 的 generate_schema 揭示了生成 schema 的完整形态:顶层为 $schema(draft-07)、type: "object"、title、description、x-tags;properties 含 enabled(默认 false)与 states;states 内是单个服务器级开关,enum 为 ["disabled", "public", "private"],默认 disabled,并带 x-enum-title 可读文案。若服务器需要鉴权(api_key_config_attr 非空),还会追加可选的 api_key 字段,标记 "x-sensitive": true,说明为"留空则使用系统 key"。

结语

两种工具开发路径各有适用场景:需要细粒度按工具开关、重度依赖供应商数据或追求 schema 版本化时,选择原生工具(参考 intentkit/tools/twitter/ 的完整实现);希望以最小成本接入外部 MCP 生态、且能接受粗粒度服务器级开关时,选择 MCP 包装(参考 intentkit/tools/mcp_coingecko/ 与 intentkit/clients/mcp/ 的既有实现)。无论哪条路径,遵守依赖规则、__init__.py 双函数契约与 schema.json 规范,就能让新工具被执行器自动发现、被 Agent 正确选用。仓库中的测试(如 tests/tools/test_tool_listing.py、tests/tools/test_tool_registry.py、tests/tools/test_mcp_wrapper.py)可进一步帮助你验证工具注册、可用性与 schema 状态同步行为。

登录后查看全文
intentkit