CoAgents：通过多智能体协作学习使用工具的框架

CoAgents 是一个创新的多智能体协作框架，旨在提升大语言模型（LLM）使用外部工具和API的能力。这个框架的核心思想是将复杂的工具使用任务分解给三个专门的智能体，它们分别是：负责生成工具使用指令的“基础代理”（Grounding Agent）、负责执行具体工具操作的“执行代理”（Execution Agent），以及负责从工具返回结果中提取关键信息的“观察代理”（Observing Agent）。这三个智能体通过互动和协作，形成一个完整的反馈循环。当工具环境返回错误或反馈时，执行代理和观察代理能够进行迭代调整和自我修正，从而让模型学会如何更精确、更有效地使用工具来完成任务。该项目的实现代码已在GitHub开源，并提供了基于TMDB（电影数据库）API的演示，帮助用户理解和应用。

功能列表

• 多智能体协作框架：创新性地采用三个独立的智能体（基础、执行、观察）协同工作，将工具使用的流程分解为指令生成、执行和结果分析三个步骤。
• 迭代学习与适应：当工具执行出错或结果不理想时，框架能够接收来自环境的反馈，并驱动执行代理和观察代理进行自我调整和优化。
• 工具指令生成：基础代理（Grounding Agent）负责理解用户意图，并将其转化为具体、可执行的工具使用指令。
• 工具执行与结果提取：执行代理（Execution Agent）调用指定的工具或API，而观察代理（Observing Agent）则从返回的原始数据中精准提取出有价值的信息。
• 支持OpenAI模型：框架集成了OpenAI的API，用户可以配置使用gpt-3.5-turbo等多种模型作为智能体的驱动核心。
• API密钥轮换：支持在配置中添加多个OpenAI API密钥，并通过随机选择策略进行请求，以规避单个密钥的速率限制。
• 自定义API端点：用户可以灵活配置Open-AI API的请求地址（Base URL），方便接入第三方或自建的LLM服务。
• TMDB演示案例：提供了一个基于TMDB电影数据库API的完整演示脚本run_tmdb.py，展示了智能体如何协作查询电影信息。

使用帮助

CoAgents 是一个基于Python的实验性框架，旨在探索如何让大语言模型更好地学习使用工具。下面将详细介绍如何配置和运行该项目。

1. 环境准备与安装

首先，你需要一个安装了Python的环境。然后，通过pip命令安装项目所需的核心依赖库。这些库为框架提供了基础能力，例如langchain用于构建智能体应用，openai用于与大语言模型进行交互。

打开你的终端（命令行工具），执行以下命令：

pip install langchain==0.0.338 openai==1.7.1 tiktoken==0.5.1 colorama==0.4.6

注：虽然官方文档建议langchain使用0.0.338版本，但同样兼容更新的版本。

2. 获取并配置API密钥

CoAgents的运行依赖两类外部API：OpenAI API 和 TMDB API。

配置OpenAI API密钥

1. 你需要拥有一个或多个OpenAI API密钥。
2. 在项目的根目录中，找到并打开文件./utilize/apis.py。
3. 在该文件中，你会看到一个名为api_keys_list的Python列表。将你的OpenAI密钥字符串添加到这个列表中。

   # 文件路径：./utilize/apis.py
   api_keys_list = [
   'sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx', # 在这里替换成你的第一个API密钥
   'sk-yyyyyyyyyyyyyyyyyyyyyyyyyyyyyy', # 如果有多个，可以继续添加
   ]
   

   该框架设计了一个巧妙的机制：每次请求时，它会从列表中随机选择一个密钥。这样做可以有效分散请求压力，避免因单个密钥达到频率限制而导致程序中断。

4. 如果你使用第三方代理服务或自建的LLM服务，可以修改BASE_URL变量来指定API的请求地址。如果使用官方API，则无需修改。

   # 文件路径：./utilize/apis.py
   BASE_URL = 'https://api.openai.com/v1' # 如果需要，可修改为你的代理地址
   

配置TMDB API访问令牌

1. 访问 TMDB (The Movie Database) 官方网站并注册一个账户。
2. 根据TMDB的指引，申请一个API访问令牌（Access Token）。
3. 在CoAgents项目的根目录下，手动创建一个新文件，并将其命名为access_token.txt。
4. 将你获取的TMDB访问令牌粘贴到这个新建的文件中并保存。

