Convoship Docs

Product documentation

New Agent wizard

Four-step creation: Mission → Tools & Knowledge → Behavior → Review.

Route: /app/agents/new. Resume in-progress work with /app/agents/new?draft={uuid}.

New Agent wizard Mission step with a filled mission and derived task
Start with the operating contract: a clear mission plus task coverage. Manual tasks and generated tasks both become the Agent's intent surface.

Step 1 — Mission

  • Agent display name and mission statement.
  • Derive tasks — POST /v1/ai-agent-wizard/derive-tasks when mission ≥ 12 characters (LLM or heuristic fallback).
  • Edit derived rows — name, example utterance, needs[], tool bindings, optional SENSITIVE/FALLBACK flag.

Step 2 — Tools & Knowledge

New Agent wizard Tools and Knowledge step with tool and knowledge source controls
Tools and knowledge stay explicit. Add HTTP tools when runtime action is required; add knowledge sources when the Agent should retrieve approved content before answering.

Checkbox grid from GET /v1/workspace-tools. Sensitive tools are flagged. Knowledge sources are typically added after create on the Knowledge tab.

Step 3 — Behavior

New Agent wizard Behavior step with persona, model budget, and guardrail settings
Behavior is the production safety pass: persona, tone, model limits, spend caps, and guardrails are reviewed before the Agent is created.
  • Persona — title, tone chips, voice, boundaries.
  • Limits — max_tool_calls_per_turn, max_llm_steps_per_conv.
  • Cost — daily_spend_cap_cents (BUDGET guardrail uses running spend).
  • Guardrails — optional rows before create; server also seeds five defaults on create.

Draft autosave

Field changes debounce (~1.5s) to POST/PATCH /v1/ai-agent-drafts. Indicator shows saving / saved / error. Successful POST /v1/ai-agents deletes the draft and redirects to Brain.

Step 4 — Review & create

New Agent wizard Review step summarizing mission, tasks, budget, and preflight checks
Review should read like a launch checklist: mission, tasks, tool coverage, persona, budget, guardrails, and publish readiness in one place.

POST /v1/ai-agents with nested tasks[], tools[], guardrails[], persona, and budget caps. New agents start in draft status until you publish from the Deploy tab.

Implementation checklist

  • Mission explains the business outcome, supported users, and boundaries.
  • Every sensitive task has an AUTH guardrail and every expensive loop has budget limits.
  • Tool schemas use stable argument names the model can infer from user language.
  • Knowledge sources are scoped to content the Agent is allowed to answer from.
  • Review confirms task coverage, tool count, guardrails, and publish readiness before create.