UCAgent (UnityChip Verification Agent)

AI-powered automated UT verification agent based on large language models

中文介绍 | UCAgent Online Documentation

Introduction

UCAgent is an automated hardware verification AI agent based on large language models, focusing on Unit Test verification for chip design. It automatically analyzes hardware designs, generates test cases, executes verification tasks, and produces test reports through AI technology, thereby improving verification efficiency.

Key Features:

• Automated chip verification workflow
• Support for functional coverage and code coverage analysis
• Consistency assurance among documentation, code, and reports
• Deep collaboration with mainstream Code Agents (OpenHands, Copilot, Claude Code, Gemini-CLI, Qwen-Code, etc.) via MCP protocol
• Three intelligent interaction modes (standard, enhanced, advanced)

For more details, please refer to UCAgent Online Documentation

Tip

The slide, code and environment for UCAgent workshop presented at RISC-V Summit Europe 2026 are available at the official repository: https://github.com/XS-MLVP/tutorial-records

---

System Requirements

• Python 3.11+, if the latest version of Python encounters dependency issues, please downgrade
• Supported OS: Linux, macOS
• Memory: 4GB+ recommended
• Network: Access to AI model API (OpenAI compatible)
• picker: https://github.com/XS-MLVP/picker

---

Quick Start

1. Clone the Repository

git clone https://github.com/XS-MLVP/UCAgent.git
cd UCAgent

2. Install Dependencies

pip3 install -r requirements.txt

3. Install OpenCode

Please refer to https://opencode.ai/ to install opencode. For other Code Agents, please refer to their documentation, e.g., claude code, copilot-cli, kilo-cli, iflow, qwen-code, etc.

4. Configure LLM API

export OPENAI_MODEL=<model_name>              # e.g., glm-5.3-flash
export OPENAI_API_KEY=<your_key>              # API key
export OPENAI_API_BASE=<base_url>             # e.g., http://my_base_url/v1
export OPENAI_CONTEXT_SIZE=<max_context_size> # optional, e.g., 819200 (800k context)
export OPENAI_OUTPUT_SIZE=<max_output_size>   # optional, e.g., 131072 (128k max output)

You can also write the above content into ~/.ucagent_env, and then load it:

source ~/.ucagent_env

5. Start Verification

Taking Adder in examples as an illustration.

# backend can be: langchain, claude, opencode, copilot, kilo, qwen, iflow, etc.
make mcp_Adder ARGS="--loop --backend=opencode"

This command creates the workspace, starts the MCP Server, and automatically invokes opencode to run the verification task; the model used by opencode is the LLM API configured in the previous step.

For supported backends, please refer to the backend section in ucagent/setting.yaml.

💡 More Usage Methods: Besides the MCP collaboration mode used in this quick start, UCAgent also supports direct LLM integration, human-machine collaboration, and other modes. See Usage Documentation

6. 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

2. Enable human stage checking

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

7. Verification Delivery

If the verification results need to be delivered, it is recommended to:

• Generate a high-quality README.md based on the Spec and verification requirements via Vibe coding
• Based on the Spec and RTL source code, analyze whether to enable reference model and Mock component support (NEED_REF_MODEL=true, IGNORE_MOCK_COMPONENT=false)
• Run the default workflow until no more bugs are found; if a reported bug is a false positive, fix the Spec document
• Run the formal workflow until no more bugs are found (e.g., make formal_mcp_Adder ARGS="--loop --backend=opencode")
• Run the coverage workflow to raise RTL coverage above 99%

---

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.

Local Startup

1. Configure Environment Variables

The environment variables are the same as the Configure LLM API step in Quick Start (OPENAI_MODEL, OPENAI_API_KEY, OPENAI_API_BASE, etc.). If they are persisted in ~/.ucagent_env, load it before startup:

source ~/.ucagent_env

2. Start UCAgent Master

make as_master_persist
# 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

Pass the same LLM API environment variables via -e when starting the container:

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

Alternatively, use Docker's --env-file to provide the environment variables from a single file instead of multiple -e flags:

docker run -it --rm \
  --env-file ~/.ucagent_docker_env \
  -p 8800:8800 \
  ghcr.io/xs-mlvp/ucagent:latest ucagent --as-master-persist --as-master

An example ~/.ucagent_docker_env is shown below. Unlike ~/.ucagent_env, do not use export here, and # comments must be on their own line (an inline # becomes part of the value):

# Model name, e.g., glm-5.3-flash
OPENAI_MODEL=<model_name>
# API key
OPENAI_API_KEY=<your_key>
# API base URL, e.g., http://my_base_url/v1
OPENAI_API_BASE=<base_url>
# Optional: context window size (tokens), e.g., 819200 (800k context)
OPENAI_CONTEXT_SIZE=<max_context_size>
# Optional: max output size per response (tokens), e.g., 131072 (128k max output)
OPENAI_OUTPUT_SIZE=<max_output_size>

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.

