基于Claude API的AI应用开发：claude-toolshed框架实战指南

1. 项目概述与核心价值

最近在折腾AI应用开发，特别是围绕Claude API构建一些自动化工具时，发现了一个挺有意思的开源项目——aksh-3141/claude-toolshed。这名字直译过来是“Claude的工具棚”，听起来就挺接地气的。简单来说，它不是一个独立的AI应用，而是一个专门为Claude API设计的“工具集”或“工具箱”框架。如果你用过Claude的API，特别是它的“工具调用”（Tool Calling）功能，就会知道这玩意儿功能强大但用起来有点繁琐。你需要自己定义工具、处理JSON、管理会话状态，代码写起来容易变得又长又乱。claude-toolshed的出现，就是为了把这些脏活累活都包了，让你能像搭积木一样，快速、优雅地把各种功能“挂载”到Claude对话中。

它的核心价值在于“提效”和“降本”。对于个人开发者或小团队，它能让你在几小时内就搭建出一个功能相对完善的AI助手原型，而不用花几天时间去处理底层的通信协议和状态管理。对于有经验的开发者，它提供了一套清晰、可扩展的架构，让你能把精力集中在业务逻辑和工具功能的实现上，而不是重复造轮子。这个项目特别适合那些想基于Claude API构建复杂对话应用、智能客服、数据分析助手或者自动化工作流的人。即使你对Python和异步编程不是特别熟，跟着它的文档和例子，也能很快上手。

2. 核心架构与设计哲学拆解

2.1 什么是“工具调用”与为什么需要框架

要理解claude-toolshed，得先搞懂Claude API的“工具调用”机制。这其实是当前大模型应用的一个主流模式：大模型本身不直接执行具体操作（比如查数据库、发邮件、调用第三方API），它只负责“思考”和“决策”。当用户提出一个需要具体操作才能回答的问题时（比如“帮我查一下上个月的销售额”），模型会“决定”需要调用哪个工具，并生成一个结构化的调用请求（一个JSON对象）。然后，你的应用程序负责接收这个请求，找到对应的函数去执行，拿到结果后，再把结果塞回给模型，由模型组织成自然语言回复给用户。

这个过程听起来简单，但实现起来坑不少。首先，你需要严格按照Anthropic的格式定义每个工具（名称、描述、参数schema）。其次，你要维护一个“工具注册表”，把定义好的工具函数映射上去。然后，在每次对话循环中，你都要检查模型的返回里是否包含了工具调用请求，如果有，就得解析、分发、执行，再把执行结果拼装好，连同历史对话一起，作为下一次请求的上下文发回去。状态管理、错误处理、异步执行……这些细节堆在一起，代码很快就变得难以维护。

claude-toolshed的设计哲学就是“约定大于配置”和“关注点分离”。它帮你把工具定义、注册、调用分发、会话管理这些通用逻辑全部封装好了。作为开发者，你只需要做两件事：1. 用Python函数和简单的装饰器来定义你的工具；2. 告诉框架怎么连接Claude API。剩下的，框架全包了。这种设计让代码结构非常清晰，工具就是纯粹的业务逻辑函数，而框架负责所有与AI模型交互的胶水代码。

2.2 项目核心组件与工作流

拆开来看，claude-toolshed主要由以下几个核心组件构成，它们共同协作，完成一次完整的工具调用对话：

1. Tool（工具）：这是最基本的单元。每一个工具对应一个Python函数。你需要用@tool装饰器来标记它，并在装饰器里提供工具的名称和描述。函数的参数和返回值类型会被框架自动用来生成符合Claude API要求的JSON Schema。比如，一个查询天气的工具，函数签名可能是def get_weather(city: str) -> str:，框架就知道这个工具需要一个字符串类型的city参数，并返回一个字符串。

2. ToolRegistry（工具注册表）：这是一个中心化的仓库，负责收集和管理所有用@tool装饰过的函数。你不需要手动注册，框架会在启动时自动发现并加载它们。这保证了工具定义的声明式和去中心化，你可以在项目的任何地方定义工具，只要它们能被导入，框架就能找到。

