Testing

Run agents locally, test subagents in isolation, and debug issues before publishing.

Running Locally#

Use the rush CLI to run agents during development. Point it at your agent directory with a test prompt and iterate on the output.

# Run with a test prompt
rush run ./my-agent --prompt "What is quantum computing?" --non-interactive

# Run with verbose output (see tool calls, token usage)
rush run ./my-agent --prompt "test" --verbose --stream-events

# Run an installed agent
rush run my-agent --prompt "test"

Action	Command
Build agent	`rush build agents/my-agent`
Test locally (relative)	`rush run ./agents/my-agent --prompt "test" --non-interactive`
Test locally (absolute)	`rush run /path/to/agent --prompt "test" --non-interactive`
Test installed	`rush run my-agent --prompt "test"`
Test subagent	`rush run ./agents/my-agent --sub name --prompt "test"`
Publish	`rush publish agents/my-agent`

Path Resolution#

rush run accepts multiple path formats depending on where your agent lives:

Format	Example	Resolution
`./agents/my-agent`	Relative with ./ prefix	Filesystem only
`/Users/you/agents/my-agent`	Absolute path	Filesystem only
`my-agent`	Simple name	Registry / installed first
`prix/researcher`	Developer-prefixed	Registry

Use ./ or absolute paths for local development. Use simple names for installed agents.

Testing Subagents#

Use the --sub flag to test specialist subagents in isolation without running the full orchestrator:

# Test a subagent without running the orchestrator
rush run ./agents/rabbit-hole --sub academic-researcher \
  --prompt "Research papers on AI alignment"

# Works with installed agents too
rush run rabbit-hole --sub academic-researcher --prompt "Research X"

Key points:

--sub loads the main agent for context, then executes only the specified subagent
--prompt is required when using --sub
Shows available subagents if you use a nonexistent name

Test each subagent individually before testing the full orchestrator. This isolates issues and saves time.

Debugging#

Verbose Mode

--verbose shows tool calls, model responses, and token usage. --stream-events shows the real-time event stream. Combine both for maximum visibility:

rush run ./my-agent --prompt "test" --verbose --stream-events --non-interactive

Common Issues

Issue	Cause	Fix
Unknown UI component	`ui_components` uses wrong format	Must be a map, not a list. Use `ui_components: { email_card: {} }` not `- email_card`
No valid agent profile found	YAML parsing error	Check for `ui_components` as list instead of map
Unknown tool	Tool not declared	Add to `tools` list in agent.yaml
Build quality check failed	Prompt has rigid rules	Use mindset-over-rules approach
Agent asks too many questions	Prompt is too passive	Add proactivity to identity section
Subagent not found	Wrong name	Use `--sub nonexistent` to see available subagents

Build Validation

rush build validates your agent before publishing. It catches:

Missing required fields
Unknown tool names
Missing CHANGELOG.md entry for current version
Prompt quality (LLM-powered review)

Never use --skip-quality, --skip-lock, or --force with rush build. These flags skip important checks.

Development Workflow#

Recommended workflow for iterating on agents:

Edit agent.yaml / prompt.yaml
Test with rush run ./my-agent --prompt "test task" --non-interactive
Check output, iterate on prompt
Run rush build agents/my-agent to validate
When satisfied, rush publish agents/my-agent

Make sure rush --version resolves before you start — see the Installation guide if it's missing.

Publishing

Build, validate, and publish agents to the registry.

Prompt Design

Write effective prompts that make agents proactive.