使用说明

项目简介

BAML Agents 是一个用于构建强大、可扩展的AI Agent的Python库。它基于 12-Factor Agents 原则，并结合 BAML (Boundary Markup Language) 用于结构化生成，以及 MCP (Model Context Protocol) 用于灵活的工具集成。该库旨在简化AI Agent的开发流程，提供即插即用的工具支持，并确保Agent的架构稳健可靠。

主要功能点

结构化生成: 利用BAML强制LLM生成结构化输出，确保数据格式的准确性和可预测性。
即插即用MCP工具: 通过'pydantic-ai-slim[mcp]' 实现本地 (Python) 和远程 (MCP) 工具的统一接口调用，方便快捷地集成各种工具。
传输协议无关性: 支持进程内Python函数调用和进程外MCP服务器通信 (http/sse 或 stdio)，灵活适应不同的部署环境。
热插拔部署: 无需修改Prompt或模型代码，即可在本地 (inner) 和远程 (outer) 工具实现之间无缝切换。
框架无关性: 轻松替换或升级Agent核心（例如，切换LLM后端或编排框架），无需重写工具接口。
跨项目复用: 在MCP服务器中定义一次工具，即可在多个应用和团队中复用，避免逻辑冗余。
易于扩展: 随着需求增长，可以轻松将工具从本地执行迁移到专用服务或集群，而无需更改客户端代码或模型配置。

安装步骤

确保已安装 Python 3.10 或更高版本。
推荐安装 uv CLI (可选，但推荐用于示例 notebook)。
使用 'pip' 安装 'baml-agents':
```
pip install baml-agents
```
如果需要运行示例 notebook，请参考项目 README 中的 'uv sync --dev' 命令安装开发依赖。

服务器配置 (MCP 功能)

'baml-agents' 本身是一个库，而不是一个可以直接运行的独立 MCP 服务器程序。 它提供了构建 MCP 服务器端组件的能力，你需要将 'baml-agents' 集成到你的 Python 应用中，才能对外提供 MCP 服务。

以下是一个概念性的配置示例，展示了如何使用 'baml-agents' 创建和配置 'McpServers' 实例，以便 MCP 客户端可以与之交互。 你需要编写 Python 代码来启动和运行这个“MCP 服务器端组件”。

假设你已经定义了一些工具 (ToolDefinition)，并希望通过 'McpServers' 将它们暴露给 MCP 客户端。你需要在你的 Python 代码中完成以下配置：

from baml_agents._mcp._mcp_servers import McpServers
from pydantic_ai.mcp import MCPServer
from pydantic_ai.tools import ToolDefinition

# 假设你已经定义了多个 MCPServer 实例 (server1, server2, ...) 和 ToolDefinition 列表 (tools_list)

# 示例 ToolDefinition (你需要根据实际情况定义你的工具)
example_tool = ToolDefinition(
    name="get_current_time",
    description="获取当前时间",
    parameters_json_schema={
        "type": "object",
        "properties": {},
        "required": [],
    },
)

# 示例 MCPServer (你需要根据你的工具实现创建 MCPServer 实例)
class MyMCPServer(MCPServer):
    async def list_tools(self) -> list[ToolDefinition]:
        return [example_tool]  # 返回你的工具列表

    async def call_tool(self, name: str, arguments: dict) -> CallToolResult:
        if name == "get_current_time":
            from datetime import datetime
            return CallToolResult.from_text(str(datetime.now()))
        return CallToolResult.from_text(f"Tool '{name}' not found", isError=True)


server1 = MyMCPServer() # 创建你的 MCPServer 实例
servers = [server1] # 可以配置多个 MCPServer 实例

mcp_servers = McpServers(servers=servers)

# 现在 mcp_servers 实例可以被你的 Agent 或其他 MCP 客户端使用，
# 但你需要自己编写代码来启动和管理这个 mcp_servers 实例的生命周期，
# 并根据你选择的传输协议 (如 stdio, SSE, WebSocket) 将其暴露给客户端。

# 例如，如果使用 stdio，你可能需要创建一个进程来运行包含 mcp_servers 的代码，
# 并将标准输入/输出连接到 MCP 客户端。

MCP 客户端配置示例 (JSON 格式):

以下是一个 MCP 客户端的配置示例，展示了如何配置连接到使用 'baml-agents' 构建的 MCP 服务器端组件。 请注意，这里的 'command' 和 'args' 仅为示例，你需要根据你实际部署和运行 'McpServers' 组件的方式进行配置。 因为 'baml-agents' 是一个库，并没有预设的启动命令，你需要自定义 Python 代码来运行它。

{
  "serverName": "baml-agents-mcp-server",
  "command": "python",  # 假设你使用 Python 运行你的 MCP 服务器端组件
  "args": ["path/to/your/mcp_server_script.py"], #  指向你的 Python 脚本路径
  "transport": "stdio" #  假设你使用 stdio 传输协议
  // 其他配置项，如 serverUrl (如果使用 http/sse 或 websocket)
}

请注意: 上述 'command' 和 'args' 仅为示例。实际使用时，你需要：

编写 Python 代码，使用 'baml-agents' 库中的 'McpServers' 和其他组件，实现你的 MCP 服务器端逻辑 (如工具定义、工具执行等)。
部署和运行你的 Python 代码。这可能涉及到创建 Python 脚本、打包、部署到服务器等步骤，具体取决于你的部署环境和需求。
根据你的部署方式，配置 MCP 客户端的 'command' 和 'args' (或 'serverUrl' 等)，以便客户端能够连接到你运行的 MCP 服务器端组件。

基本使用方法

定义工具 (ToolDefinition): 使用 'pydantic_ai.tools.ToolDefinition' 定义你的工具，包括名称、描述和参数 JSON Schema。
创建 MCPServer 实例: 继承 'pydantic_ai.mcp.MCPServer' 并实现 'list_tools' 和 'call_tool' 方法，以提供你的工具列表和工具调用逻辑。
使用 McpServers 管理多个 MCPServer: 创建 'McpServers' 实例，并将你的 'MCPServer' 实例列表传递给它。
在 BAML Agent 中集成: 使用 'baml_agents' 提供的工具和方法，将 'McpServers' 集成到你的 BAML Agent 中，以便 Agent 可以调用 MCP 工具。
运行和部署: 根据你的需求部署和运行你的 BAML Agent 和 MCP 服务器端组件。

更多详细用法和示例，请参考 'baml-agents' 仓库中的 'notebooks/' 目录。

关键词