3. Agent/Toolset（代理/工具集）：这是与Claude模型对话的核心执行器。你创建一个Agent实例，并把你需要的工具注册表传递给它。Agent内部封装了与Claude API的通信逻辑。它的run方法是主要的入口，你传入用户消息，它就会自动处理整个“模型思考->调用工具->返回结果->模型回复”的循环，直到模型认为不需要再调用工具，给出最终答案为止。

4. Conversation（会话）：Agent内部维护着一个会话对象，它保存了完整的对话历史（包括用户消息、模型回复、工具调用和工具执行结果）。这个状态是自动管理的，确保了多轮对话中上下文的连贯性。

整个工作流可以概括为：用户输入 ->Agent.run()-> 框架将对话历史和可用工具列表发送给Claude -> Claude返回消息或工具调用请求 -> 框架解析工具调用，执行对应的Python函数 -> 将函数结果作为新的上下文消息发送给Claude -> Claude生成最终回复 -> 框架输出回复给用户。这个过程对开发者是完全透明的。

3. 从零开始：环境搭建与基础工具创建

3.1 安装与初始配置

上手的第一步是安装。claude-toolshed是一个Python库，所以前提是你得有Python环境（建议3.8以上）。安装非常简单，用pip一键搞定：

pip install claude-toolshed

安装完成后，最关键的一步是配置Claude API密钥。框架需要这个密钥来与Anthropic的服务器通信。绝对不要把密钥硬编码在代码里，更不要上传到GitHub等公开平台。最安全、最规范的做法是使用环境变量。

在终端里设置环境变量（Linux/macOS）：

export ANTHROPIC_API_KEY='你的实际API密钥'

或者在代码中通过os.environ设置（仅用于临时测试，生产环境不推荐）：

import os os.environ['ANTHROPIC_API_KEY'] = '你的实际API密钥'

对于Windows用户，可以在PowerShell中使用：

$env:ANTHROPIC_API_KEY="你的实际API密钥"

实操心得：我强烈建议使用.env文件配合python-dotenv库来管理环境变量。在项目根目录创建一个.env文件，里面写上ANTHROPIC_API_KEY=sk-xxx，然后在代码开头加两行from dotenv import load_dotenv; load_dotenv()。这样既安全（.env文件通常被.gitignore忽略），又方便，在不同环境（开发、测试、生产）切换时只需替换.env文件即可。

3.2 创建你的第一个工具

让我们从一个最简单的“Hello World”式工具开始，感受一下框架的便捷。假设我们想创建一个工具，让Claude能给我们讲个笑话。

首先，创建一个Python文件，比如my_first_agent.py。

import asyncio from claude_toolshed import tool from claude_toolshed.agent import Agent # 1. 使用装饰器定义一个工具 @tool(name="tell_joke", description="Tell a random joke.") def get_random_joke() -> str: """这个函数被@tool装饰后，就成为了一个Claude可调用的工具。 函数名本身不重要，装饰器里的name才是工具在Claude眼中的标识。 description至关重要，Claude根据它来决定什么时候调用这个工具。 """ # 这里只是一个硬编码的例子，实际可以连接笑话API jokes = [ "为什么程序员分不清万圣节和圣诞节？因为 Oct 31 == Dec 25。", "我写代码的速度，取决于咖啡因的浓度和死线的距离。", "调试代码就像在雷区里找一只变色的猫，而那只猫可能根本不存在。" ] import random return random.choice(jokes) # 2. 创建Agent并运行 async def main(): # 初始化Agent。默认使用最新的Claude模型。 agent = Agent(tools=[get_random_joke]) # 将工具函数传入 # 开始对话 response = await agent.run("给我讲个笑话吧，要程序员相关的。") print("Claude:", response) if __name__ == "__main__": asyncio.run(main())

运行这个脚本，你会看到Claude调用了tell_joke工具，并把工具返回的笑话组织成一段友好的话术回复给你。整个过程，你只需要定义函数和一句话启动对话，框架自动完成了工具描述生成、API调用、结果注入的所有中间步骤。

