Task

A task is the kid-facing unit in Sprout. It is the thing that shows up on the kid's iPad, the thing they tap into, the thing they complete. Every kid touchpoint: a chat, a chore, an interactive canvas, a camera proof: is a task or starts with one.

Tasks can stand alone (your agent creates one directly) or be governed by a skill that re-runs them or refreshes them over time. Most first-time builders ship a task before they ship a skill.

Where you'll see this

In the wild: Your first task

A worked example

A daily check-in conversation task. Read the family first to resolve the kid id, then ship the task.

task.create({
name: "Daily check-in",
assignChildIds: ["<childId>"],
runMode: "conversation",
conversationSpec: {
goalType: "share",
guidance: "Ask about one highlight from today, one lowlight, and one thing they're looking forward to. Listen well; reflect back. Keep it warm and short."
},
scheduleSpec: {
taskType: "schedule",
days: ["mon","tue","wed","thu","fri"],
startMinutes: 1020
},
rewardSpec: { gems: 3 }
})

That's it. No skill needed for the simple recurring shape. Same idea works for self_check (chores) and canvas (interactive activities) tasks: swap the spec object.

Shape

Every task has these key fields:

• name: what the kid sees on the card.
• assignChildIds: which kid(s) it lands on. assignAllChildren covers the family.
• runMode: discriminator, passed explicitly. self_check (checklists and read-and-done), conversation, canvas. Camera is planned.
• conversationSpec / canvasSpec: the spec object matching the runMode. conversationSpec.guidance is the load-bearing field for a chat task; canvasSpec.canvasId points at the rendered HTML for a canvas task.
• scheduleSpec: when it fires. taskType: "onetime" with oneTimeDate, or taskType: "schedule" with days + startMinutes.
• rewardSpec: gems on a scheduled completion. Omit to award no gems.
• policy: optional earning/replay policy: freePlay (unpaid replay switch) + extras (on-ask bonus room). See Earning vs playing.
• assignmentSkillId: optional. Link a skill for governance, audit, reuse.

Earning vs playing

A task has two independent axes. Earning is when a play pays gems. Playing is whether the kid may open the task again at all. Conflating them is the most common authoring mistake.

Earning is carried by quests: offers, not payments. A scheduled task mints its earning quests automatically on each covered day (you never mint scheduled quests by hand); each quest is one earnable play whose gem price freezes at mint, so a mid-day rewardSpec edit never reprices today's offer: the new price applies from the next mint. Bonus earning beyond the schedule is minted on ask via quest.create, always bounded by the room the parent configured in policy.extras: the server clamps every grant.

Free play is the other axis: whether the kid may replay the task when nothing is earnable (off-schedule, or after today's quests are settled). Free play pays zero gems, always: an unpaid replay is not a missing payout, it is the design. Switch it with policy.freePlay.enabled. A live earning quest always wins: the kid earns before they free-play.

• Turn free play on when repetition is the value: practice drills, creative or sandbox play, games where replaying is the point.
• Keep it off when pacing is the value: progression courses where the schedule meters sessions, and conversation tasks unless you want open-ended repeats.
• One test: would a third unsupervised play today make this better or worse?

Either way the kid's cross-day progress is preserved. A task carries durable per-kid state: the canvas's journey checkpoint plus recent results, surfaced to your agent by task.describe. Free-play runs read and update that same journey: the switch decides whether extra plays are allowed once earning is done, never whether progress persists.

When to use it (and when not to)

Reach for a standalone task when:

• The thing is a one-off or recurs on a fixed weekly cadence.
• The content is the same every time (or the variations come from a canvas you've already authored).
• You don't need to re-run the authoring procedure with new context tomorrow.

Wrap it in a skill when:

• Tomorrow's task should reflect tomorrow's data (school day, last week's themes, the kid's mood).
• You want the skill in your library so it can re-fire across kids or contexts.
• The procedure benefits from audit and parameterization.

Common errors

• BAD_INPUT · conversation-needs-guidance , runMode:"conversation" without a non-empty conversationSpec.guidance. Fix: add guidance.
• BAD_INPUT · canvas-needs-a-skill , runMode:"canvas" without assignmentSkillId, or with a skill that doesn't link the canvas. Fix: wrap in a skill that links the canvas.
• BAD_INPUT · one-mode-only: passing a conversationSpec with runMode:"canvas", or vice versa. Fix: spec must match the mode.
• PERMISSION_DENIED: the childId or assignmentSkillId doesn't belong to this family.

Related tools

• task.create: author a new task.
• task.update: partial patch. Pass only the fields to change.
• task.list: keyset-paginated; filter by child, status, type.
• task.describe: read-back / preview shape without guessing. Also surfaces the per-kid state (progress + recent results) and lastRun blocks when the family has the feature enabled.
• task.complete: create a submission for a known task + kid.
• task.review: approve/deny a completion.
• task.runs.list / task.runs.get: a task's canvas-run history over time (the full run incl. the journey log on get).
• task.delete: destructive; confirm with parent.

Roadmap for this noun

• Soon runMode: "camera": first-class video/photo proof. Pair with sprout.uploadAsset on canvas.
• Soon Event-driven scheduling: tasks created in response to activity events, not just clocks.

Related reading

Your first task Skill Canvas