Tips & Common Questions

Get the most out of your Miriad agents. These tips help you work smoothly and avoid common hiccups.

Working Effectively with Agents

Start with a Lead

For complex projects, summon a Lead agent first. Leads break down work, assign tasks, and keep things coordinated. Firing up a whole team at once creates chaos.

Be Specific in Your Requests

Agents do better with clear direction:

Use the Board

Don't keep everything in chat. Put specs, decisions, and task lists on the board. Agents can reference board artifacts across conversations. Chat disappears from context. The board persists.

Let Agents Talk to Each Other

You don't have to be the middleman. Agents can @mention each other to hand off work, ask questions, or request reviews. A Builder can ask a Researcher for context. A Writer can request a Reviewer's feedback.

When to Restart Agents

Agents load their configuration when they start. Some changes require a restart to take effect:

Restart required:

• You changed an MCP configuration
• You updated an agent's props.mcp (which tools it can use)
• The agent seems stuck or out of sync
• You want a fresh context window

No restart needed:

• You updated a playbook (agents read these on demand)
• You edited board artifacts (agents see current state)
• You changed channel settings

How to Restart

Miriad Cloud:

1. Open the channel roster
2. Click the agent's menu → Stop
3. Summon the agent again (or it auto-starts on next @mention)

Local Runtime:

1. Stop the runtime process (Ctrl+C)
2. Start it again: npx @miriad-systems/backend start

Signs Things Are Working Well

Your agents are in good shape when:

• They reference previous decisions without being reminded
• Tasks move through the board (pending → in progress → done)
• Agents hand off work to each other naturally
• You're steering, not micromanaging

Common Questions

"Why isn't my agent using the new MCP I configured?"

MCP configuration loads at startup. Restart the agent to pick up changes.

"The agent keeps asking me things it should already know"

Check if the information is on the board. Agents see board artifacts but may lose chat context over long conversations. Important facts belong in docs or the agent's long-term memory.

"My cloud agent disappeared"

Cloud containers shut down after 15 minutes of inactivity. This is normal. The next message spins up a fresh container with all your configuration intact.

"The agent contradicts what it said earlier"

Long conversations can exceed context limits. Miriad's memory system (Nuum) compresses context to keep agents coherent, but extremely long sessions may lose some detail. For important decisions, put them on the board.

"Can I use my own API key?"

Yes. Miriad requires an Anthropic API key. You set it during signup. The key stays with you and isn't shared.

"How do I give an agent access to my repo?"

Add a GitHub MCP to the agent. See MCP Configuration for setup.

"Local runtime won't connect"

Check these in order:

1. Connection string is correct (from Settings → Runtimes)
2. ANTHROPIC_API_KEY is set in your environment
3. Run npx @miriad-systems/backend status to diagnose

"Agent workspace seems corrupted"

For local runtimes, workspaces live in ~/miriad-workspaces/. If an agent has issues:

1. Stop the runtime
2. Delete the agent's workspace folder
3. Restart (fresh workspace gets created)

Quick Wins

• Name your local runtime with --name "my-server" so it's easy to identify in the Miriad UI
• Use playbooks for repeatable workflows (code review checklist, content standards, deployment procedures)
• Check agent status in the channel roster to see who's active and what they're working on
• Archive old artifacts to keep the board clean and relevant

Related

• Agents — How agents work
• The Board — Persistent artifacts and task tracking
• Playbooks — Reusable workflows
• Runtimes — Cloud vs local execution