注意事项：@tool装饰器中的description字段是灵魂。Claude模型完全依赖这个描述来理解工具的功能。描述要清晰、具体，最好说明工具的用途、输入和输出。模糊的描述会导致模型错误调用或根本不调用。例如，“处理数据”就太模糊，“根据城市名称查询该城市当前的天气情况和温度”就明确得多。

3.3 处理带参数的复杂工具

现实中的工具很少像讲笑话这么简单。大部分工具都需要输入参数。claude-toolshed利用Python的类型注解来自动生成参数schema，非常智能。

让我们创建一个稍微复杂点的工具：一个简易的计算器，能进行加减乘除。

from claude_toolshed import tool from typing import Literal @tool( name="calculator", description="Perform a basic arithmetic operation. Choose from addition (+), subtraction (-), multiplication (*), or division (/)." ) def calculate(a: float, b: float, operation: Literal["+", "-", "*", "/"]) -> float: """执行基础算术运算。 Args: a: 第一个运算数 b: 第二个运算数 operation: 运算符，支持 +, -, *, / Returns: 运算结果 """ if operation == "+": return a + b elif operation == "-": return a - b elif operation == "*": return a * b elif operation == "/": if b == 0: return float('inf') # 简单处理除零错误，实际项目应更严谨 return a / b else: raise ValueError(f"Unsupported operation: {operation}") # 在Agent中使用 async def main(): agent = Agent(tools=[calculate]) # 你可以问：“计算一下3.14乘以2.5等于多少？” response = await agent.run("请帮我计算 (15 + 7) * 3 的值。") print(response)

这里有几个关键点：

1. 类型注解即Schema：函数参数a: float, b: float明确告诉框架，这两个参数是数字类型。Claude API会据此生成{"type": "number"}的schema。
2. 复杂类型支持：operation: Literal["+", "-", "*", "/"]使用了typing.Literal。这会被框架翻译成枚举类型（{"enum": ["+", "-", "*", "/"]}），强制Claude必须从这几个选项里选一个，避免了模型胡编乱造一个不支持的运算符。
3. 错误处理：在工具函数内部进行基本的错误检查（如除零），并返回一个合理的值或抛出异常。框架能捕获异常并将其信息传递给Claude，让模型可以向用户解释错误。

运行这段代码，Claude会理解你的问题，自动调用calculator工具，并传入正确的参数a=15, b=7, operation=‘+‘，得到结果22后，再调用一次a=22, b=3, operation=‘*‘，最终计算出66，并组织语言回复你。这一切都是自动的、链式的。

4. 构建实战：一个多功能个人助理Agent

理解了基础工具后，我们来组装一个更有用的东西：一个能查天气、记笔记、管理待办事项的个人文字助理。这个例子将涵盖更接近真实世界的场景。

4.1 工具一：智能天气查询

我们使用一个免费的公开天气API（例如Open-Meteo）来获取真实数据。这涉及到网络请求，所以工具函数必须是异步的（async def）。

import aiohttp from claude_toolshed import tool from datetime import date @tool(name="get_weather", description="Get the current weather and forecast for a given city.") async def fetch_weather(city_name: str, country_code: str = "CN") -> str: """根据城市名和国家代码查询天气。 使用Open-Meteo API，无需密钥。 """ # 1. 地理编码：将城市名转换为经纬度 geo_url = f"https://geocoding-api.open-meteo.com/v1/search?name={city_name}&country={country_code}&count=1" async with aiohttp.ClientSession() as session: async with session.get(geo_url) as resp: if resp.status != 200: return f"无法找到城市 '{city_name}' 的地理信息。" geo_data = await resp.json() if not geo_data.get('results'): return f"未找到城市 '{city_name}'。请检查拼写。" location = geo_data['results'][0] lat, lon = location['latitude'], location['longitude'] city_full_name = location.get('name', city_name) # 2. 获取天气数据 weather_url = ( f"https://api.open-meteo.com/v1/forecast?" f"latitude={lat}&longitude={lon}" f"&current=temperature_2m,weathercode&daily=weathercode,temperature_2m_max,temperature_2m_min" f"&timezone=auto" ) async with session.get(weather_url) as resp: if resp.status != 200: return f"获取{city_full_name}的天气数据失败。" weather_data = await resp.json() # 3. 解析并格式化结果 current = weather_data['current'] daily = weather_data['daily'] # 简单映射天气代码到文字（实际应用可用更全的映射表） wmo_code_map = {0: "晴", 1: "少云", 2: "多云", 3: "阴天", 45: "雾", 61: "小雨", 80: "阵雨"} current_weather = wmo_code_map.get(current['weathercode'], "未知") today = daily['time'][0] today_weather = wmo_code_map.get(daily['weathercode'][0], "未知") result = f""" {city_full_name} 当前天气： - 温度：{current['temperature_2m']}°C - 状况：{current_weather} 今日({today})预报： - 最高温：{daily['temperature_2m_max'][0]}°C - 最低温：{daily['temperature_2m_min'][0]}°C - 天气：{today_weather} """ return result

