关键词

AI智能体环境模拟强化学习自动化测试LLM工具调用

项目简介

HUD Python（'hud-python'）是一个功能强大的开源工具包，旨在帮助开发者和研究人员构建、评估和训练AI智能体。它将各种软件和应用封装成标准化的交互式环境，这些环境作为MCP服务器运行，允许LLM客户端通过统一的JSON-RPC协议进行通信，并调用工具、访问资源。无论是在本地开发还是大规模云端运行，HUD Python都能提供全面的支持，包括实时遥测、公共基准测试和内置强化学习管道。

主要功能点

  • MCP环境构建: 轻松将任何软件或应用转换为遵循Model Context Protocol (MCP) 标准的交互式环境。这些环境作为MCP服务器，提供上下文信息和功能给AI智能体。
  • 工具托管与执行: MCP服务器可以注册和执行多种工具，例如浏览器自动化工具（Playwright）、模拟计算机操作工具（键盘、鼠标、截图），以及针对特定应用（如2048游戏、Todo应用、Google表格）的定制工具，使得LLM能够调用外部功能。
  • 资源管理与数据访问: 支持托管和管理各种资源，如环境状态、遥测数据、问题注册表等，并提供标准化的访问能力。
  • Prompt模板定义: 支持定义和渲染Prompt模板，以实现可定制的LLM交互模式。
  • 灵活的部署模式: 支持将MCP环境部署为本地Docker容器、远程云端实例，或直接在Python环境中运行，满足不同场景的需求。
  • 强化学习集成: 内置强化学习管道，支持在任何HUD环境中进行策略训练和基准测试。
  • 实时遥测与评估: 提供实时监控，记录每一次工具调用、观察和奖励，方便调试和性能分析；支持运行公共基准测试和评估智能体表现。

安装步骤

'hud-python' 可以通过 'pip' 命令轻松安装：

  1. 核心安装（包含MCP服务器、遥测、基础环境设计工具）： 
    pip install hud-python
  2. 智能体安装（额外添加AI提供者、数据集支持）： 
    pip install "hud-python[agent]"
  3. CLI工具（可选，推荐使用 'uv' 管理）： 
    uv tool install hud-python
    （如果 'uv' 不可用，可以使用 'pip install --user pipx && pipx install hud-python'）

MCP服务器配置

HUD Python生成的MCP服务器支持多种启动方式。MCP客户端需要知道MCP服务器的启动命令及其参数才能建立连接。以下是常见MCP服务器的配置示例：

  • 本地Python环境运行 (如文本2048游戏) 如果您的MCP服务器环境文件在项目根目录下的 'environments/text_2048/src' 目录中，可以使用以下配置：

    {
  "local_text_2048_server": {
    "command": "python",
    "args": ["-m", "hud_controller.server"],
    "env": {"PYTHONPATH": "environments/text_2048/src"},
    "cwd": "environments/text_2048"
  }
}
    • server name: 'local_text_2048_server' - 给您的MCP服务器实例起一个唯一的名称。
    • command: 'python' - 启动服务器的命令，这里是Python解释器。
    • args: '["-m", "hud_controller.server"]' - 传递给Python解释器的参数，指示运行 'hud_controller.server' 模块。
    • env: '{"PYTHONPATH": "environments/text_2048/src"}' - 服务器运行时的环境变量，确保Python能找到 'hud_controller' 模块。
    • cwd: '"environments/text_2048"' - 服务器启动时的工作目录。

  • 本地Docker容器运行 (如远程浏览器环境) 如果您已构建名为 'hudpython/hud-remote-browser:latest' 的Docker镜像，可以使用以下配置在本地Docker容器中启动MCP服务器：

    {
  "local_remote_browser_server": {
    "command": "docker",
    "args": ["run", "--rm", "-i", "hudpython/hud-remote-browser:latest"]
  }
}
    • server name: 'local_remote_browser_server' - 给您的MCP服务器实例起一个唯一的名称。
    • command: 'docker' - 启动服务器的命令，这里是Docker客户端。
    • args: '["run", "--rm", "-i", "hudpython/hud-remote-browser:latest"]' - 传递给Docker客户端的参数，用于运行指定的Docker镜像。

  • 远程HUD云端MCP服务器 您也可以连接到HUD提供的远程云端MCP服务器。这种情况下，您只需要提供URL和认证信息。

    {
  "hud_cloud_mcp": {
    "url": "https://mcp.hud.so/v3/mcp",
    "headers": {
      "Authorization": "Bearer YOUR_HUD_API_KEY",
      "Mcp-Image": "hudpython/hud-text-2048:v1.2"
    }
  }
}
    • server name: 'hud_cloud_mcp' - 给您的MCP服务器实例起一个唯一的名称。
    • url: 'https://mcp.hud.so/v3/mcp' - HUD云端MCP服务器的URL。
    • headers: 包含认证信息的HTTP头，'YOUR_HUD_API_KEY' 需要替换为您的实际HUD API密钥。'Mcp-Image' 指定要启动的环境Docker镜像。

