Goals: agents that pursue a business goal over days

An ask is one job that ends. A goal is a number an agent works toward over days, the way an employee would: "Book 20 demos with salons in Pune by 30 November", "Every urgent ticket answered within 4 hours this week". You give the goal a measure, a target, a deadline, a budget and the agent that works it. OrchKernel keeps the goal, measures progress from records it trusts, wakes the agent on a schedule, keeps it inside its budget, caps and approvals, and shows you how it is going.

The agent plans, works a little at each wake, writes what it tried in the goal's journal, and stops when the goal ends. It never sets or changes a goal: only people do. Missing the target is acceptable; the agent is told to report honestly, and messages it sends never count as progress.

This page covers who sets a goal, the New goal sheet, the plan you approve, what happens at each wake, reading a goal's page, pace and bands, limits, changing, pausing and stopping a goal, records a goal holds, and the API and command line. The steps use the demo company (ok demo serve): Ada is the admin, Sam leads Sales, Alice is a rep. What is not possible yet is listed at the end.

Words used on this page#

• Measure: what the goal counts. An outcome from Company → Impact (a demo booked), records to count or add up (leads whose stage became Demo), a current number (open urgent tickets now), or a share (urgent tickets answered within 4 hours, of all urgent tickets).
• Target and direction: the number to reach, at least, at most or kept below.
• Period: from the day the goal starts to its deadline. A goal counts what happens in its period, for the records its own filter keeps (territory is Pune), however old the record is.
• Baseline: the measure over the period of the same length before the goal started, recorded when it starts. It is shown beside the number; for counts and sums the pace still starts at 0.
• Pace: where the number should be by now for the goal to reach its target, over working days in the company calendar.
• Band: On track, At risk or Off track, from the number against the pace (below).
• Counted and claimed: a record the goal's own agent made qualify is claimed until a person confirms it; only then is it counted. A change from anywhere else (a person, a webhook, someone else's system) counts at once.
• Plan: what the agent means to do, as tactics (each a channel, a segment of records and its own caps), the segments as record filters, and what it will not do. You approve it before anything reaches a customer.
• Goal item: one piece of customer-facing work (a draft to one lead) the kernel splits out of a wake as its own task, waiting on its own approval, so twenty drafts never hold up the goal.
• Hold: a record a goal is working. Other goals leave it alone until this goal ends or someone releases it.
• Journal: the goal's diary. OrchKernel writes why it woke, readings, spend, approvals and state changes; the agent adds a short note per wake.
• Autonomy: how far the agent goes on its own: Research only (reads and plans) or Drafts for approval (every customer message waits for a person). Send approved templates is not available yet.

Who sets a goal#

A lead who tries to set a goal for another team's agent is told "You may set goals only for your own team's agents; ask its lead."

Setting a goal#

1. Sign in as Sam and open Work → Goals, then New goal. (Alice, a member, sees Propose a goal instead.)
2. The goal: a name ("Pune demos"), the goal in your words ("Book 20 demos with salons in Pune by 30 November"), and whether it is Committed or a Stretch.
3. What it counts: pick An outcome (the outcomes turned on under Company → Impact), or Records to count, A current number or A share, built from a collection, what to count or add up, the date that puts a record in the period, and conditions ("territory is Pune"). Then the direction, the target and the deadline. A goal lasts at most 90 days.
4. Who works it: the agent, a sponsor (next in line when it goes badly), and who decides its drafts and questions: Each record's person (the rep a lead is assigned to; without one, you) or Me.
5. How far the agent goes: Research only or Drafts for approval.
6. Budget and limits: the total budget (required), the most a day (left empty: the total ÷ working days × 1.5), the caps a day (WhatsApp 25, emails 20, calls 30 by default), the records it may read a day (500), and the guard that pauses outreach when opt-outs pass 3% over 7 days.
7. When it wakes: the days and up to three times (09:30 and 15:00, Monday to Saturday), in the company's time zone, and the time of the daily digest.
8. Under the fields, the preview shows the working days to the deadline (the last working day if the deadline falls on a weekend or holiday), the pace a working day, the daily limit, and the baseline when it can be read. It warns when the agent could change the records the measure counts ("Sales Assistant can change leads, the records this goal counts. A record it changes so that it counts is shown as claimed, not counted, until a person confirms it."). The preview reads as you: a measure over records you may not read is refused ("the measure counts records of hr_pay that Alice may not read"), and so is a goal whose owner may not read them.
9. Set the goal. It starts now, Planning: its first wake drafts a plan.

