Usage

• 1: MCP Integration Mode (Recommended)
• 2: Direct Mode
• 3: Human-AI Collaborative Verification
• 4: Options
• 5: TUI
• 6: FAQ

1 - MCP Integration Mode (Recommended)

MCP Integration (Recommended) Integrate Code Agent

Collaborate with external CLI via MCP. This mode works with all LLM clients that support MCP-Server invocation, such as Cherry Studio, Claude Code, Gemini-CLI, VS Code Copilot, Qwen Code, etc. Daily usage is to use make directly; for detailed commands see Quick Start, or check the root Makefile.

• Prepare RTL and the corresponding SPEC docs under examples/{dut}. {dut} is the module name; if it is Adder, the directory is examples/Adder.

• Package RTL, place docs, and start MCP server: make mcp_{dut} (e.g., make mcp_Adder).

• Configure your MCP client:

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

• Start the client: for Qwen Code, run qwen under UCAgent/output, then input the prompt.

• prompt:

  Please get your role and basic guidance via RoleInfo, then complete the task. Use ReadTextFile to read files. Operate only within the current working directory; do not go outside it.

2 - Direct Mode

Direct Usage

Based on local CLI and LLM. Requires an OpenAI‑compatible API and an embedding model API.

Configure via Environment Variables (Recommended)

Config file content:

# OpenAI-compatible API config
openai:
  model_name: "$(OPENAI_MODEL: Qwen/Qwen3-Coder-30B-A3B-Instruct)" # model name
  openai_api_key: "$(OPENAI_API_KEY: YOUR_API_KEY)" # API key
  openai_api_base: "$(OPENAI_API_BASE: http://10.156.154.242:8000/v1)" # API base URL
# Embedding model config
# Used for doc search and memory features; can be disabled via --no-embed-tools
embed:
  model_name: "$(EMBED_MODEL: Qwen/Qwen3-Embedding-0.6B)" # embedding model name
  openai_api_key: "$(EMBED_OPENAI_API_KEY: YOUR_API_KEY)" # embedding API key
  openai_api_base: "$(EMBED_OPENAI_API_BASE: http://10.156.154.242:8001/v1)" # embedding API URL
  dims: 4096 # embedding dimension

UCAgent config supports Bash‑style env placeholders: $(VAR: default). On load, it will be replaced with the current env var VAR; if unset, the default is used.

• For example, in the built‑in vagent/setting.yaml:
  • openai.model_name: "$(OPENAI_MODEL: <your_chat_model_name>)"
  • openai.openai_api_key: "$(OPENAI_API_KEY: [your_api_key])"
  • openai.openai_api_base: "$(OPENAI_API_BASE: http://<your_chat_model_url>/v1)"
  • embed.model_name: "$(EMBED_MODEL: <your_embedding_model_name>)"
  • Also supports other providers: model_type supports openai, anthropic, google_genai (see vagent/setting.yaml).

You can switch models and endpoints just by exporting env vars, without editing the config file.

Example: set chat model and endpoint

# Specify chat model (OpenAI‑compatible)
export OPENAI_MODEL='Qwen/Qwen3-Coder-30B-A3B-Instruct'

# Specify API Key and Base (fill in according to your provider)
export OPENAI_API_KEY='your_api_key'
export OPENAI_API_BASE='https://your-openai-compatible-endpoint/v1'

# Optional: embedding model (if using retrieval/memory features)
export EMBED_MODEL='text-embedding-3-large'
export EMBED_OPENAI_API_KEY="$OPENAI_API_KEY"
export EMBED_OPENAI_API_BASE="$OPENAI_API_BASE"

Then start UCAgent as described earlier. To persist, append the above exports to your default shell startup file (e.g., bash: ~/.bashrc, zsh: ~/.zshrc, fish: ~/.config/fish/config.fish), then reopen terminal or source it manually.

Configure via config.yaml

• Create and edit config.yaml at the project root to configure the AI model and embedding model:

# OpenAI-compatible API config
openai:
  openai_api_base: <your_openai_api_base_url> # API base URL
  model_name: <your_model_name> # model name, e.g., gpt-4o-mini
  openai_api_key: <your_openai_api_key> # API key

