JX ReAct Agent

一个轻量、可扩展的 ReAct judge。Agent 通过模型原生的 tools/tool_calls 检查工作目录，在收集证据后调用 submit_score 提交结构化评分。

它自带文本、图片、PDF、Word、PowerPoint 和 Excel 检查工具，也支持按任务加载 自定义 Python 工具。默认工具均为只读；shell 需要显式开启，不提供编辑工具。

模型或内部网关需要支持 Chat Completions 风格的 function tools。本项目不要求模型 支持 response_format=json_schema。

安装

安装包含文档读取能力的版本：

python3 -m pip install 'jx-react-agent[documents]'

只需要文本工具时可安装核心包：

python3 -m pip install jx-react-agent

RewardKit 集成

安装后，常规 rewardkit 命令会直接识别 judge = "react"。Reward TOML 示例：

[judge]
judge = "react"
model = "openai/doubao-seed-2.1-turbo"
timeout = 300
mode = "batched"

运行方式不变：

rewardkit "$reward_dir" \
  --workspace "$workspace" \
  --output /logs/verifier/reward.json

模型由 LiteLLM 调用，OPENAI_API_KEY、OPENAI_BASE_URL 等标准环境变量继续 有效。也可以只为本 Agent 设置：

export REACT_JUDGE_API_KEY=...
export REACT_JUDGE_API_BASE=...

RewardKit 0.2.0 的 agent registry 只存在于当前进程，而且不会自动扫描第三方 agent entry points。这个 wheel 在 Python 的 site-packages 根目录安装 jx_react_agent_autoload.pth，新进程启动时执行：

import rewardkit_react
rewardkit_react.install()

因此配置被解析前，react backend 已经注册，无需修改 RewardKit 源码或换用另一条 命令。pip 和 rewardkit 必须来自同一个 Python 环境。

随任务目录上传

如果不从 PyPI 安装，可以把整个目录上传后，在评分前运行一次 entry_point.sh：

REWARDKIT_PYTHON="$(command -v python3)"
REWARDKIT_PYTHON="$REWARDKIT_PYTHON" /tests/react-judge/entry_point.sh
rewardkit "$reward_dir" --workspace "$workspace"

bootstrap 会在指定的 Python 环境中构建、安装并验证注册。默认安装 documents extra；远端镜像已经包含依赖或只检查文本时可关闭：

REACT_JUDGE_EXTRAS= \
  REWARDKIT_PYTHON="$REWARDKIT_PYTHON" \
  /tests/react-judge/entry_point.sh

REACT_JUDGE_CACHE_DIR 可调整安装缓存目录。源码、Python 解释器或 extras 变化时会 自动重新安装。

轨迹日志

每次 judge attempt 只保存一个轨迹文件。文件中的 request 是最后一轮发给模型的 完整请求，包含此前累积的 messages、tools 和图片 data URL/base64；response 是 这次请求对应的最终 assistant 响应，包含 submit_score tool call 和评分参数； events 记录模型 tool call、工具 observation 和最终提交。这样可以直接查看完整 请求及最终答案，又不会重复保存每一轮请求或图片。API key 和 Authorization 凭证 不会写入文件。

默认目录为：

/logs/verifier/judge_agents_trajs

文件名形如 trajectory.react.batched-1.<uuid>.json，路径也会写入 RewardKit 的 reward-details.json。可用环境变量覆盖目录：

export REACT_JUDGE_LOG_DIR=/custom/judge/trajs

内置工具

默认暴露以下工具：

• view：查看两层目录或带行号的文本文件窗口。
• list_files：按指定深度列出文件和大小。
• search_files：在文本文件中搜索并返回文件名、行号和匹配行。
• inspect_file：读取文本、图片、PDF、DOCX、PPTX 和 XLSX。
• render_document：把 PDF 页面转成图片；安装 LibreOffice 后也能渲染 PPT/PPTX/DOC/DOCX。
• submit_score：根据本次评分 schema 动态生成，用于提交最终结果。

图片会作为真正的 image_url content block 送入下一轮模型消息。

shell 已内置但默认关闭。需要运行测试或其他命令时显式开启：

export REACT_JUDGE_TOOLS=view,list_files,search_files,inspect_file,render_document,shell

也可以在默认工具基础上开启：

export REACT_JUDGE_ENABLE_SHELL=1

常用限制：

export REACT_JUDGE_MAX_STEPS=20
export REACT_JUDGE_MAX_TOOL_CHARS=40000
export REACT_JUDGE_MAX_IMAGE_BYTES=8388608

自定义工具

工具继承公开的 Tool 类：

from typing import Any

from rewardkit_react.tool import Tool, ToolContext, ToolResult


class CountFiles(Tool):
    name = "count_files"
    description = "Count files in a workspace directory."
    parameters = {
        "type": "object",
        "properties": {"path": {"type": "string", "default": "."}},
        "additionalProperties": False,
    }

    async def execute(
        self, arguments: dict[str, Any], context: ToolContext
    ) -> ToolResult:
        path = context.resolve_workspace_path(arguments.get("path", "."))
        count = sum(child.is_file() for child in path.rglob("*"))
        return ToolResult(text=str(count), metadata={"count": count})


TOOLS = [CountFiles()]

任务本地工具可以直接从文件加载，无需重新构建主包：

export REACT_JUDGE_TOOL_MODULES=/tests/tools/count_files.py
rewardkit /tests/rewards/t1 --workspace /workspace

工具模块可以提供 TOOLS、get_tools() 或 register_tools(registry)。多个路径使用 系统 path separator 或逗号分隔。

可复用工具也可以发布为单独的 wheel：

[project.entry-points."rewardkit_react.tools"]
count_files = "my_rewardkit_tools:CountFiles"

Agent 启动时会通过 importlib.metadata.entry_points() 自动加载这个分组。

文档依赖

Python extra 可以安装 PyMuPDF、Pillow、python-pptx 等依赖，但无法安装 LibreOffice。需要把 PPTX/DOCX 渲染成图片时，应在运行环境中安装 LibreOffice。 只提取文字和结构时，python-pptx 与 python-docx 已经足够。

本地构建和测试：

python3 -m pytest
python3 -m build
python3 -m pip install 'dist/jx_react_agent-0.1.0-py3-none-any.whl[documents]'