agent-runtime-lab

A minimal, testable ReAct-style agent runtime built to make tool execution, bounded runs, and event traces easy to inspect.

一个最小、可测试的 ReAct 风格 Agent Runtime，用清晰代码展示工具调用、超时控制和追加式事件轨迹。

Why this project / 项目目标

• Typed LLM.complete(...) -> ToolCall | FinalAnswer boundary.
• A bounded Agent.run(...) loop with explicit failure events.
• Schema-described tools with a uniform timeout.
• Safe file containment checks and argv-only command execution (shell=False).
• Append-only JSONL traces that can be replayed or evaluated later.
• No API key or network connection required for the demo.

这个项目刻意保持依赖和抽象最少，重点不是做聊天应用，而是展示 Agent Runtime 的核心控制面：模型决策、工具执行、observation、终止条件和可审计 trace。

Architecture / 架构

flowchart LR
    U["User input"] --> A["Agent loop"]
    A --> L["LLM.complete"]
    L -->|ToolCall| R["ToolRegistry"]
    R --> O["Observation"]
    O --> A
    L -->|FinalAnswer| F["Final output"]
    A --> T["JSONL trace"]
    R --> T

Loading

Public interfaces / 公开接口：

• LLM.complete(messages, tools) -> ToolCall | FinalAnswer
• Agent.run(user_text: str) -> str
• ToolRegistry.call(name, arguments, timeout_s) -> str
• JsonlTrace.emit(event_type, **fields)

Trace event types are user, tool_call, observation, final, and error.

Quick start / 快速开始

git clone https://github.com/CChen19/agent-runtime-lab.git
cd agent-runtime-lab
python -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev]'
agent-runtime-lab
python -m pytest

The demo uses MockLLM, a temporary workspace, a safe argv command, and an offline search result. It writes traces/demo.jsonl so the full run remains inspectable.

演示使用确定性的 MockLLM，不需要 API key。运行完成后可以直接查看 traces/demo.jsonl，理解每一步决策和工具结果。

Safety boundaries / 安全边界

• read_file resolves the requested path and verifies it remains below the configured root.
• run_command accepts an argv list and never invokes a shell.
• Every tool call has a timeout, but this lab is not an OS sandbox.
• The runtime records tool failures as observations so the model can recover; terminal loop failures emit an error event.

run_command 仍然会启动本地进程，因此这个项目展示的是安全接口设计，而不是完整的容器或操作系统级隔离。

Tests / 测试

The test suite covers the ReAct sequence, JSONL ordering, unknown tools, path traversal, command failures, timeouts, and maximum-step termination. GitHub Actions runs it on Python 3.10 and 3.12.

License

MIT