3. 运行演示程序

完成以上所有配置后，你就可以运行项目自带的演示程序run_tmdb.py了。这个程序将展示CoAgents如何使用TMDB的API来查询电影数据。

打开终端，进入项目的根目录，然后执行以下命令：

python run_tmdb.py
--model_name 'gpt-3.5-turbo'
--log_file './log_file.json'
--data_file <your_dataset_file>
--access_token_file './access_token.txt'

下面详细解释一下每个命令行参数的含义：

• model_name: 指定驱动智能体的大语言模型。默认为gpt-3.5-turbo，你可以根据需要在代码中进行调整。
• log_file: 指定一个文件路径，用于记录程序运行过程中智能体之间的交互日志。这对于调试和分析非常有用。
• data_file: 指定包含任务数据的数据集文件。你需要提供一个符合格式要求的数据文件，其中包含了需要查询的任务指令。
• access_token_file: 指定存储TMDB访问令牌的文件路径。这里我们指向刚刚创建的access_token.txt。

执行该命令后，CoAgents框架将开始工作。基础代理会根据数据集中的任务生成工具使用计划，执行代理会调用TMDB API，而观察代理会从返回的JSON数据中提取所需信息，最终完成查询任务并将结果输出。整个过程的详细日志将被记录在你指定的log_file.json文件中。

应用场景

1. 智能API调用
   在需要与复杂的外部API（如社交媒体、天气、金融数据等）进行交互的场景中，CoAgents可以自动学习如何构建请求、发送请求，并从返回的数据中提取关键信息，而无需开发者为每一种API编写固定的解析代码。
2. 自动化数据查询与分析
   用户可以通过自然语言提出查询需求（例如“帮我查找2023年上映的科幻电影中评分最高的五部”），CoAgents能够将该需求分解，通过调用数据库查询工具（如TMDB API）来执行查询，并整合结果，最终生成精准的答案。
3. 复杂任务拆解与执行
   对于需要多个步骤和多个工具才能完成的复杂任务，例如“规划一次从北京到上海的旅行，需要考虑天气、交通和住宿”，CoAgents的协作框架可以将任务拆解为天气查询、机票预订、酒店查询等子任务，并依次调用相应的工具来完成。
4. 软件或系统操作自动化
   CoAgents可以学习操作带有API接口的软件或操作系统。例如，通过学习文件系统的API，它可以实现文件的创建、移动和删除；通过学习日历API，它可以帮助用户自动安排会议。

QA

1. CoAgents框架包含哪几个核心智能体？它们各自的职责是什么？
   CoAgents框架包含三个核心智能体：
   • 基础代理 (Grounding Agent): 它的主要职责是理解用户的任务需求，并生成使用特定工具的详细指令或计划。
   • 执行代理 (Execution Agent): 负责根据基础代理生成的指令，实际调用并执行相应的工具或API。
   • 观察代理 (Observing Agent): 在工具执行完毕后，它负责分析返回的结果（通常是JSON或文本），并从中提取出对用户有用的关键信息。
2. 如果工具执行失败，CoAgents会如何处理？
   这是CoAgents框架的一个核心优势。当执行代理调用工具后收到错误反馈（例如API返回错误码），这个反馈会被系统捕捉。执行代理和观察代理会根据这个反馈进行迭代调整。它们会尝试修正请求参数或改变策略，然后再次尝试执行，从而实现一种自我修正的学习过程。
3. 运行CoAgents项目前，我需要准备哪些API密钥？
   你需要准备两类API凭证：
   • OpenAI API密钥: 用于驱动智能体（Agent）的思考和决策能力，支持gpt-3.5-turbo等模型。
   • TMDB API访问令牌: 用于访问项目演示案例中所使用的电影数据库（The Movie Database）API。
4. 我是否可以更换或添加新的工具？
   可以。CoAgents是一个框架，其设计本身就是为了方便地接入和使用各种工具。虽然演示案例使用的是TMDB API，但开发者可以通过扩展代码，定义新的工具并将其提供给智能体。只需让基础代理学会生成使用新工具的指令，并让观察代理学会解析新工具的返回结果即可。