实操心得：对于涉及网络I/O的工具，务必使用异步函数（async def）和像aiohttp这样的异步HTTP客户端。这能保证你的Agent在等待一个工具（如网络请求）返回时，不会阻塞整个事件循环，从而保持高响应性。同步的requests库在异步环境里会出问题。

4.2 工具二：简易笔记与待办管理

为了简化，我们用内存中的字典来模拟数据存储。在实际项目中，你会连接到数据库（如SQLite、PostgreSQL）或云服务。

from claude_toolshed import tool from typing import Optional, List # 模拟内存存储 notes_store = {} todos_store = [] @tool(name="create_note", description="Create a new note with a title and content.") def add_note(title: str, content: str) -> str: """创建一条新笔记。""" if title in notes_store: return f"笔记 '{title}' 已存在，请使用更新功能或换一个标题。" notes_store[title] = content return f"笔记 '{title}' 创建成功。" @tool(name="get_note", description="Retrieve the content of a note by its title.") def retrieve_note(title: str) -> str: """根据标题获取笔记内容。""" content = notes_store.get(title) if content is None: return f"未找到标题为 '{title}' 的笔记。" return f"笔记 '{title}' 的内容：\n{content}" @tool(name="add_todo", description="Add a new todo item.") def add_todo_item(task: str, priority: Literal["low", "medium", "high"] = "medium") -> str: """添加一条待办事项。""" import uuid todo_id = str(uuid.uuid4())[:8] new_item = {"id": todo_id, "task": task, "priority": priority, "done": False} todos_store.append(new_item) return f"待办事项已添加 (ID: {todo_id})。任务：'{task}'，优先级：{priority}。" @tool(name="list_todos", description="List all pending todo items, optionally filtered by priority.") def list_pending_todos(priority_filter: Optional[str] = None) -> str: """列出所有未完成的待办事项。""" filtered = [t for t in todos_store if not t['done']] if priority_filter and priority_filter in ["low", "medium", "high"]: filtered = [t for t in filtered if t['priority'] == priority_filter] if not filtered: return "当前没有待办的事项。" if not priority_filter else f"没有优先级为 '{priority_filter}' 的待办事项。" result = "待办事项列表：\n" for item in filtered: result += f"- [{item['id']}] {item['task']} (优先级: {item['priority']})\n" return result

这个工具集展示了几个重要模式：

1. 工具分组：将相关的操作（笔记的增查、待办的增列）定义在同一个模块里，逻辑清晰。
2. 可选参数：priority_filter: Optional[str] = None表示这个参数可以省略。Claude在调用时，如果用户没提优先级，就不会传这个参数。
3. 状态持久化：目前数据存在内存里，程序重启就没了。这是为了演示的简化。生产环境必须使用外部持久化存储，并在工具函数中实现读写。

4.3 组装并运行多功能Agent

现在，我们把所有工具组装起来，创建一个真正的个人助理。

