UCAgent

System Requirements

• Python 3.11+
• Supported OS: Linux, macOS
• Memory: 4GB+ recommended
• Network: Access to AI model API (OpenAI compatible)
• picker: https://github.com/XS-MLVP/picker

---

2. Install Dependencies

pip3 install -r requirements.txt

requires configuration: OPENAI_API_BASE and other environment variables

Edit a custom file to export environment variables required by ucagent, for example:

1. Initial setup: Install dependencies

make docs-install

Dependencies

• pandoc
• XeLaTeX (TexLive)
• Chinese font "Noto Serif CJK SC"
• Monospace font (default DejaVu Sans Mono)
• Optional filter pandoc-crossref

3. Install and Configure qwen

Please refer to https://qwenlm.github.io/qwen-code-docs/en/ to install qwen-code-cli, then configure the MCP Server as shown below.

Example ~/.qwen/settings.json:

{
    "mcpServers": {
           "unitytest": {
            "httpUrl": "http://localhost:5000/mcp",
            "timeout": 300000
        }
    }
}

Since running test cases may take a long time, it is recommended to set a larger timeout value, for example 300 seconds.

For other Code Agents, please refer to their documentation, e.g., claude code, opencode, copilot-cli, kilo-cli, iflow, etc.

Or, if ucagent is installed, you can directly run ucagent to start master mode

ucagent --as-master-persist --as-master ```

Then visit http://localhost:8800 in your browser.

Docker Startup

docker run -it --rm \
  -e OPENAI_API_BASE=<your_openai_api_base> \
  -e OPENAI_API_KEY=<your_openai_api_key> \
  -e OPENAI_MODEL=<your_openai_model> \
  -p 8800:8800 \
  ghcr.io/xs-mlvp/ucagent:latest ucagent --as-master-persist --as-master

If ghcr.io is not accessible, you can directly replace it with mirror addresses such as ghcr.nju.edu.cn.

After successful startup, visit http://localhost:8800 in your browser.

Documentation Build and Preview (MkDocs)

The Makefile provides documentation-related helper targets (MkDocs + Material):

3. Local generation: Build production version

make docs-build # Generate docs/site directory

PDF Manual Build (Pandoc + XeLaTeX)

For generating high-quality developer PDF manuals:

Quick Start

Usage Flow

First-time use (install dependencies):

make docs-install    # Install mkdocs and material theme dependencies

Daily development (preview documentation):

```bash make docs-serve # Start local server, visit http://127.0.0.1:8030

Complete Workflow Example

```bash

Examples

make pdf
make MONO="JetBrains Mono" pdf      # Override monospace font
make TWOSIDE=1 pdf                   # Two-sided layout (adds -twoside to filename)
make pdf-clean

5. How to Improve Verification Quality (Optional)

By default, UCAgent only enables the internal Python Checker for stage checking, which is heuristic. If you need verification quality improvement, you can enable LLM stage checking. If you need to reach "delivery level" quality, you further need to enable Human stage checking.

1. Enable LLM stage checking

1. Enable human stage checking

Default stage checking order: Python Checker -> LLM -> Human

---

Then load the environment variables

source ~/.ucagent_env

#### 2. Start UCAgent Master

4. Cleanup (optional)

make docs-clean # Delete docs/site directory ```

Interact via Web Interface

UCAgent provides Master mode, based on which you can perform centralized Agent management, create tasks, view status, use online terminals, and other operations through the web interface.

export OPENAI_API_BASE=<your_openai_api_base>

export OPENAI_API_KEY=<your_openai_api_key>

Frequently Asked Questions (FAQ)

Q: How to configure different AI models?

A: Modify the openai.model_name field in config.yaml, which supports any OpenAI-compatible API. See Configuration Documentation.

Q: What to do when errors occur during verification?

A: Use Ctrl+C to enter interactive mode, check current status with status, and use help to get debugging commands.

Q: MCP server cannot connect?

A: Check if the port is occupied, verify firewall settings, and you can specify a different port with --mcp-server-port.

Q: Why is there information from the last execution?

A: UCAgent by default looks for the .ucagent/ucagent_info.json file in the working directory to load previous execution information and continue. If you don't need history, delete this file or use the --no-history parameter to ignore loading history.

Q: How to run long-duration verification?

A: Please refer to CodeAgent's custom backend mode examples/CustomBackend/README.md.

Q: Can verification stages be customized?

A: Yes, see Customization Documentation.

Q: How to add custom tools?

A: Create a new tool class in the ucagent/tools/ directory, inherit from the UCTool base class, and load it with the --ex-tools parameter. See Tool List Documentation.

🔍 More Questions: Check the complete FAQ Documentation

---