Basic Operations

1. In the web interface, click the + button (or launch button) to create a new task.
2. In the Agent list, click the API button to connect to the control page of a specific Agent.
3. In the Agent control page, click the web terminal button to open the online terminal.
4. Start ucagent locally and connect to an existing Master service via the --master parameter.

More Features

1. Launch page: create workspace, upload/import files, parse modules, compile, and preview launch command.
2. Task page: filter, paginate, inspect task details/logs, and stop/delete managed tasks.
3. Enhanced Agent page: stage multi-select and bulk toggles (HM/Skip/LFail/LPass), plus stage artifact content/diff review.
4. Unified proxy access: Master proxies cmd/terminal/web-console paths for both task and agent entries.
5. Improved Web Terminal: multiple terminal sessions across different URLs.

📖 Detailed Operations: See TUI Usage Documentation

---

Basic Operations

TUI Shortcuts

• ctrl+up/down/left/right: Adjust layout (Console height / Mission panel width)
• ctrl+h/j/k/l: Vim-style layout adjustment (equivalent to ctrl+left/down/up/right)
• ctrl+c: Cancel running command; exit TUI if no command is running
• ctrl+t: Open theme picker
• f1: Show/hide keyboard shortcuts help panel
• shift+right: Clear console output
• shift+left: Clear input text
• tab: Command completion; press Tab repeatedly to cycle through candidates
• pageup/pagedown: Page through Console output
• esc: Exit scrolling/paging/help panel, or clear input

Stage Color Indicators

• White: Pending execution
• Red: Currently executing
• Green: Execution passed
• *:
  • Blue indicates LLM Fail checking is enabled for this stage, providing modification suggestions when stage check fails more than 3 times
  • Green indicates LLM Pass checking is enabled for this stage, verifying if stage task requirements are met upon completion
  • Red indicates this stage requires mandatory human inspection, AI can continue after entering command hmcheck_pass [msg]
• Yellow: Stage skipped

Common Interactive Commands

• q: Exit TUI (or exit UCAgent)
• tui: Enter TUI
• tab: Command completion
• tool_list: List all available tools
• help: View all command help
• loop [prompt]: Continue current task

📖 Detailed Operations: See TUI Usage Documentation

---

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

---

Documentation Build and Preview (MkDocs)

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

Target	Purpose	Use Case
make docs-help	Show documentation-related target help	View available commands
make docs-install	Install build dependencies from docs/requirements-docs.txt	First use or dependency updates
make docs-serve	Local preview (default 127.0.0.1:8030)	Develop and preview docs
make docs-build	Build static site to docs/site	Generate production version
make docs-clean	Delete docs/site directory	Clean build artifacts

Usage Flow

First-time use (install dependencies):

make docs-install    # Install mkdocs and material theme dependencies

Daily development (preview documentation):

make docs-serve      # Start local server, visit http://127.0.0.1:8030
# Browser will auto-refresh after modifying docs

Local generation and viewing (build production version):

make docs-build      # Generate static website to docs/site directory
# Open docs/site/index.html in local browser
make docs-clean      # Clean build artifacts (optional)

Complete Workflow Example

# 1. Initial setup: Install dependencies
make docs-install

# 2. Development phase: Preview docs (can be repeated)
make docs-serve      # Visit http://127.0.0.1:8030 in browser
# ...edit documentation...
# Press Ctrl+C to stop service

# 3. Local generation: Build production version
make docs-build      # Generate docs/site directory
# Open docs/site/index.html in local browser

# 4. Cleanup (optional)
make docs-clean      # Delete docs/site directory

Notes

• Port and address are currently hardcoded in docs/Makefile, can be modified as needed.
• make docs-serve is suitable for development use, supports hot reload
• make docs-build generates complete static website files, output to docs/site directory, can preview final effect locally (open docs/site/index.html)

---

PDF Manual Build (Pandoc + XeLaTeX)

For generating high-quality developer PDF manuals:

Target	Purpose
make pdf	Generate ucagent-doc.pdf from ordered Markdown sources
make pdf-one	Equivalent to pdf (convenient for CI calls)
make pdf-clean	Clean generated PDF and LaTeX temporary files

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

Dependencies

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

Custom Variables

• MONO Change monospace font
• TWOSIDE Enable two-sided mode when non-empty

Common Issues

• Missing fonts: Install CJK font packages (e.g., fonts-noto-cjk).
• LaTeX errors: Ensure complete XeLaTeX suite is installed (use texlive-full if necessary).
• Missing cross-references: Confirm pandoc-crossref is in PATH.

Output: ucagent-doc.pdf can be distributed with version releases.

---

Get More Help

• 📚 UCAgent Online Documentation
• 🚀 Quick Start Guide
• 🔧 Custom Configuration
• 🛠️ Tool List
• 💬 GitHub Issues

Contributing

Issues and Pull Requests are welcome!