A goal without a measure, a target, a deadline, a budget or an agent is refused with what is missing ("deadline: a goal needs a deadline"), and so is one longer than 90 days ("deadline: a goal lasts at most 90 days").

The plan#

The first wake reads the records the goal's filter keeps and drafts a plan. The goal's page shows it as a card Waiting for you: each tactic with its channels, the segment it works and its caps; the segments as filters; what the agent will not do; its notes.

• Approve plan starts the goal working (Active).
• Lower caps lets you lower a tactic's caps first; Approve with these caps sends them as your edit.
• Reject asks why (optional) and sends it back: the reason goes in the journal and the next planning wake reads it.

The plan waits for its owner; for a goal a member proposed, for the team's lead. While it waits, nothing wakes the goal and its page says so ("Plan v1 waits for Sam. Nothing wakes the goal until it is decided.").

A segment is a filter of plain fields and values ({ "status": "trial", "territory": "Pune" }), shown in words ("status is trial and territory is Pune"). The plan's checks read a record as someone other than the goal's agent last wrote it: the agent cannot move a record into a segment, give it an address or name its own approver.

Nothing customer-facing happens before you approve a plan. Once approved, the plan is checked at the gate, not only shown to the agent: a send on a channel the plan does not list, or to a record outside its segments, is refused with "outside the approved plan: …", and the agent is told to propose a change. Under Plan the page lists every approved version with what changed from the one before.

At each wake#

A goal wakes at its times, and when you press Wake now. One wake is open at a time; after the server was down there is one catch-up wake, not one per missed time. Each wake is a run of the goal's agent that starts from a fixed, fresh context: the goal and the approved plan, the number against the pace, the budget and caps left today, what is new, what waits for people, the last journal lines, and its memory.

Every draft to a customer becomes its own goal item: a task with its own approval, titled with the record and the goal ("Email draft for Glow Salon: goal Pune demos"). It goes to the record's person (the rep a lead is assigned to, if they may read the lead) or the owner, unless a company rule names someone else (a rule that sends every email to an admin still does). The wake does not wait for them; it ends, and the next one carries on. Approvals on goal work also reach your inbox like any other.

A decision is journaled with who made it and their reason, never the message ("Anand declined the draft for Glow Salon (Trials on WhatsApp): already talking to them"). The next wake sees it, and the goal does not draft to that record with that tactic again until its plan changes; the record's hold is released. A goal set to Research only reads and changes nothing outside its own worklist.

A reply from a prospect, or anything else a person outside wrote, puts the wake in review mode: goal items, the agent's note and writes to its own records still go ahead; anything else waits for a person.

A goal's page#

Open a goal from Work → Goals. At the top: its state, its band while it is active, and Wake now, Pause (or Resume), Adjust and Stop for whoever manages it (Accept and Decline on a proposed goal, for its lead).

• Tiles: the number counted against the target (with what is claimed), the pace by now and the baseline, the spend of the budget and today's spend of the daily limit, the next wake and the deadline. A source that cannot be read shows Unknown, which never counts as success.
• Progress: a chart of the number counted over the period (claimed drawn apart, dotted), the pace line, the target and the baseline.
• What's next: one line under the title: who decides what waits ("Plan v1 waits for Sam"), the next wake and how many drafts wait for people.
• Today: each cap used ("WhatsApp 14 of 25"), the wakes, and today's spend.
• Waiting for people: the goal's drafts and questions, each with the record and who it waits for.
• How it is set: the measure, period, agent, autonomy, who decides drafts, wake times, budget and guards.
• Plan: the approved versions and what changed.
• Spot-checks: records the goal counted, picked at random, with Counts and Does not count. One that does not is taken off the goal's count; the Impact page's figures are not changed.
• Records it works: the records the goal holds, each with Release.
• Journal: newest first, in plain words (money, dates, wake times). The agent's notes are shown as its own words, in a box of their own; they are never instructions to anyone.

The journal, the records it works, the drafts waiting and the spot-checks are for whoever manages the goal and its sponsor.

Pace and bands#

For a goal to reach at least a target:

