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

中文介绍 | UCAgent Online Documentation

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

• 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

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

pip3 install -r requirements.txt

Example: Compile the Adder in examples (requires picker):

make init_Adder
# picker export Adder/Adder.v --rw 1 --sname Adder --tdir output/ -c -w output/Adder/Adder.fst

Default address: http://127.0.0.1:5000

make mcp_Adder  # workspace is set to output directory
# ucagent output/ Adder -s -hm --tui --mcp-server-no-file-tools --no-embed-tools

Please refer to: https://qwenlm.github.io/qwen-code-docs/en/

Since test cases may take longer to run when there are many, it's recommended to set a larger timeout value, such as 300 seconds.

Example ~/.qwen/settings.json configuration:

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

cd output
qwen

Note: Start the Code Agent in the working directory (e.g., output in the example above), otherwise file path mismatch issues may occur.

Input Task Prompt:

Please use the tool RoleInfo to get your role information and basic guidance, then complete the task. Use the tool ReadTextFile to read files. You need to perform file operations in the current working directory and should not go beyond this directory.

Tips:

• Write verification prompts according to task requirements
• When Code Agent stops midway, you can input: Continue, please use tools Check and Complete to determine if all tasks are finished

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

• ctrl+up/down/left/right: Adjust the UI interface layout
• shift+up/down: Adjust the height of the status UI panel
• shift+right: Clear console
• shift+left: Clear input text
• alt + up/down: Scroll the content of message box
• alt + left/right: Scroll the content of console box
• esc: Force refresh the tui/exit scrolling

• White: Pending execution
• Red: Currently executing
• Green: Execution passed
• *: Stage requires mandatory human inspection, AI can continue after entering command hmcheck_pass [msg]
• Yellow: Stage skipped

• 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

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_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 headless mode and the script tests/test_nohead_loop.bash.

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

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

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)

# 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

• 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)

For generating high-quality developer PDF manuals:

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

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

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

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

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

Issues and Pull Requests are welcome!