import asyncio from claude_toolshed.agent import Agent # 假设上面的工具定义都在同一个文件或已被导入 from my_weather_tool import fetch_weather from my_note_tools import add_note, retrieve_note, add_todo_item, list_pending_todos async def main(): # 创建Agent，传入所有工具 agent = Agent( tools=[fetch_weather, add_note, retrieve_note, add_todo_item, list_pending_todos], model="claude-3-5-sonnet-20241022", # 可以指定模型版本 max_tokens=1024, ) # 模拟一个多轮对话场景 conversation = [ "今天北京天气怎么样？", "把‘项目会议要点’记下来，内容是‘讨论claude-toolshed集成方案，负责人张三，下周交付原型’。", "我还有哪些高优先级的待办事项？", "帮我计算一下(1200 - 450) / 30 等于多少？", # 我们没加计算器工具，看Claude如何处理 ] print("=== 个人助理对话开始 ===") for user_msg in conversation: print(f"\n[用户]: {user_msg}") response = await agent.run(user_msg) print(f"[助理]: {response}") print("=== 对话结束 ===") if __name__ == "__main__": asyncio.run(main())

运行这个脚本，你会看到一个连贯的对话。Claude会根据你的问题，智能地选择调用get_weather、create_note或list_todos工具。当你问到一个它没有对应工具的问题（如计算）时，它会老实地回答“我无法执行计算”，或者尝试用推理给出一个近似答案（取决于模型）。这展示了Agent的能力边界。

5. 高级特性与生产级考量

当你想把基于claude-toolshed的原型变成真正可用的服务时，有几个高级特性和工程化问题必须考虑。

5.1 会话记忆与上下文管理

默认情况下，Agent对象会维护一个会话，记住之前的所有对话和工具调用结果。这对于多轮对话至关重要。但有时你需要更精细的控制：

• 新建会话：每次调用agent.run()，默认是延续上次会话。如果想开始一个全新话题，可以创建新的Agent实例，或者使用agent.new_session()方法（如果框架提供）。
• 上下文长度与总结：Claude模型有上下文窗口限制（如200K tokens）。超长的对话历史会被截断，可能导致遗忘早期信息。对于超长对话，一个高级策略是定期让模型自己总结之前的对话要点，然后将总结作为新的“系统提示”或压缩后的历史，再继续后续对话。claude-toolshed本身可能不直接提供此功能，但你可以通过拦截或包装agent.run的输入输出来实现。
• 会话持久化：如果你想实现“用户下次登录还能看到上次对话”的功能，就需要把agent.conversation（或其中的消息列表）序列化（如转成JSON）保存到数据库。下次初始化Agent时，再反序列化加载进去。

5.2 错误处理与工具鲁棒性

工具函数在执行时可能出错（网络超时、API限流、无效输入等）。框架通常能捕获异常并将其传递给Claude模型，模型会尝试向用户解释错误。但我们可以做得更好：

from claude_toolshed import tool import aiohttp from aiohttp import ClientError, ClientTimeout @tool(name="robust_weather", description="A more robust weather query tool.") async def get_weather_safe(city: str) -> str: try: # ... 之前的天气查询逻辑 ... async with aiohttp.ClientSession(timeout=ClientTimeout(total=10)) as session: # ... 发起请求 ... pass except ClientError as e: # 网络相关错误 return f"查询天气时网络出现错误：{str(e)}。请稍后重试。" except TimeoutError: return "天气查询请求超时，请检查网络或稍后再试。" except KeyError as e: # API返回数据格式不符合预期 return f"处理天气数据时遇到意外格式，错误信息：{str(e)}。" except Exception as e: # 捕获所有其他未预见的错误 # 生产环境应记录日志（如logging.error(e)），而不是直接返回给用户 return "系统内部处理天气请求时发生未知错误。"

核心原则：工具函数应该尽可能内部消化错误，并返回一个对用户友好的字符串信息。避免让未处理的异常直接抛出导致整个Agent会话崩溃。同时，一定要记录详细的错误日志（使用logging模块），方便后台排查。

5.3 性能优化与超时控制