For at most and keep below: on track at or under the target, at risk up to 10% over it, off track beyond. Pace counts working days only (the company's working week and holidays, under Company); for a count or a sum it starts at 0, for a share or a current number it runs from the baseline to the target. A count is judged in whole records: on the first morning, with less than one record due, a goal is not off track. Falling behind never raises caps or the budget.

Limits#

• Budget: the goal stops working when its total is spent (Out of budget), and stops for the day at its daily limit. Goal spend also counts against the agent's own budget.
• Caps a day, for the goal as a whole and for each tactic, are set with the goal and its plan, and today's use shows on its page. Refusing a send past a goal's cap before anyone is asked ("Pune demos reached today's limit of 25 WhatsApp messages") comes in the next batch.
• Consent and every other cap apply as for any send (see Contacts and consent and Limits).
• Records read a day: readings refresh only the records the goal is working, within this budget.
• 90 days at most; then the goal ends.
• A kill switch and budget scope goal:<id> stop one goal's work at once (see the gate). The owner, the team's lead or an admin engages it; a switch an admin engaged only an admin releases. Three failed wakes in a row pause the goal, and so does its owner leaving the company.

Changing, pausing and stopping#

Adjust changes the target, deadline, budget, daily limit, caps, wake times, autonomy and who decides drafts. Each change is a new version of the goal and a line in its journal ("Version 2: target changed from 20 to 25"). Only people change a goal: an agent that tries is refused with "only people change a goal's target".

Pause stops the wakes until Resume; a wake already running finishes its round and starts no new work, and drafts already waiting for people do not go out while it is paused (approving one is refused with "goal Pune demos is paused"; after Resume the same approval sends it). Stop withdraws the goal's approvals that wait for people, cancels its open goal items and ends its wakes; a stopped goal cannot be started again. A goal that has ended (Succeeded, Missed, Stopped, Out of budget) changes no more.

Records a goal holds#

One goal works a record at a time. A record is held from the goal's first item for it until the goal ends or someone releases it. Another goal's sends and writes to it are refused ("held by goal Pune demos"); an agent run outside goals is not blocked but sees that the record is worked by a goal.

A record's page in the workspace (in an app's pages and in Brain) shows Worked by goal: Pune demos to anyone who may read the record (linking to the goal for those who may see it), with Release for whoever manages the goal. A person declining a record's only draft releases it too. When two goals' measures overlap, a held record's progress counts for the goal holding it only.

API and command line#

Every route answers people only: an agent token gets 403 agent_token_scope, and an agent by any other way 403 people_only (a change of a goal: 403 goal_people_only, "only people change a goal's {field}"). Every refusal carries its sentence in message.

Errors: 403 people_only, goal_people_only, denied (not yours to manage, another team's agent, or a member widening the goal their lead accepted); 404 not_found (no such goal you may see, a record it does not offer to spot-check); 409 no_plan_waiting, not_held (a release of a record it does not hold), goal_not_running (a paused, proposed or ended goal does not wake or pause), wake_open (a wake is under way), goal_killed, not_proposed, goal_ended; 422 invalid with problems (also a field a person does not change, such as state).

The command line reads goals, as you may see them:

ok --as sam goal list          # one line a goal: state, number, pace, next wake, spend
ok --as sam goal show <id>     # the goal, its measure, budget, caps, plan and journal

ok goal list and ok goal show <id> change nothing; set and change goals in the workspace or through the API.

Giving the Goal lead its tools#

The bundled Goal lead plans, keeps its worklist and journals; it ships with no send or read tools of its own. Give it the company's:

• A connected system's tools (reads such as search_leads, and its writes and sends): under Company → Connectors, make a toolset with the tools and give it to the Goal lead (or your copy of it). A toolset counts as the agent's own tools for its runs, whatever its skill lists.
• An app's send tools (the email app's send, WhatsApp): copy the Goal lead (ok agent fork goal-lead --slug acme) and propose a change to the copy's goal-pursuit skill that adds them; the change pipeline runs its evals before it applies.

The goal's allowlist (allow_tools), when set, narrows what the agent may use for this goal to those tools.

Not possible yet#

These come in the next batch of goals:

• Waking on events: a reply from a contact the goal works, a change to a record it holds, an approval decided, a goal item finished.
• More than one agent on a goal (workers beside the lead agent).
• The weekly review proposing the next plan version, plan change proposals, and escalation from the owner to the sponsor to admins when a goal is off track at two reviews.
• Winding down at the target (open conversations become the owner's tasks, a final report), and a goal that passes its deadline below target ending as missed with its report.
• Approvals on goal work expiring at the end of the next working day.
• Goal and tactic caps on the shared counters, guards that pause one tactic, and autonomy lowered automatically at an off-track review.
• A first WhatsApp message by an approved template, and replies read through a connector.
• Send approved templates autonomy.
• A connector record's hold shown in Contacts (it shows on the goal's page).