# Embedding model config
# Used for doc search and memory features; can be disabled via --no-embed-tools
embed:
  model_name: <your_embed_model_name> # embedding model name
  openai_api_base: <your_openai_api_base_url> # embedding API URL
  openai_api_key: <your_api_key> # embedding API key
  dims: <your_embed_model_dims> # embedding dimension, e.g., 1536

Start

• Step 1 is the same as in MCP mode: prepare RTL and the corresponding SPEC docs under examples/{dut}. {dut} is the module name; if it is Adder, the directory is examples/Adder.
• Step 2 differs: package RTL, put the docs into the workspace, and start UCAgent TUI: make test_{dut}, where {dut} is the module. For Adder, run make test_Adder (see all targets in Makefile). This will:
  • Copy files from examples/{dut} to output/{dut} (.v/.sv/.md/.py, etc.)
  • Run python3 ucagent.py output/ {dut} --config config.yaml -s -hm --tui -l
  • Start UCAgent with TUI and automatically enter the loop

Tip: verification artifacts are written to output/unity_test/ by default; to change it, use the CLI --output option to set the directory name.

Direct CLI (without Makefile):

• Not installed (run inside project):
  • python3 ucagent.py output/ Adder --config config.yaml -s -hm --tui -l
• Installed as command:
  • ucagent output/ Adder --config config.yaml -s -hm --tui -l

Options aligned with vagent/cli.py:

• workspace: workspace directory (here output/)
• dut: DUT name (workspace subdirectory name, e.g., Adder)
• Common options:
  • --tui start terminal UI
  • -l/--loop --loop-msg "..." enter loop immediately after start and inject a hint
  • -s/--stream-output stream output
  • -hm/--human human‑intervention mode (can pause between stages)
  • --no-embed-tools if retrieval/memory tools are not needed
  • --skip/--unskip skip/unskip stages (can be passed multiple times)

TUI Quick Reference (Direct Mode)

• List tools: tool_list
• Stage check: tool_invoke Check timeout=0
• View logs: tool_invoke StdCheck lines=-1 (‑1 for all lines)
• Stop check: tool_invoke KillCheck
• Finish stage: tool_invoke Complete timeout=0
• Run tests:
  • Full: tool_invoke RunTestCases target='' timeout=0
  • Single test function: tool_invoke RunTestCases target='tests/test_checker.py::test_run' timeout=120 return_line_coverage=True
  • Filter: tool_invoke RunTestCases target='-k add or mul'
• Jump stage: tool_invoke GoToStage index=2 (index starts from 0)
• Continue: loop 继续修复 ALU754 的未命中分支并重试用例

Recommended minimal write permission (only allow generation under verification artifacts):

• Allow only unity_test/ and unity_test/tests/ to be writable:
  • add_un_write_path *
  • del_un_write_path unity_test
  • del_un_write_path unity_test/tests

FAQ and Tips

• Check stuck/no output:
  • First run tool_invoke StdCheck lines=-1 to view all logs; if needed tool_invoke KillCheck; fix then retry tool_invoke Check.
• Tool name not found:
  • Run tool_list to confirm available tools; if missing, check whether in TUI mode and whether embedding tools were disabled (usually unrelated).
• Artifact location:
  • By default under workspace/output_dir, i.e., output/unity_test/ for the examples on this page.

Related Docs

• Full human‑AI collaboration flow and examples: see Human‑AI Collaboration
• MCP integration (e.g., gemini‑cli / qwen code): see MCP Integration Mode
• TUI interface and operations in detail: see TUI

3 - Human-AI Collaborative Verification

UCAgent supports human‑AI collaborative verification. You can pause AI execution, intervene manually, then continue AI execution. This mode applies to scenarios needing fine control or complex decisions.

Collaboration Flow:

1. Pause AI execution:
   • Direct LLM access mode: press Ctrl+C to pause.
   • Code Agent collaboration mode: pause according to the agent’s method (e.g. Gemini-cli uses Esc).
