CAMEL 的 ACIToolkit 实战指南用自然语言驱动 ACI 600 外部应用集成【免费下载链接】camel CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org项目地址: https://gitcode.com/GitHub_Trending/ca/camel导读ACIToolkit 是 CAMEL 框架中面向 ACIAgent Client Interface平台的标准工具包Toolkit它把 ACI 提供的 600 应用集成能力封装为可供ChatAgent直接调用的函数工具FunctionTool。本文以 ACIToolkit API 参考 为主体结合 源码实现、单元测试 与 官方示例系统讲解环境准备、初始化、应用发现/配置、账户链接、函数检索与执行等全部 API并给出一个「Agent 用一句自然语言为 GitHub 仓库加 Star」的完整可运行方案。读完本文你将掌握如何把 ACI 的工具生态无缝接入 CAMEL Agent。1. 背景ACIToolkit 在 CAMEL 工具体系中的定位CAMEL 通过camel/toolkits/目录管理数十个面向具体服务的工具包如 GitHub、Gmail、Notion、Stripe 等。ACIToolkit 是其中面向 ACI 平台的统一入口其核心定位是让 CAMEL Agent 通过统一接口发现、配置、链接并执行 ACI 生态中各类第三方应用的函数而无需为每个应用单独实现工具包。从源码看ACIToolkit 继承自 BaseToolkit并在类级别声明了两个关键装饰器见 aci_toolkit.py 头部api_keys_required( [ (None, ACI_API_KEY), ] ) class ACIToolkit(BaseToolkit): rA toolkit for interacting with the ACI API.api_keys_required定义见 camel/utils/commons.py实例化时校验ACI_API_KEY环境变量是否存在缺失则抛出ValueErrordependencies_required(aci)__init__上定义见 camel/utils/commons.py校验 Python 侧是否已安装aciSDK缺失则抛出ImportError。因此使用 ACIToolkit 的前置条件非常明确安装aci依赖 配置ACI_API_KEY环境变量二者缺一不可。测试文件中同样体现了这一点——test_aci_toolkit_init在未设置ACI_API_KEY时会被skipif跳过见 test_aci_toolkit.py。另外继承BaseToolkit还带来两个通用能力超时控制BaseToolkit.__init_subclass__会自动为所有可调用方法包装with_timeout超时值通过构造参数timeout传入base.pyMCP 服务器run_mcp_server(mode)支持以stdio/sse/streamable-http模式将工具包暴露为 MCP 服务base.py。2. 环境准备安装依赖与配置密钥2.1 安装依赖ACIToolkit 内部通过from aci import ACI实例化客户端因此需要安装 ACI 官方 Python SDKCAMEL 的camel-ai[all]安装方式同样可用见 ACI Cookbookpip install aci # 或安装 CAMEL 全量依赖 pip install camel-ai[all]2.2 配置环境变量参考 示例代码 与 ACI Cookbook需要设置三类密钥环境变量说明ACI_API_KEYACI 平台 API Key用于身份认证在 ACI 控制台platform.aci.dev申请ACI_BASE_URLACI API 的基础 URL可选默认由aciSDK 决定LINKED_ACCOUNT_OWNER或LINKED_ACCOUNT_OWNER_ID已链接账户的属主 ID例如johndoe用于代表终端用户执行函数建议使用dotenv从.env文件加载import os from dotenv import load_dotenv load_dotenv() ACI_API_KEY os.getenv(ACI_API_KEY) LINKED_ACCOUNT_OWNER os.getenv(LINKED_ACCOUNT_OWNER)说明linked_account_owner_id与「账户链接」机制强相关——需要先在 ACI 控制台完成相应应用的账户授权执行函数时才能以该属主身份操作。3. 初始化 ACIToolkit3.1 构造参数根据 API 参考 与 源码构造函数签名如下def __init__( self, api_key: Optional[str] None, # ACI API Key缺省时读取 ACI_API_KEY base_url: Optional[str] None, # ACI API 基础 URL缺省时读取 ACI_BASE_URL linked_account_owner_id: Optional[str] None, # 链接账户属主 ID如 johndoe timeout: Optional[float] None, # 请求超时时间 ) - None四个参数全部可空api_key/base_url显式传入优先否则回退到环境变量ACI_API_KEY/ACI_BASE_URLlinked_account_owner_id默认None在执行函数前建议显式指定否则调用方需在execute_function中单独传入timeout透传给BaseToolkit用于自动超时包装。3.2 初始化行为__init__中仅做三件事源码 L61-L68from aci import ACI super().__init__(timeout) self._api_key api_key or os.getenv(ACI_API_KEY) self._base_url base_url or os.getenv(ACI_BASE_URL) self.client ACI(api_keyself._api_key, base_urlself._base_url) self.linked_account_owner_id linked_account_owner_id测试 test_aci_toolkit.py 验证了两种初始化路径默认参数下_api_key应等于os.getenv(ACI_API_KEY)、linked_account_owner_id为None显式传入api_key、base_url、linked_account_owner_id时三者均被正确保存。4. 核心 API 详解ACIToolkit 共暴露 15 个方法含 1 个异步变体按职责可分为三组应用发现与配置管理、账户链接管理、函数检索与执行。以下逐一讲解签名与默认值均以 API 参考为准。4.1 应用发现与配置管理search_tool —— 按意图搜索应用def search_tool( self, intent: Optional[str] None, # 意图描述结果按与该意图的相关性排序 allowed_app_only: bool True, # 仅返回当前 api_key 被允许访问的应用 include_functions: bool False, # 是否在结果中附带函数名与描述 categories: Optional[List[str]] None, # 按分类过滤默认空列表 limit: Optional[int] 10, # 返回结果上限 offset: Optional[int] 0, # 分页偏移 ) - Optional[List[AppBasic]]成功返回List[AppBasic]异常时记录日志并返回错误字符串下同。测试 test_search_tool 验证其内部调用client.apps.search(...)参数一一对应注意 CAMEL 侧参数名allowed_app_only与 SDK 侧allowed_apps_only的差异。list_configured_apps —— 列出已配置应用def list_configured_apps( self, app_names: Optional[List[str]] None, # 按应用名过滤 limit: Optional[int] 10, offset: Optional[int] 0, ) - Union[List[AppConfiguration], str]内部调用client.app_configurations.list(...)源码 L136-L143。configure_app —— 配置应用认证方式def configure_app(self, app_name: str) - Union[Dict, str]这是一个自动判定认证方式的智能方法源码 L145-L170app_details self.get_app_details(app_name) if app_details and app_details.security_schemes[0] api_key: security_scheme SecurityScheme.API_KEY elif app_details and app_details.security_schemes[0] oauth2: security_scheme SecurityScheme.OAUTH2 else: security_scheme SecurityScheme.NO_AUTH configuration self.client.app_configurations.create( app_nameapp_name, security_schemesecurity_scheme )即先查询应用详情根据其首个安全方案api_key/oauth2/ 其他自动选择SecurityScheme.API_KEY/OAUTH2/NO_AUTH再创建配置。测试 test_configure_app 以security_schemes [api_key]的场景验证了该判定逻辑。get_app_configuration / delete_app / get_app_detailsdef get_app_configuration(self, app_name: str) - Union[AppConfiguration, str] # 查询指定应用配置 def delete_app(self, app_name: str) - Optional[str] # 删除应用配置成功返回 None def get_app_details(self, app_name: str) - AppDetails # 获取应用详情含安全方案等元数据注意get_app_details没有try/except包装源码 L244-L254异常会直接抛出delete_app成功时返回None而非消息。4.2 账户链接管理这部分管理「已授权账户」是执行函数前必须完成的一步。方法签名说明link_accountlink_account(app_name: str) - Union[LinkedAccount, str]为已配置应用链接账户若应用认证方案为API_KEY会携带self._api_key调用 SDK源码 L207-L242get_linked_accountsget_linked_accounts(app_name: str) - Union[List[LinkedAccount], str]列出某应用下全部已链接账户enable_linked_accountenable_linked_account(linked_account_id: str) - Union[LinkedAccount, str]启用指定链接账户disable_linked_accountdisable_linked_account(linked_account_id: str) - Union[LinkedAccount, str]禁用指定链接账户delete_linked_accountdelete_linked_account(linked_account_id: str) - str删除链接账户成功返回linked_account_id: {id} deleted successfully源码 L330-L332enable/disable/delete的返回值行为与调用参数在 test_aci_toolkit.py 中均有断言验证。4.3 函数检索与执行这是整个工具包的能力核心让 Agent 能「按意图找函数 → 拿函数定义 → 执行函数」。search_function —— 按意图搜索函数def search_function( self, app_names: Optional[List[str]] None, # 限定应用范围 intent: Optional[str] None, # 搜索意图 allowed_apps_only: bool True, # 仅返回允许访问应用中的函数 limit: Optional[int] 10, offset: Optional[int] 0, ) - List[Dict]内部调用client.functions.search(...)源码 L373-L379。function_definition —— 获取函数定义def function_definition(self, func_name: str) - Dict返回包含函数名、描述、参数 Schematype/function/parameters的字典直接调用client.functions.get_definition(func_name)源码 L346。返回结构可参见测试中的 Mocktest_aci_toolkit.py。execute_function —— 执行函数调用def execute_function( self, function_name: str, # 要执行的函数名 function_arguments: Dict, # 函数参数字典 linked_account_owner_id: str, # 终端用户账户属主ID须先在 ACI 控制台链接同属主账户 allowed_apps_only: bool False, # 仅使用 api_key 被允许的函数/应用 ) - Dict内部调用client.handle_function_call(...)源码 L404-L410。测试 test_execute_function 确认四个参数原样透传给 SDK。aexecute_function —— 异步执行函数调用async def aexecute_function( self, function_name: str, function_arguments: Dict, linked_account_owner_id: str, allowed_apps_only: bool False, ) - Dict通过asyncio.to_thread把同步的handle_function_call放到线程池中执行避免阻塞事件循环源码 L412-L442。测试 test_aexecute_function 使用pytest.mark.asyncio验证其异步行为。5. get_tools()把 ACI 能力注入 ChatAgentget_tools()是每个 Toolkit 的通用出口返回List[FunctionTool]。ACIToolkit 的实现源码 L444-L501分两步第一步注册 15 个管理类工具。将search_tool、list_configured_apps、configure_app、get_app_configuration、delete_app、link_account、get_app_details、get_linked_accounts、enable_linked_account、disable_linked_account、delete_linked_account、function_definition、search_function、execute_function、aexecute_function全部包装为FunctionTool。第二步动态注入已配置应用的真实函数。流程如下源码 L451-L500_configure_app [app.app_name for app in self.list_configured_apps() or []] _all_function self.search_function(app_names_configure_app) for function in _all_function: schema self.client.functions.get_definition(function[function][name]) def dummy_func(*, schemaschema, **kwargs): return self.execute_function( function_nameschema[function][name], function_argumentskwargs, linked_account_owner_idself.linked_account_owner_id, ) async def async_dummy_func(*, schemaschema, **kwargs): return await self.aexecute_function( function_nameschema[function][name], function_argumentskwargs, linked_account_owner_idself.linked_account_owner_id, ) dummy_func.async_call async_dummy_func # 为同步函数附加异步入口 tool FunctionTool(funcdummy_func, openai_tool_schemaschema) tools.append(tool)关键点闭包捕获每个dummy_func通过默认参数schemaschema绑定各自的函数定义避免循环变量共享Schema 透传以 ACI 返回的原始 OpenAI 兼容 Schema 直接构造FunctionToolLLM 据此生成参数同步/异步双入口dummy_func.async_call async_dummy_func让同一工具既能被同步调用也能被异步调用数量可预期get_tools()返回 15 个管理工具 已配置应用函数数测试 test_get_tools 在 Mock 出 1 个函数时断言结果为 16 个工具。6. 完整实战一句自然语言操作 GitHub下面复现 examples/toolkits/aci_toolkit.py 的完整流程——让 CAMEL Agent 用自然语言star the repo camel-ai/camel为 GitHub 仓库加 Star。6.1 完整代码import os from dotenv import load_dotenv from camel.agents import ChatAgent from camel.models import ModelFactory from camel.toolkits import ACIToolkit from camel.types import ModelPlatformType, ModelType load_dotenv() LINKED_ACCOUNT_OWNER os.getenv(LINKED_ACCOUNT_OWNER) if LINKED_ACCOUNT_OWNER is None: raise ValueError(LINKED_ACCOUNT_OWNER environment variable is not set.) # 创建 ACIToolkit带 GitHub 应用权限 aci_toolkit ACIToolkit(linked_account_owner_idLINKED_ACCOUNT_OWNER) # 创建默认模型 model ModelFactory.create( model_platformModelPlatformType.DEFAULT, model_typeModelType.DEFAULT, ) # 创建 ChatAgent并注入 ACI 工具 chat_agent ChatAgent( modelmodel, toolsaci_toolkit.get_tools(), # 显式启用 GitHub 应用工具 ) # 执行自然语言指令 response chat_agent.step(star the repo camel-ai/camel) print(response)6.2 运行链路解析aci_toolkit.get_tools()动态加载 GitHub 相关函数例如GITHUB__STAR_REPOSITORYChatAgent.step(star the repo camel-ai/camel)中LLM 依据函数 Schema 生成工具调用框架调用对应的dummy_func其内部通过execute_function调用 ACI 的handle_function_callACI 以linked_account_owner_id对应的已授权账户身份完成 GitHub 操作。示例文件末尾给出了真实运行输出examples/toolkits/aci_toolkit.py其中tool_calls记录了ToolCallingRecord( tool_nameGITHUB__STAR_REPOSITORY, args{path: {repo: camel, owner: camel-ai}}, result{success: True, data: {}}, ... )Agent 最终回复「The repositorycamel-ai/camelhas been successfully starred!」——整条链路从自然语言到真实第三方操作完全打通。6.3 交互式查询变体examples/usecases/aci_mcp/aci_toolkit_camel.py 提供了一个交互式版本从环境读取LINKED_ACCOUNT_OWNER_ID用 Gemini 模型ModelPlatformType.GEMINIModelType.GEMINI_2_5_PRO构建 Agent支持用户输入任意查询后调用 ACI 工具并打印响应可作为多模型场景下的参考模板。7. 进阶把 ACIToolkit 暴露为 MCP 服务器由于ACIToolkit继承自BaseToolkit它天然具备 run_mcp_server 能力可将其工具以 MCP 协议暴露给任意 MCP 客户端from camel.toolkits import ACIToolkit toolkit ACIToolkit(linked_account_owner_idjohndoe) toolkit.run_mcp_server(modestdio) # 或 sse / streamable-http相关 cookbook 位于 docs/cookbooks/mcp/camel_aci_mcp_cookbook.ipynb展示了「CAMEL Toolkit 作为 MCP 服务器」的完整用法。8. 行为契约与测试验证ACIToolkit 的单元测试集中在 test/toolkits/test_aci_toolkit.py从中可以总结出清晰的行为契约统一异常处理除get_app_details与function_definition外绝大多数方法用try/except包裹 SDK 调用异常时通过logger.error记录并返回错误字符串而非抛出异常——这让工具在 Agent 循环中「失败可观测、可重试」环境依赖真实初始化测试test_aci_toolkit_init要求ACI_API_KEY已设置否则跳过SDK 参数透传CAMEL 侧参数与 SDK 侧参数一一映射如allowed_app_only→allowed_apps_only测试用assert_called_once_with严格校验工具数量get_tools() 固定 15 个管理工具 动态注入的已配置应用函数。运行测试需先设置ACI_API_KEYpytest test/toolkits/test_aci_toolkit.py9. 常见问题与使用建议初始化报ValueError: Missing required API key未设置ACI_API_KEY环境变量。请先到 ACI 控制台申请 Key 并export ACI_API_KEY...初始化报ImportError: Missing required modules: aci未安装 ACI Python SDK执行pip install aci执行函数返回权限错误检查是否在 ACI 控制台完成了对应应用的授权以及linked_account_owner_id是否与控制台中的账户属主一致必要时把allowed_apps_only设为True只使用 api_key 明确允许的函数工具数量不符合预期get_tools()只注入「已配置应用」的函数先调用configure_app(app_name)并link_account(app_name)完成配置与授权函数才会出现在工具列表中需要异步场景在异步 Agent 或高并发场景优先使用aexecute_function避免同步调用阻塞事件循环。10. 总结ACIToolkit 是 CAMEL 与 ACI 生态之间的桥梁通过「应用搜索 → 应用配置 → 账户链接 → 函数检索 → 函数执行」五步标准化流程把 600 第三方应用能力以统一的 FunctionTool 形式暴露给 LLM。其 15 个 API 覆盖了从资源发现到最终执行的全生命周期配合get_tools()的动态注入机制开发者只需十余行代码即可让 Agent 用自然语言操作真实世界的外部应用。【免费下载链接】camel CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org项目地址: https://gitcode.com/GitHub_Trending/ca/camel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
CAMEL 的 ACIToolkit 实战指南用自然语言驱动 ACI 600 外部应用集成【免费下载链接】camel CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org项目地址: https://gitcode.com/GitHub_Trending/ca/camel导读ACIToolkit 是 CAMEL 框架中面向 ACIAgent Client Interface平台的标准工具包Toolkit它把 ACI 提供的 600 应用集成能力封装为可供ChatAgent直接调用的函数工具FunctionTool。本文以 ACIToolkit API 参考 为主体结合 源码实现、单元测试 与 官方示例系统讲解环境准备、初始化、应用发现/配置、账户链接、函数检索与执行等全部 API并给出一个「Agent 用一句自然语言为 GitHub 仓库加 Star」的完整可运行方案。读完本文你将掌握如何把 ACI 的工具生态无缝接入 CAMEL Agent。1. 背景ACIToolkit 在 CAMEL 工具体系中的定位CAMEL 通过camel/toolkits/目录管理数十个面向具体服务的工具包如 GitHub、Gmail、Notion、Stripe 等。ACIToolkit 是其中面向 ACI 平台的统一入口其核心定位是让 CAMEL Agent 通过统一接口发现、配置、链接并执行 ACI 生态中各类第三方应用的函数而无需为每个应用单独实现工具包。从源码看ACIToolkit 继承自 BaseToolkit并在类级别声明了两个关键装饰器见 aci_toolkit.py 头部api_keys_required( [ (None, ACI_API_KEY), ] ) class ACIToolkit(BaseToolkit): rA toolkit for interacting with the ACI API.api_keys_required定义见 camel/utils/commons.py实例化时校验ACI_API_KEY环境变量是否存在缺失则抛出ValueErrordependencies_required(aci)__init__上定义见 camel/utils/commons.py校验 Python 侧是否已安装aciSDK缺失则抛出ImportError。因此使用 ACIToolkit 的前置条件非常明确安装aci依赖 配置ACI_API_KEY环境变量二者缺一不可。测试文件中同样体现了这一点——test_aci_toolkit_init在未设置ACI_API_KEY时会被skipif跳过见 test_aci_toolkit.py。另外继承BaseToolkit还带来两个通用能力超时控制BaseToolkit.__init_subclass__会自动为所有可调用方法包装with_timeout超时值通过构造参数timeout传入base.pyMCP 服务器run_mcp_server(mode)支持以stdio/sse/streamable-http模式将工具包暴露为 MCP 服务base.py。2. 环境准备安装依赖与配置密钥2.1 安装依赖ACIToolkit 内部通过from aci import ACI实例化客户端因此需要安装 ACI 官方 Python SDKCAMEL 的camel-ai[all]安装方式同样可用见 ACI Cookbookpip install aci # 或安装 CAMEL 全量依赖 pip install camel-ai[all]2.2 配置环境变量参考 示例代码 与 ACI Cookbook需要设置三类密钥环境变量说明ACI_API_KEYACI 平台 API Key用于身份认证在 ACI 控制台platform.aci.dev申请ACI_BASE_URLACI API 的基础 URL可选默认由aciSDK 决定LINKED_ACCOUNT_OWNER或LINKED_ACCOUNT_OWNER_ID已链接账户的属主 ID例如johndoe用于代表终端用户执行函数建议使用dotenv从.env文件加载import os from dotenv import load_dotenv load_dotenv() ACI_API_KEY os.getenv(ACI_API_KEY) LINKED_ACCOUNT_OWNER os.getenv(LINKED_ACCOUNT_OWNER)说明linked_account_owner_id与「账户链接」机制强相关——需要先在 ACI 控制台完成相应应用的账户授权执行函数时才能以该属主身份操作。3. 初始化 ACIToolkit3.1 构造参数根据 API 参考 与 源码构造函数签名如下def __init__( self, api_key: Optional[str] None, # ACI API Key缺省时读取 ACI_API_KEY base_url: Optional[str] None, # ACI API 基础 URL缺省时读取 ACI_BASE_URL linked_account_owner_id: Optional[str] None, # 链接账户属主 ID如 johndoe timeout: Optional[float] None, # 请求超时时间 ) - None四个参数全部可空api_key/base_url显式传入优先否则回退到环境变量ACI_API_KEY/ACI_BASE_URLlinked_account_owner_id默认None在执行函数前建议显式指定否则调用方需在execute_function中单独传入timeout透传给BaseToolkit用于自动超时包装。3.2 初始化行为__init__中仅做三件事源码 L61-L68from aci import ACI super().__init__(timeout) self._api_key api_key or os.getenv(ACI_API_KEY) self._base_url base_url or os.getenv(ACI_BASE_URL) self.client ACI(api_keyself._api_key, base_urlself._base_url) self.linked_account_owner_id linked_account_owner_id测试 test_aci_toolkit.py 验证了两种初始化路径默认参数下_api_key应等于os.getenv(ACI_API_KEY)、linked_account_owner_id为None显式传入api_key、base_url、linked_account_owner_id时三者均被正确保存。4. 核心 API 详解ACIToolkit 共暴露 15 个方法含 1 个异步变体按职责可分为三组应用发现与配置管理、账户链接管理、函数检索与执行。以下逐一讲解签名与默认值均以 API 参考为准。4.1 应用发现与配置管理search_tool —— 按意图搜索应用def search_tool( self, intent: Optional[str] None, # 意图描述结果按与该意图的相关性排序 allowed_app_only: bool True, # 仅返回当前 api_key 被允许访问的应用 include_functions: bool False, # 是否在结果中附带函数名与描述 categories: Optional[List[str]] None, # 按分类过滤默认空列表 limit: Optional[int] 10, # 返回结果上限 offset: Optional[int] 0, # 分页偏移 ) - Optional[List[AppBasic]]成功返回List[AppBasic]异常时记录日志并返回错误字符串下同。测试 test_search_tool 验证其内部调用client.apps.search(...)参数一一对应注意 CAMEL 侧参数名allowed_app_only与 SDK 侧allowed_apps_only的差异。list_configured_apps —— 列出已配置应用def list_configured_apps( self, app_names: Optional[List[str]] None, # 按应用名过滤 limit: Optional[int] 10, offset: Optional[int] 0, ) - Union[List[AppConfiguration], str]内部调用client.app_configurations.list(...)源码 L136-L143。configure_app —— 配置应用认证方式def configure_app(self, app_name: str) - Union[Dict, str]这是一个自动判定认证方式的智能方法源码 L145-L170app_details self.get_app_details(app_name) if app_details and app_details.security_schemes[0] api_key: security_scheme SecurityScheme.API_KEY elif app_details and app_details.security_schemes[0] oauth2: security_scheme SecurityScheme.OAUTH2 else: security_scheme SecurityScheme.NO_AUTH configuration self.client.app_configurations.create( app_nameapp_name, security_schemesecurity_scheme )即先查询应用详情根据其首个安全方案api_key/oauth2/ 其他自动选择SecurityScheme.API_KEY/OAUTH2/NO_AUTH再创建配置。测试 test_configure_app 以security_schemes [api_key]的场景验证了该判定逻辑。get_app_configuration / delete_app / get_app_detailsdef get_app_configuration(self, app_name: str) - Union[AppConfiguration, str] # 查询指定应用配置 def delete_app(self, app_name: str) - Optional[str] # 删除应用配置成功返回 None def get_app_details(self, app_name: str) - AppDetails # 获取应用详情含安全方案等元数据注意get_app_details没有try/except包装源码 L244-L254异常会直接抛出delete_app成功时返回None而非消息。4.2 账户链接管理这部分管理「已授权账户」是执行函数前必须完成的一步。方法签名说明link_accountlink_account(app_name: str) - Union[LinkedAccount, str]为已配置应用链接账户若应用认证方案为API_KEY会携带self._api_key调用 SDK源码 L207-L242get_linked_accountsget_linked_accounts(app_name: str) - Union[List[LinkedAccount], str]列出某应用下全部已链接账户enable_linked_accountenable_linked_account(linked_account_id: str) - Union[LinkedAccount, str]启用指定链接账户disable_linked_accountdisable_linked_account(linked_account_id: str) - Union[LinkedAccount, str]禁用指定链接账户delete_linked_accountdelete_linked_account(linked_account_id: str) - str删除链接账户成功返回linked_account_id: {id} deleted successfully源码 L330-L332enable/disable/delete的返回值行为与调用参数在 test_aci_toolkit.py 中均有断言验证。4.3 函数检索与执行这是整个工具包的能力核心让 Agent 能「按意图找函数 → 拿函数定义 → 执行函数」。search_function —— 按意图搜索函数def search_function( self, app_names: Optional[List[str]] None, # 限定应用范围 intent: Optional[str] None, # 搜索意图 allowed_apps_only: bool True, # 仅返回允许访问应用中的函数 limit: Optional[int] 10, offset: Optional[int] 0, ) - List[Dict]内部调用client.functions.search(...)源码 L373-L379。function_definition —— 获取函数定义def function_definition(self, func_name: str) - Dict返回包含函数名、描述、参数 Schematype/function/parameters的字典直接调用client.functions.get_definition(func_name)源码 L346。返回结构可参见测试中的 Mocktest_aci_toolkit.py。execute_function —— 执行函数调用def execute_function( self, function_name: str, # 要执行的函数名 function_arguments: Dict, # 函数参数字典 linked_account_owner_id: str, # 终端用户账户属主ID须先在 ACI 控制台链接同属主账户 allowed_apps_only: bool False, # 仅使用 api_key 被允许的函数/应用 ) - Dict内部调用client.handle_function_call(...)源码 L404-L410。测试 test_execute_function 确认四个参数原样透传给 SDK。aexecute_function —— 异步执行函数调用async def aexecute_function( self, function_name: str, function_arguments: Dict, linked_account_owner_id: str, allowed_apps_only: bool False, ) - Dict通过asyncio.to_thread把同步的handle_function_call放到线程池中执行避免阻塞事件循环源码 L412-L442。测试 test_aexecute_function 使用pytest.mark.asyncio验证其异步行为。5. get_tools()把 ACI 能力注入 ChatAgentget_tools()是每个 Toolkit 的通用出口返回List[FunctionTool]。ACIToolkit 的实现源码 L444-L501分两步第一步注册 15 个管理类工具。将search_tool、list_configured_apps、configure_app、get_app_configuration、delete_app、link_account、get_app_details、get_linked_accounts、enable_linked_account、disable_linked_account、delete_linked_account、function_definition、search_function、execute_function、aexecute_function全部包装为FunctionTool。第二步动态注入已配置应用的真实函数。流程如下源码 L451-L500_configure_app [app.app_name for app in self.list_configured_apps() or []] _all_function self.search_function(app_names_configure_app) for function in _all_function: schema self.client.functions.get_definition(function[function][name]) def dummy_func(*, schemaschema, **kwargs): return self.execute_function( function_nameschema[function][name], function_argumentskwargs, linked_account_owner_idself.linked_account_owner_id, ) async def async_dummy_func(*, schemaschema, **kwargs): return await self.aexecute_function( function_nameschema[function][name], function_argumentskwargs, linked_account_owner_idself.linked_account_owner_id, ) dummy_func.async_call async_dummy_func # 为同步函数附加异步入口 tool FunctionTool(funcdummy_func, openai_tool_schemaschema) tools.append(tool)关键点闭包捕获每个dummy_func通过默认参数schemaschema绑定各自的函数定义避免循环变量共享Schema 透传以 ACI 返回的原始 OpenAI 兼容 Schema 直接构造FunctionToolLLM 据此生成参数同步/异步双入口dummy_func.async_call async_dummy_func让同一工具既能被同步调用也能被异步调用数量可预期get_tools()返回 15 个管理工具 已配置应用函数数测试 test_get_tools 在 Mock 出 1 个函数时断言结果为 16 个工具。6. 完整实战一句自然语言操作 GitHub下面复现 examples/toolkits/aci_toolkit.py 的完整流程——让 CAMEL Agent 用自然语言star the repo camel-ai/camel为 GitHub 仓库加 Star。6.1 完整代码import os from dotenv import load_dotenv from camel.agents import ChatAgent from camel.models import ModelFactory from camel.toolkits import ACIToolkit from camel.types import ModelPlatformType, ModelType load_dotenv() LINKED_ACCOUNT_OWNER os.getenv(LINKED_ACCOUNT_OWNER) if LINKED_ACCOUNT_OWNER is None: raise ValueError(LINKED_ACCOUNT_OWNER environment variable is not set.) # 创建 ACIToolkit带 GitHub 应用权限 aci_toolkit ACIToolkit(linked_account_owner_idLINKED_ACCOUNT_OWNER) # 创建默认模型 model ModelFactory.create( model_platformModelPlatformType.DEFAULT, model_typeModelType.DEFAULT, ) # 创建 ChatAgent并注入 ACI 工具 chat_agent ChatAgent( modelmodel, toolsaci_toolkit.get_tools(), # 显式启用 GitHub 应用工具 ) # 执行自然语言指令 response chat_agent.step(star the repo camel-ai/camel) print(response)6.2 运行链路解析aci_toolkit.get_tools()动态加载 GitHub 相关函数例如GITHUB__STAR_REPOSITORYChatAgent.step(star the repo camel-ai/camel)中LLM 依据函数 Schema 生成工具调用框架调用对应的dummy_func其内部通过execute_function调用 ACI 的handle_function_callACI 以linked_account_owner_id对应的已授权账户身份完成 GitHub 操作。示例文件末尾给出了真实运行输出examples/toolkits/aci_toolkit.py其中tool_calls记录了ToolCallingRecord( tool_nameGITHUB__STAR_REPOSITORY, args{path: {repo: camel, owner: camel-ai}}, result{success: True, data: {}}, ... )Agent 最终回复「The repositorycamel-ai/camelhas been successfully starred!」——整条链路从自然语言到真实第三方操作完全打通。6.3 交互式查询变体examples/usecases/aci_mcp/aci_toolkit_camel.py 提供了一个交互式版本从环境读取LINKED_ACCOUNT_OWNER_ID用 Gemini 模型ModelPlatformType.GEMINIModelType.GEMINI_2_5_PRO构建 Agent支持用户输入任意查询后调用 ACI 工具并打印响应可作为多模型场景下的参考模板。7. 进阶把 ACIToolkit 暴露为 MCP 服务器由于ACIToolkit继承自BaseToolkit它天然具备 run_mcp_server 能力可将其工具以 MCP 协议暴露给任意 MCP 客户端from camel.toolkits import ACIToolkit toolkit ACIToolkit(linked_account_owner_idjohndoe) toolkit.run_mcp_server(modestdio) # 或 sse / streamable-http相关 cookbook 位于 docs/cookbooks/mcp/camel_aci_mcp_cookbook.ipynb展示了「CAMEL Toolkit 作为 MCP 服务器」的完整用法。8. 行为契约与测试验证ACIToolkit 的单元测试集中在 test/toolkits/test_aci_toolkit.py从中可以总结出清晰的行为契约统一异常处理除get_app_details与function_definition外绝大多数方法用try/except包裹 SDK 调用异常时通过logger.error记录并返回错误字符串而非抛出异常——这让工具在 Agent 循环中「失败可观测、可重试」环境依赖真实初始化测试test_aci_toolkit_init要求ACI_API_KEY已设置否则跳过SDK 参数透传CAMEL 侧参数与 SDK 侧参数一一映射如allowed_app_only→allowed_apps_only测试用assert_called_once_with严格校验工具数量get_tools() 固定 15 个管理工具 动态注入的已配置应用函数。运行测试需先设置ACI_API_KEYpytest test/toolkits/test_aci_toolkit.py9. 常见问题与使用建议初始化报ValueError: Missing required API key未设置ACI_API_KEY环境变量。请先到 ACI 控制台申请 Key 并export ACI_API_KEY...初始化报ImportError: Missing required modules: aci未安装 ACI Python SDK执行pip install aci执行函数返回权限错误检查是否在 ACI 控制台完成了对应应用的授权以及linked_account_owner_id是否与控制台中的账户属主一致必要时把allowed_apps_only设为True只使用 api_key 明确允许的函数工具数量不符合预期get_tools()只注入「已配置应用」的函数先调用configure_app(app_name)并link_account(app_name)完成配置与授权函数才会出现在工具列表中需要异步场景在异步 Agent 或高并发场景优先使用aexecute_function避免同步调用阻塞事件循环。10. 总结ACIToolkit 是 CAMEL 与 ACI 生态之间的桥梁通过「应用搜索 → 应用配置 → 账户链接 → 函数检索 → 函数执行」五步标准化流程把 600 第三方应用能力以统一的 FunctionTool 形式暴露给 LLM。其 15 个 API 覆盖了从资源发现到最终执行的全生命周期配合get_tools()的动态注入机制开发者只需十余行代码即可让 Agent 用自然语言操作真实世界的外部应用。【免费下载链接】camel CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org项目地址: https://gitcode.com/GitHub_Trending/ca/camel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
