Cogency：构建智能AI代理的认知架构工具

Cogency 是一个开源的认知架构工具，托管在 GitHub 上，旨在帮助开发者构建高效的 AI 代理。它通过透明的 ReAct 循环（推理、行动、观察、生成）实现多步骤任务处理，支持实时流式输出和可追溯的操作。Cogency 提供灵活的工具集成，例如网页搜索、天气预报和行程规划，适合开发智能自动化应用。用户可以自定义代理的个性、语气和风格，例如创建“友好的海盗”或“耐心教师”风格的 AI 助手。项目支持多种语言模型和嵌入式后端，安装简单，开发者可快速上手。Cogency 的设计注重模块化和扩展性，适合从简单任务到复杂工作流的开发需求。

功能列表

• 多步骤推理：通过 ReAct 循环（推理、行动、观察、生成）分解复杂任务，逐步生成结果。
• 工具集成：支持网页搜索、天气预报、旅行信息等工具，开发者可自定义工具扩展功能。
• 实时流式输出：每个操作步骤实时显示，便于调试和追踪。
• 个性化代理：支持设置代理的个性、语气和风格，例如“友好的海盗”或“鼓励的教师”。
• 多语言模型支持：兼容多种主流语言模型和嵌入式后端，灵活适配不同开发需求。
• 模块化设计：提供易于扩展的架构，开发者可快速添加新工具或功能。
• 异步操作：支持异步编程，适合处理高并发任务。

使用帮助

安装流程

要使用 Cogency，开发者需先安装 Python 环境（建议 Python 3.8 或以上）。以下是详细的安装步骤：

1. 克隆项目代码：
   在终端运行以下命令，将 Cogency 仓库克隆到本地：

   git clone https://github.com/iteebz/cogency.git
   cd cogency
   

2. 安装依赖：
   使用 pip 安装 Cogency 核心包：

   pip install cogency
   

   如果需要支持所有语言模型、嵌入式后端和工具，运行：

   pip install cogency[all]
   

3. 配置 API 密钥：
   Cogency 支持多种语言模型（如 OpenAI）。需要配置 API 密钥，创建 .env 文件并添加密钥：

   echo "OPENAI_API_KEY=sk-..." >> .env
   

   替换 sk-... 为你的实际 API 密钥。支持其他提供商的密钥，具体参考官方文档。

4. 验证安装：
   运行以下代码测试安装是否成功：

   import asyncio
   from cogency import Agent
   async def main():
   agent = Agent("assistant")
   async for chunk in agent.stream("What is 25 * 43?"):
   print(chunk, end="", flush=True)
   asyncio.run(main())
   

   如果输出 1075，说明安装成功。

功能操作流程

Cogency 的核心在于通过 ReAct 循环实现智能任务处理。以下是主要功能的使用方法：

创建和使用 AI 代理

1. 初始化代理：
   创建一个基础代理：

   from cogency import Agent
   agent = Agent("assistant")
   

   可以通过设置 personality、tone 和 style 参数自定义代理。例如，创建一个“友好的海盗”代理：

   pirate = Agent("pirate", personality="friendly pirate who loves coding")
   

2. 运行任务：
   使用 stream 方法运行任务，输出实时流式结果。例如，查询数学问题：

   async for chunk in agent.stream("What is 25 * 43?"):
   print(chunk, end="", flush=True)
   

   输出为 1075。对于复杂任务，如行程规划：

   async for chunk in agent.stream("Plan a 3-day trip to Tokyo"):
   print(chunk, end="", flush=True)
   

   代理会自动调用工具（如天气预报、旅行信息），生成详细行程。

工具集成

Cogency 支持内置工具（如 web_search、weather_forecast）和自定义工具。以下是添加自定义工具的步骤：

1. 定义工具：
   创建一个自定义工具，例如获取城市时间的 TimezoneTool：

   from cogency import Agent, BaseTool
   class TimezoneTool(BaseTool):
   def __init__(self):
   super().__init__("timezone", "Get time in any city")
   async def run(self, city: str):
   return {"time": f"Current time in {city}: 14:30 PST"}
   def get_schema(self):
   return "timezone(city='string')"
   

2. 注册工具：
   将工具注册到代理：

   agent = Agent("time_assistant", tools=[TimezoneTool()])
   async for chunk in agent.stream("What's the time in London?"):
   print(chunk, end="", flush=True)
   

   输出为 Current time in London: 14:30 PST。

个性化代理设置

Cogency 允许为代理设置个性。例如，创建一个“耐心教师”风格的代理：

teacher = Agent("teacher", personality="patient teacher", tone="encouraging", style="conversational")
async for chunk in teacher.stream("Explain quantum computing"):
print(chunk, end="", flush=True)

输出将以鼓励的语气、口语化风格解释量子计算。

调试与追踪

Cogency 的每个操作步骤都可追溯。运行任务时，日志会记录推理、行动和观察的每一步。例如，运行行程规划任务时，日志可能显示：

• 推理：需要天气信息来规划活动。
• 行动：调用 weather_forecast("Tokyo 3 days")。
• 观察：获取天气数据（晴天、雨天等）。
• 生成：基于天气数据生成行程。

开发者可通过日志调试代理行为，确保任务按需执行。

注意事项

• 确保网络连接稳定，部分工具（如网页搜索）需要访问互联网。
• 检查 .env 文件中的 API 密钥是否正确配置。
• 异步编程需要 Python 的 asyncio 支持，建议熟悉异步语法。
• 官方文档（位于 GitHub 仓库的 README.md）提供更多示例和高级用法。

应用场景

1. 自动化任务处理
   Cogency 适合开发自动化工作流。例如，电商平台可使用 Cogency 代理自动回复客户咨询，结合网页搜索工具查找产品信息。
2. 旅行规划
   用户可以输入“计划东京三天行程”，Cogency 会自动调用天气预报和旅行信息工具，生成天气适配的行程建议。
3. 教育辅助
   教师风格的代理可用于解释复杂概念，如量子计算或编程基础，适合在线教育平台或个人学习。
4. 开发工具扩展
   开发者可为 Cogency 添加自定义工具，如数据库查询或文件管理，扩展其在企业级应用中的功能。

QA

1. Cogency 支持哪些语言模型？
   Cogency 支持多种主流语言模型，如 OpenAI 的 GPT 系列，具体支持列表需参考官方文档。用户需提供相应 API 密钥。
2. 如何调试代理的行为？
   Cogency 的 ReAct 循环每一步都会记录日志，开发者可查看推理、行动和观察的细节，定位问题。
3. 是否需要编程经验？
   基础使用需要 Python 编程知识，尤其是异步编程。非开发者可参考示例代码快速上手。
4. 可以离线使用吗？
   部分功能（如本地计算任务）支持离线使用，但网页搜索等工具需要联网。