• 工具执行超时：如果一个工具执行时间过长（比如一个复杂的数据库查询或慢速的第三方API），会拖累整个对话响应。可以为工具函数设置超时机制。Python的asyncio.wait_for可以派上用场。

  import asyncio from functools import wraps def tool_with_timeout(timeout_seconds=30): def decorator(func): @wraps(func) async def wrapper(*args, **kwargs): try: return await asyncio.wait_for(func(*args, **kwargs), timeout=timeout_seconds) except asyncio.TimeoutError: return f"工具 '{func.__name__}' 执行超时（>{timeout_seconds}秒），请重试或简化请求。" return wrapper return decorator @tool(name="slow_query") @tool_with_timeout(10) # 自定义超时装饰器要放在@tool里面 async def potentially_slow_operation(): await asyncio.sleep(15) # 模拟慢操作 return "Done"

• 异步并发：如果多个工具之间没有依赖关系，且框架支持，可以考虑让它们并发执行。不过，标准的Claude工具调用模式是顺序的（模型思考->调用一个工具->得到结果->再思考），所以通常不需要。

5.4 安全性与权限控制

这是企业级应用无法回避的问题。你不能让用户通过Claude调用任何工具。

• 工具级权限：最简单的办法是根据用户身份，动态构建不同的工具列表。例如，普通用户只能使用查询天气和创建笔记，而管理员则多一个系统管理工具。在创建Agent时，根据当前登录用户传入不同的tools列表即可。
• 参数校验与净化：工具函数必须对输入参数进行严格的校验。即使Claude模型已经根据schema生成了参数，也要防范潜在的注入攻击或非法值。例如，一个删除文件工具，必须校验文件路径是否在允许的目录内。

  @tool(name="read_file") def read_allowed_file(filepath: str) -> str: import os # 限制只能读取特定安全目录下的文件 SAFE_BASE_DIR = "/var/www/safe_data/" full_path = os.path.abspath(os.path.join(SAFE_BASE_DIR, filepath)) # 防止目录遍历攻击 if not full_path.startswith(os.path.abspath(SAFE_BASE_DIR)): return "错误：无权访问该路径。" if not os.path.exists(full_path): return "文件不存在。" # ... 读取文件 ...

• 访问令牌（Token）管理：如果你的工具需要调用需要认证的外部API（如公司内部系统），千万不要把API密钥硬编码在工具函数里。应该从安全的配置服务或当前用户的会话信息中获取。

6. 常见问题、调试技巧与避坑指南

在实际开发和集成claude-toolshed的过程中，你肯定会遇到各种问题。下面是我踩过的一些坑和总结的排查思路。

6.1 工具不被调用？检查描述和对话历史

问题：你明明定义了一个工具，但Claude在对话中从来不调用它。排查步骤：

1. 检查工具描述：这是最常见的原因。描述必须清晰、无歧义，准确反映工具的功能和适用场景。对比一下：

• 差描述：“处理数据”
• 好描述：“根据给定的股票代码，查询该股票最近一天的收盘价和涨跌幅。”用后者，当用户问“苹果股价怎么样？”时，模型更容易匹配到。

2. 检查工具参数Schema：在Agent初始化后，可以打印出工具列表的schema看看。

agent = Agent(tools=[my_tool]) for t in agent.tools: print(t.name, t.schema) # 查看生成的JSON Schema是否符合预期

确保参数类型（string, number, boolean等）定义正确。 3.检查对话历史/系统提示：有时之前的对话历史会把模型“带偏”。或者，如果你设置了很强的系统提示（如“你是一个只负责翻译的助手”），模型可能会自我限制，不去调用其他功能的工具。尝试开启一个新的会话（新建Agent）测试。 4.模型能力：确认你使用的Claude模型版本支持工具调用。目前claude-3-opus、claude-3-sonnet和claude-3-haiku都支持，但不同版本在工具调用的准确性和主动性上可能有细微差别。

6.2 工具调用参数错误？强化类型提示和描述

问题：Claude调用了工具，但传入的参数值类型不对或格式错误，导致工具函数执行失败。解决方案：