2. Human intervention:
   • Manually edit files, test cases or configuration.
   • Use interactive commands for debugging or adjustment.
3. Stage control:
   • Use tool_invoke Check to check current stage status.
   • Use tool_invoke Complete to mark stage complete and enter next stage.
4. Continue execution:
   • Use loop [prompt] to continue AI execution and optionally provide extra prompt info.
   • In Code Agent mode, input prompts via the agent console.
5. Permission management:
   • Use add_un_write_path, del_un_write_path to set file write permissions, controlling whether AI can edit specific files.
   • Applies to direct LLM access or forced use of UCAgent file tools.

4 - Options

Arguments and Options

Use UCAgent:

ucagent <workspace> <dut_name> {options}

Inputs

• workspace: working directory:
  • workspace/<DUT_DIR>: device under test (DUT), i.e., the Python package <DUT_DIR> exported by the picker; e.g., Adder
  • workspace/<DUT_DIR>/README.md: natural‑language description of verification requirements and goals for this DUT
  • workspace/<DUT_DIR>/*.md: other reference documents
  • workspace/<DUT_DIR>/*.v/sv/scala: source files used for bug analysis
  • Other verification‑related files (e.g., provided test cases, requirement specs, etc.)
• dut_name: the name of the DUT, i.e., <DUT_DIR>, for example: Adder

Outputs

• workspace: working directory:
  • workspace/Guide_Doc: guidance and documents followed during the verification process
  • workspace/uc_test_report: generated Toffee‑test report
  • workspace/unity_test/tests: auto‑generated test cases
  • workspace/*.md: generated docs including bug analysis, checkpoints, verification plan, and conclusion

See also the detailed outputs in Introduction.

Positional Arguments

Execution and Interaction

Config and Templates

Planning and ToDo

ToDo Tools Overview & Examples

Note: ToDo tools are for enhancing model planning; users can define the model’s ToDo list. This feature requires strong model capability and is disabled by default.

Enabling: use --use-todo-tools in any mode; or in standard mode use --force-todo to force enable and include ToDo info in each round.

Conventions and limits: step indices are 1‑based; number of steps must be 2–20; length of notes and each step text ≤ 100; exceeding limits will be rejected with an error string.

Tool overview

Invocation examples (MCP/internal tool call, JSON args):

{
	"tool": "CreateToDo",
	"args": {
		"task_description": "Complete verification closure for Adder core functions",
		"steps": [
			"Read README and spec, summarize features",
			"Define checkpoints and pass criteria",
			"Generate initial unit tests",
			"Run and fix failing tests",
			"Fill coverage and output report"
		]
	}
}

{
	"tool": "CompleteToDoSteps",
	"args": { "completed_steps": [1, 2], "notes": "Initial issues resolved, ready to add tests" }
}

{ "tool": "UndoToDoSteps", "args": { "steps": [2], "notes": "Step 2 needs checkpoint tweaks" } }

{ "tool": "ResetToDo", "args": {} }

{ "tool": "GetToDoSummary", "args": {} }

{ "tool": "ToDoState", "args": {} }

External and Embedding Tools

Logging

MCP Server

Stage Control and Safety

Version and Check

Example

python3 ucagent.py ./output Adder \
	\
	-s \
	-hm \
	-im enhanced \
	--tui \
	-l \
	--loop-msg 'start verification' \
	--seed 12345 \
	--sys-tips '按规范完成Adder的验证' \
	\
	--config config.yaml \
	--template-dir ./templates \
	--template-overwrite \
	--output unity_test \
	--override 'conversation_summary.max_tokens=16384,conversation_summary.max_summary_tokens=2048,conversation_summary.use_uc_mode=True,lang="zh",openai.model_name="gpt-4o-mini"' \
	--gen-instruct-file GEMINI.md \
	--guid-doc-path ./output/Guide_Doc \
	\
	--use-todo-tools \
	\
	--ex-tools 'SqThink,AnotherTool' \
	--no-embed-tools \
	\
	--log \
	--log-file ./output/ucagent.log \
	--msg-file ./output/ucagent.msg \
	\
	--mcp-server-no-file-tools \
	--mcp-server-host 127.0.0.1 \
	--mcp-server-port 5000 \
	\
	--force-stage-index 2 \
	--skip 5 --skip 7 \
	--unskip 6 \
	--nw ./output/Adder ./output/unity_test

• Positional arguments
  • ./output: workspace working directory
  • Adder: dut subdirectory name
• Execution and interaction
  • -s: stream output
  • -hm: human intervention on start
  • -im enhanced: enhanced interaction mode (with planning and memory)
  • –tui: enable TUI
  • -l: enter loop immediately after start
  • –loop/–loop-msg: inject first message when entering loop
  • –seed 12345: fix random seed
  • –sys-tips: custom system prompt
• Config and templates
  • –config config.yaml: load project config from config.yaml
  • –template-dir ./templates: set template directory to ./templates
  • –template-overwrite: allow overwrite when rendering templates
  • –output unity_test: output directory name unity_test
  • –override ‘…’: override config keys (dot‑path=value, multiple comma‑separated; string values require inner quotes and wrap the whole with single quotes); the example sets conversation summary limits, enables trimming, sets doc language to Chinese, and model name to gpt‑4o‑mini
  • -gif/–gen-instruct-file GEMINI.md: generate external collaboration guide at <workspace>/GEMINI.md
  • –guid-doc-path ./output/Guide_Doc: customize Guide_Doc directory as ./output/Guide_Doc
• Planning and ToDo
  • –use-todo-tools: enable ToDo tools and force attaching ToDo info
• External and embedding tools
  • –ex-tools ‘SqThink,AnotherTool’: enable external tools SqThink,AnotherTool
  • –no-embed-tools: disable built‑in retrieval/memory tools
• Logging
  • –log: enable log file
  • –log-file ./output/ucagent.log: set log output file to ./output/ucagent.log
  • –msg-file ./output/ucagent.msg: set message log file to ./output/ucagent.msg
• MCP Server
  • –mcp-server-no-file-tools: start MCP (without file tools)
  • –mcp-server-host: server listen address 127.0.0.1
  • –mcp-server-port: server listen port 5000
• Stage control and safety
  • –force-stage-index 2: start from stage index 2
  • –skip 5 –skip 7: skip stage 5 and stage 7
  • –unskip 7: unskip stage 7
  • –nw ./output/Adder ./output/unity_test: restrict writable paths to ./output/Adder and ./output/unity_test
• Notes
  • –check and –version exit immediately, not combined with run
  • –mcp-server and –mcp-server-no-file-tools are mutually exclusive; here we choose the latter. Path arguments (e.g., –template-dir/–guid-doc-path/–nw) must exist, otherwise an error occurs
  • String values in –override must be quoted, and wrap the whole argument in single quotes to prevent the shell from consuming the inner quotes (the example already does this)

5 - TUI

TUI (UI & Operations)

UCAgent provides a urwid‑based terminal UI (TUI) for interactively observing task progress, message stream, and console output locally, and for entering commands directly (e.g., enter/exit loop, switch modes, run debug commands, etc.).

Layout

• Mission panel (left)

  • Stage list: show current task stages (index, title, failures, elapsed). Color meanings:
    • Green: completed stage
    • Red: current stage
    • Yellow: skipped stage (shows “skipped”)
  • Changed Files: recently modified files (with mtime and relative time, e.g., “3m ago”). Newer files are highlighted in green.
  • Tools Call: tool call status and counters. Busy tools are highlighted in yellow (e.g., SqThink(2)).
  • Daemon Commands: demo commands running in background (with start time and elapsed).

• Status panel (top right)

  • Shows API and agent status summary, and current panel size parameters (useful when adjusting layout).

• Messages panel (upper middle right)

  • Live message stream (model replies, tool output, system tips).
  • Supports focus and scrolling; the title shows “current/total” position, e.g., Messages (123/456).

• Console (bottom)

  • Output: command and system output area with paging.
  • Input: command input line (default prompt “(UnityChip) “). Provides history, completion, and busy hints.

Tip: the UI auto‑refreshes every second (does not affect input). When messages or output are long, it enters paging or manual scrolling.

Shortcuts

• Enter: execute current input; if empty, repeat the last command; q/Q/exit/quit to exit TUI.
• Esc:
  • If browsing Messages history, exit scrolling and return to the end;
  • If Output is in paging view, exit paging;
  • Otherwise focus the bottom input box.
• Tab: command completion; press Tab again to show more candidates in batches.
• Shift+Right: clear Console Output.
• Shift+Up / Shift+Down: move focus up/down in Messages (browse history).
• Ctrl+Up / Ctrl+Down: increase/decrease Console output area height.
• Ctrl+Left / Ctrl+Right: decrease/increase Mission panel width.
• Shift+Up / Shift+Down (another path): adjust Status panel height (min 3, max 100).
• Up / Down:
  • If Output is in paging mode, Up/Down scrolls pages;
  • Otherwise navigate command history (put the command into input line for editing and Enter to run).

Paging mode hint: when Output enters paging, the footer shows “Up/Down: scroll, Esc: exit”; press Esc to exit paging and return to input.

Commands and Usage

• Normal commands: enter and press Enter, e.g., loop, tui, help (handled by internal debugger).
• History commands: when input is empty, pressing Enter repeats the last command.
• Clear: type clear and press Enter; only clears Output (does not affect message history).
• Demo/background commands: append & to run in background; when finished, an end hint appears in Output; use list_demo_cmds to see current background commands.
• Directly run system/dangerous commands: prefix with ! (e.g., !loop); after running, it prioritizes scrolling to the latest output.
• List background commands: list_demo_cmds shows running demo commands and start times.

Message Configuration (message_config)

• Purpose: view/adjust message trimming policy at runtime; control history retention and LLM input token limit.
• Commands:
  • message_config to view current config
  • message_config <key> <value> to set a config item
• Configurable items:
  • max_keep_msgs: number of historical messages to keep (affects conversation memory window)
  • max_token: token limit for trimming before sending to model (affects cost/truncation)
• Examples:
  • message_config
  • message_config max_keep_msgs 8
  • message_config max_token 4096

Other notes

• Auto‑completion: supports command names and some parameters; if there are many candidates, they are shown in batches; press Tab multiple times to view remaining items.
• Busy hints: while a command is executing, the input box title cycles through (wait.), (wait..), (wait…), indicating processing.
• Message focus: when not manually scrolled, focus follows the latest message automatically; after entering manual scrolling, it stays until Esc or scrolled to the end.
• Error tolerance: if some UI operations fail (e.g., terminal doesn’t support some control sequences), the TUI tries to fall back to a safe state and continue running.

6 - FAQ

FAQ

• Switch model: set openai.model_name in config.yaml.
• Errors during verification: press Ctrl+C to enter interactive mode; run status and help.
• Check failed: read reference_files via ReadTextFile; fix per hints; iterate RunTestCases → Check.
• Custom stages: edit vagent/lang/zh/config/default.yaml or use --override.
• Add tools: create class under vagent/tools/, inherit UCTool, and load with --ex-tools YourTool.
• MCP connection: check port/firewall; change --mcp-server-port; add --no-embed-tools if no embedding.
• Read-only protection: limit writes with --no-write/--nw (paths must be under workspace).

Why is there no default config.yaml in Quick Start?

• When installed via pip, there is no repo config.yaml, so Quick Start Start MCP Server doesn’t pass --config config.yaml.
• You can add a config.yaml in your workspace and start with --config config.yaml, or clone the repo to use the built-in configs.

Adjust message window and token limit?

• In TUI: message_config to view; set message_config max_keep_msgs 8 or message_config max_token 4096.
• Scope: affects conversation history trimming and the maximum token limit sent to the LLM (effective via the Summarization/Trim node).

“CK bug” vs “TC bug”?

• Use the unified term “TC bug”. Ensure <TC-*> in the bug doc maps to failing tests.

Where is WriteTextFile?

• Removed. Use EditTextFile (overwrite/append/replace) or other file tools.