Agents

Agents Module: Step-by-Step Tutorial

This page covers agents from zero to usable routing in ask/chat. Follow in order; each step has an expected result.

Step 1: Inspect current agents

mosaic --project-state agents list
mosaic --project-state agents default

Expected: a list (possibly empty) and current default agent id if set.

Step 2: Create your first custom agent

mosaic --project-state agents add \
  --name Writer \
  --id writer \
  --skill writer \
  --temperature 0.2 \
  --max-turns 8 \
  --tools-enabled true \
  --guard-mode confirm_dangerous \
  --set-default \
  --route ask \
  --route chat

Expected: agent writer exists and is set as default.

Step 3: Show and verify details

mosaic --project-state agents show writer
mosaic --project-state agents route list
mosaic --project-state agents route resolve --route ask
mosaic --project-state agents default

Expected: ask/chat route points to writer.

Step 4: Use agent in ask/chat

# explicit agent override
mosaic --project-state ask --agent writer "summarize this repository"
mosaic --project-state chat --agent writer

# implicit via default/route
mosaic --project-state ask "hello from default agent"
mosaic --project-state chat

Expected: responses are generated with your agent settings.

Step 5: Update agent settings safely

mosaic --project-state agents update writer \
  --name "Writer V2" \
  --skill reviewer \
  --temperature 0.15 \
  --max-turns 10 \
  --route ask

mosaic --project-state agents update writer --clear-skills
mosaic --project-state agents show writer

Expected: updated fields are reflected in agent show output.

Step 6: Manage route mapping

mosaic --project-state agents route set chat writer
mosaic --project-state agents route list
mosaic --project-state agents route resolve --route chat
mosaic --project-state agents route remove chat

Expected: route changes apply immediately to routing resolution.

Step 7: Switch default and rollback

mosaic --project-state agents default writer
mosaic --project-state agents default

# optional cleanup
mosaic --project-state agents remove writer

Use remove only when the agent is no longer referenced by your routing policy.

Step 8: Troubleshooting checklist

• If ask --agent writer fails, run agents show writer first.
• If skill-bound agent fails, run skills list and verify configured --skill ids.
• If route behavior is unexpected, run agents route list and agents route resolve.
• If execution is blocked, inspect approvals get and sandbox get.
• Use doctor and logs --tail 120 for diagnosis context.