基本使用方法

安装完成后，您可以：

  1. 启动一个开发环境 (MCP服务器) 使用HUD CLI命令在本地启动一个带热重载的MCP服务器环境。例如，为远程浏览器环境：

    hud dev environments/remote_browser

    这会在后台启动一个MCP服务器，并允许您在代码修改时自动重载。

  2. 构建和分析MCP环境镜像 构建您的环境Docker镜像：

    hud build your-username/your-environment:latest environments/your_environment_path

    分析已构建环境的能力（工具、资源等）：

    hud analyze your-username/your-environment:latest

  3. 使用HUD智能体与环境交互 在您的Python代码中，使用 'hud.clients.MCPClient' 连接到MCP服务器，并使用 'hud.agents' 中提供的智能体（如 'ClaudeAgent' 或 'GenericOpenAIChatAgent'）与环境交互，执行任务：

    import asyncio
import hud
from hud.datasets import Task
from hud.agents import ClaudeAgent
from hud.clients import MCPClient
from hud.settings import settings # 获取您的API Key

async def run_agent_task():
    # MCP服务器配置 (例如，使用HUD云端2048游戏环境)
    mcp_config = {
        "hud": {
            "url": "https://mcp.hud.so/v3/mcp",
            "headers": {
                "Authorization": f"Bearer {settings.api_key}", # 替换为您的HUD API Key
                "Mcp-Image": "hudpython/hud-text-2048:v1.2" # 远程2048游戏环境镜像
            }
        }
    }

    # 定义一个任务，包含Prompt、MCP服务器配置、设置工具和评估工具
    task_data = {
        "prompt": "玩2048游戏，争取达到64点。",
        "mcp_config": mcp_config,
        "setup_tool": {
            "name": "setup",
            "arguments": {"name": "board", "arguments": {"board_size": 4}},
        },
        "evaluate_tool": {
            "name": "evaluate",
            "arguments": {"name": "max_number", "arguments": {"target": 64}},
        },
    }
    task = Task(**task_data)

    # 创建MCP客户端连接MCP服务器
    client = MCPClient(mcp_config=task.mcp_config)

    # 创建一个Claude智能体，并指定允许调用的工具
    agent = ClaudeAgent(
        mcp_client=client,
        model="claude-sonnet-4-20250514", # 您的Claude模型
        allowed_tools=["move"] # 允许智能体使用'move'工具
    )

    with hud.trace("2048游戏智能体演示"):
        try:
            # 运行任务，智能体将自动执行设置、游戏过程和评估
            result = await agent.run(task, max_steps=20)
            print(f"游戏完成！奖励: {result.reward}")
        finally:
            # 关闭MCP客户端连接
            await client.shutdown()

asyncio.run(run_agent_task())

    这段代码将启动一个AI智能体，连接到远程2048游戏MCP服务器，并尝试完成“达到64点”的任务。您可以在HUD平台（'app.hud.so'）上实时查看智能体的行为轨迹和评估结果。

信息

分类

AI与计算

访问项目