关键词

LLM工具开发AI Agent工具Python函数调用语言模型集成自动化脚本

项目简介

Claude Code Python SDK 是一款专为Python开发者设计的工具包，旨在帮助您将自定义Python函数无缝集成到基于Model Context Protocol (MCP) 的LLM应用中。该SDK的核心功能之一是允许您在Python应用内部定义和运行“内嵌式MCP服务器”，这些服务器以标准化的方式向LLM（例如Claude Code）提供工具（Tools）。与传统的需要独立进程的MCP服务器不同，内嵌式服务器直接在您的Python应用进程中运行，显著提高了性能、简化了部署和调试流程。

主要功能点

  • 内嵌式MCP工具托管: 允许您使用简单的Python装饰器 ('@tool') 定义自定义函数，并将其注册为LLM可调用的工具。这些工具直接在您的Python应用进程中运行，无需额外的进程管理。
  • MCP协议兼容: 您的自定义工具将通过标准的MCP协议（JSON-RPC）与LLM客户端通信，确保互操作性。
  • 高性能: 由于工具运行在同一进程中，消除了进程间通信（IPC）的开销，带来更快的工具执行速度。
  • 简化部署与调试: 将MCP工具服务器集成到您的Python应用中，减少了部署的复杂性，并使得在同一个环境中调试LLM与自定义工具的交互变得更加容易。
  • 上下文交互: 提供丰富的客户端功能，支持LLM与自定义工具之间的双向、交互式会话，包括发送消息、接收响应、中断操作以及动态修改会话选项。

安装步骤

# 确保您已安装Python 3.10+ 和 Node.js
# 安装Claude Code CLI（如果尚未安装）
npm install -g @anthropic-ai/claude-code

# 安装Claude Agent SDK for Python
pip install claude-agent-sdk

服务器配置

此SDK帮助您在Python应用内部创建MCP服务器。MCP客户端（例如Claude Code CLI或其他兼容MCP的LLM客户端）需要知道如何连接到这些服务器。当您使用'ClaudeSDKClient'或'query'函数并配置'mcp_servers'选项时，SDK会在内部管理这些服务器的启动和通信。

MCP客户端通常通过以下JSON格式配置来识别和连接MCP服务器：

{
  "mcpServers": {
    "your-server-name": {
      "type": "sdk",
      "name": "your-server-name",
      // "instance" 字段由SDK内部管理，不会暴露给MCP客户端作为配置项。
      // 对于外部MCP客户端，此SDK创建的内嵌式服务器由SDK在内部抽象为"sdk"类型，
      // 客户端无需直接提供 command 或 args，SDK会在内部桥接LLM的工具调用请求
      // 到您定义的Python函数。
    },
    // 如果您有外部MCP服务器（例如用Node.js或Rust实现），可以这样配置：
    "external-server": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "your_external_mcp_server_module"]
    }
  }
}

配置参数说明（供MCP客户端开发者参考）:

  • 'your-server-name'：您在'create_sdk_mcp_server'函数中定义的服务器名称，LLM将使用此名称引用您的工具集。
  • 'type': 对于使用此SDK创建的内嵌式MCP服务器，其类型固定为 '"sdk"'。
  • 'name': 服务器的唯一标识符，与您在'create_sdk_mcp_server'中传入的'name'参数一致。
  • 注意: 对于类型为'"sdk"'的MCP服务器，实际的工具逻辑直接在Python应用进程中运行，MCP客户端无需提供'command'或'args'来启动一个单独的进程。SDK负责内部的请求路由和响应处理。

基本使用方法

以下是如何使用此SDK定义一个计算器工具服务器，并让LLM能够调用这些工具：

  1. 定义自定义工具: 使用 '@tool' 装饰器将普通Python异步函数转换为LLM可调用的工具。

    from claude_agent_sdk import tool
from typing import Any

@tool("add", "将两个数字相加", {"a": float, "b": float})
async def add_numbers(args: dict[str, Any]) -> dict[str, Any]:
    result = args["a"] + args["b"]
    return {"content": [{"type": "text", "text": f"{args['a']} + {args['b']} = {result}"}]}

@tool("subtract", "从一个数字中减去另一个数字", {"a": float, "b": float})
async def subtract_numbers(args: dict[str, Any]) -> dict[str, Any]:
    result = args["a"] - args["b"]
    return {"content": [{"type": "text", "text": f"{args['a']} - {args['b']} = {result}"}]}

  2. 创建内嵌式MCP服务器: 将定义的工具列表传递给 'create_sdk_mcp_server' 函数，创建一个MCP服务器实例。

    from claude_agent_sdk import create_sdk_mcp_server

calculator_server = create_sdk_mcp_server(
    name="calculator",
    version="1.0.0",
    tools=[add_numbers, subtract_numbers]
)

  3. 配置并使用'ClaudeSDKClient': 在'ClaudeAgentOptions'中将您的MCP服务器配置传递给'mcp_servers'参数，并通过'allowed_tools'明确允许LLM调用这些工具（工具名称格式为'mcp__<server_name>__<tool_name>'）。然后使用'ClaudeSDKClient'进行交互。

    import asyncio
from claude_agent_sdk import ClaudeAgentOptions, ClaudeSDKClient, AssistantMessage, TextBlock, ResultMessage, ToolUseBlock

async def main():
    options = ClaudeAgentOptions(
        mcp_servers={"my_calc": calculator_server},
        allowed_tools=["mcp__my_calc__add", "mcp__my_calc__subtract"]
    )

    async with ClaudeSDKClient(options=options) as client:
        print("用户: 计算 15 + 27")
        await client.query("请计算 15 + 27")

        async for message in client.receive_response():
            if isinstance(message, AssistantMessage):
                for block in message.content:
                    if isinstance(block, TextBlock):
                        print(f"Claude: {block.text}")
                    elif isinstance(block, ToolUseBlock):
                        print(f"Claude 调用工具: {block.name}，输入: {block.input}")
            elif isinstance(message, ResultMessage):
                print("结果结束。")

        print("\n用户: 现在从结果中减去 10")
        await client.query("现在从刚才的结果中减去 10") # Claude会记住上下文

        async for message in client.receive_response():
            if isinstance(message, AssistantMessage):
                for block in message.content:
                    if isinstance(block, TextBlock):
                        print(f"Claude: {block.text}")
                    elif isinstance(block, ToolUseBlock):
                        print(f"Claude 调用工具: {block.name}，输入: {block.input}")
            elif isinstance(message, ResultMessage):
                print("结果结束。")

if __name__ == "__main__":
    asyncio.run(main())

注意：'mcp__<server_name>__<tool_name>'是Claude Code识别MCP服务器中特定工具的命名约定。

信息

分类

开发者工具

访问项目