• 使用更精确的类型：除了基本的str,int,float,bool，多用typing模块。List[str],Dict[str, int],Literal[“yes“, “no“]都能生成更精确的schema，约束模型的输出。
• 在描述中明确格式：如果参数有特定格式（如日期“YYYY-MM-DD”，邮箱地址），一定要在工具描述或参数描述中写明。例如：@tool(description=“查询日历。date参数格式必须为YYYY-MM-DD。”)
• 工具函数内部做防御性校验：这是最后一道防线。即使参数不对，也要优雅处理。

  @tool(name="send_email") def send_email(to: str, subject: str, body: str) -> str: import re # 简单的邮箱格式校验 if not re.match(r"[^@]+@[^@]+\.[^@]+", to): return f"错误：邮箱地址‘{to}’格式无效。" # ... 发送逻辑 ...

6.3 异步工具函数卡住或报错？确保正确的异步上下文

问题：在运行异步工具时，程序卡住、报错Event loop is closed或Task was destroyed but it is pending。根本原因：异步事件循环管理不当。claude-toolshed内部是异步的，你的异步工具函数也必须在正确的事件循环中运行。解决与避坑：

1. 入口点使用asyncio.run()：这是最安全的方式，如我们所有例子所示。
2. 避免在同步函数中调用异步Agent：如果你在Flask、Django（非异步视图）这样的同步Web框架中集成，不能直接await agent.run()。你需要使用asyncio.run()在一个新的事件循环中运行，或者使用asyncio.create_task并在一个已运行的事件循环中管理。更推荐使用支持异步的Web框架（如FastAPI、Sanic、Quart）。
3. 管理好HTTP会话：对于aiohttp，不要在每次工具调用时都创建新的ClientSession，这很耗资源且可能导致端口耗尽。最好在工具函数外部创建并复用session，或者使用框架提供的上下文管理。

6.4 如何调试复杂的工具调用逻辑？

当对话逻辑复杂，工具调用链很长时，看清内部发生了什么很有必要。

• 开启详细日志：claude-toolshed可能内置了日志功能。查看其文档，看如何设置日志级别（如logging.basicConfig(level=logging.DEBUG)）来打印模型请求、响应和工具调用的详细信息。
• 手动打印中间状态：你可以在工具函数内部和agent.run前后打印信息。

  async def main(): agent = Agent(tools=[...]) user_input = “复杂问题...” print(f“用户输入: {user_input}”) # 你可以先看看Agent准备发送给Claude的消息和工具列表 # （这需要查看Agent内部属性，具体取决于框架暴露的接口） response = await agent.run(user_input) print(f“模型最终回复: {response}”) # 查看完整的对话历史 for msg in agent.conversation.messages: # 假设属性名是这个 print(f“{msg[‘role’]}: {msg[‘content’]}”)

• 使用Claude API Playground或Console：有时，直接把Agent构建的请求（包括系统提示、历史消息、工具定义）复制到Anthropic的官方控制台里手动发送，能更直观地看到模型的“思考过程”和原始响应，有助于调试工具选择或参数生成的问题。

6.5 成本控制与Token使用优化

Claude API是按Token收费的。复杂的工具调用和长对话历史会快速消耗Token。

• 监控Token用量：API的响应头或响应体里通常会包含本次请求消耗的输入/输出Token数。定期统计，做到心中有数。
• 精简工具描述：在保证清晰的前提下，工具描述不要太啰嗦。每个Token都要花钱。
• 定期清理对话历史：对于长时间运行的会话，定期让模型总结一下，然后重置历史，只保留总结作为新的系统消息。这能有效控制上下文长度。
• 设置max_tokens参数：在创建Agent时，合理设置max_tokens，防止模型生成过于冗长的回复。

最后，再分享一个我个人的小技巧：在项目初期，可以先用一个简单的、硬编码返回值的工具来测试整个流程是否跑通，然后再去实现复杂的、依赖外部服务的真实逻辑。这能帮你快速隔离问题，确定是工具定义的问题、模型调用的问题，还是外部API集成的问题。claude-toolshed这个框架把复杂的AI交互抽象得非常干净，让你能专注于创造有价值的工具本身，而不是陷在协议和状态管理的泥潭里。