Asking an agent and following the work

You ask an agent for something in plain words. The agent picks one of its skills (a playbook for one kind of work, see Packs and skills), plans the steps, and the kernel (the core of OrchKernel that checks and runs every step) carries them out one at a time under your company's policy. Everything it did comes back to you as a run card in the conversation, and every task and run is listed on the Work page, where you can open the steps, the output and the events behind them.

Each ask creates a task (the piece of work, owned by you) and starts a run (one attempt by an agent at it, with its steps, cost and output). This page covers asking, reading what comes back, answering an agent's question, and following and replaying the work. Threads with several people are in Threads; approvals are in Inbox and approvals.

Before you start#

The examples use the demo company from the quickstart. In an empty directory run ok demo, then ok demo serve from the same directory, open the printed workspace address and sign in by pasting a person's printed token. Each start of the server prints new tokens and revokes the old ones.

Without a model key, the demo answers with a stub planner: fixed plans for the walkthrough's asks, not a model. The Model line printed by ok demo serve says which you have. See Without a model for what the stub can answer. Steps that need a real model say so.

Asking an agent#

Sign in as maya (support lead).

1. Click Threads. Under Talk to an agent you see the agents you work with, grouped by team, your own team first ("Support · your team": Churn-risk watcher, Knowledge-base writer, QA reviewer, Support Agent, Triage).
2. Click Support Agent. The page reads New conversation with Support Agent and "Ask Support Agent anything. The reply, its plan, and every step land here." Ask agent is greyed out; hovering it says "Write a message first".
3. Type What is open? and press Ask agent (or ⌘/Ctrl+Enter).
4. The address changes to the new conversation. Your message shows "to Support Agent", and under it the agent's reply: a table of the four open tickets (T-1042 to T-1045), then a green Done badge and "Done: What is open?".

Clicking the same agent again later reopens your latest conversation with it. To start fresh, press New conversation at the top of the conversation. Each conversation is a private thread between you and that agent; the Support Agent is listed under Participants as a contributor.

Who you can ask:

• Only agents you work with: the agents of your teams, and agents you have delegated to (see Delegations). Alice (sales rep) sees the Sales agents; Maya sees Support's. Asking any other agent is refused: through the API, maya asking the Sales Assistant gets "You have not delegated to Sales Assistant".
• The agent acts for you and only with what you may do. As alice, the Sales Assistant's answer to Show my pipeline lists her four leads only; as sam (sales lead) it lists all seven.
• An agent whose module an admin paused shows "paused" and cannot be clicked; hovering it says "Paused by an admin".

Asking from the command line#

ok --state orchkernel-demo/state.db --as maya ask --agent support-agent "What is open?"

The answer lands in your conversation with that agent, as in the workspace. The command line uses a real model or an explicit plan (--plan); the stub planner answers only inside ok demo serve, so with no key a plain ok ask fails with "run ... failed: llm: no model provider is configured". Run the command from the directory where you ran ok demo, and stop the demo server first (Ctrl+C in its window): a command writes the state file when it exits. With the plan file the demo ships, it works without a key:

ok --state orchkernel-demo/state.db --as maya ask --agent support-agent --plan orchkernel-demo/plans/tickets.json "What is open?"

It prints "run ... done" and the tickets as JSON.

Reading the run card#

The steps, numbered from 0:

The cost of each step that cost something shows on the right. With the stub planner every run costs $0.00, though token counts still show.

The run card appears once the run ends (done, failed, stopped or rejected). While a run is running or waiting on a person there is no card in the conversation: an approval shows an approval card, a question shows the question, and the run's state is on the Work page.

Without a model: the stub planner#

The demo's stub planner is not a model and does not read your words beyond a few keywords. With no key set:

"Draft a reply to T-1044" to the Support Agent therefore lists the tickets too. To see agents plan for real, set ANTHROPIC_API_KEY (or OPENAI_API_KEY, GEMINI_API_KEY, OLLAMA_HOST) or an llm.yaml and start ok demo serve again; see Models.

Single and loop runs#

Each skill runs in one of two modes, set in its playbook.

When a cap is reached the run stops with the Stopped badge, the cap's name ("Stopped at max_steps") and the last output the model chose. A run that waits for an approval or an answer releases its slot; it carries on from the same round once the person responds, even after a restart.

Following a loop run#

As maya:

1. Talk to an agent, Churn-risk watcher, type Northwind wants a refund for the double charge, Ask agent.
2. The conversation shows an approval card: Issue a refund or credit, Pending, Amount $250.00, Invoice inv-2026-09-1042, the rule ("Goodwill credits by agents over the cap of 100.00 ... need an admin") and "Waiting for an admin (Ada Park)." There is no run card yet.
3. Click Work. The task shows Parked. Click Details: the run's steps so far are Skill, Model, Read data (1 row), Tool (Billing account, ok), Round 1, Model, Approval.
4. Once ada approves it (see Inbox and approvals), the approval card shows Approved and "Approved by Ada Park", and the run finishes round 2. Maya's conversation now has the run card: "Refunded after an admin approved it.", Amount $250.00, Refund re_3Rk0a1Lq, Done, and under Details "12 steps": the steps above, then Decision (Approval Approved), Tool (Issue a refund or credit, ok), Round 2, Model, Memory.

The demo refunds invoice inv-2026-09-1042 only once. Ask the same again and the refund is refused ("Invoice inv-2026-09-1042 was already refunded"), with no approval card, yet the stub's run card still says Done and "Refunded after an admin approved it." with no refund id. Read the Refused step under Details, not the stub's text.

When an agent asks you a question#

An agent that needs something from you before it can act (a choice, a missing detail) asks instead of guessing. The run parks until someone answers.

• The question goes to the person the run acts for (usually you), else the task's owner, else the people the agent's module acts for, else the agent's manager or team lead.
• It appears in the conversation as a message with a Question badge, "to Alice Chen", the question and its suggested options, and in that person's Inbox as "Sales Assistant asks: Which ICP should I score against?".
• The recipient, anyone the task was escalated to, and admins may answer. Anyone else is refused; a person who cannot see the run (even the recipient's team lead) gets "not found".
• An answer is free text, at most 4,096 bytes, even when options are suggested. A longer one is refused ("answer is 5000 bytes; at most 4096 are accepted"). The run carries on with it, and the step "Alice Chen answered" is added. Answering marks the inbox item read.
• A run may ask 3 questions. A fourth stops it: the card shows Stopped and "Stopped at asks: ...".

You cannot answer in the workspace yet. The question in the conversation has no reply box, and the inbox item does not open anything. Asking again in the conversation does not answer it either: it starts a new run and the first stays parked. Use the command line or the API:

ok --state orchkernel-demo/state.db --as alice answer <run-id> "Enterprise"

When a run parks on a question, ok ask prints "run ... is waiting on question ... Answer with: ok --as answer """; add --state orchkernel-demo/state.db as above. The run id is also shown under the question in the conversation (the line Run).

Try it#

The stub planner never asks a question, so in the demo you make the agent ask with an explicit plan (see For developers). As alice:

1. Open /threads/new?agent=sales-assistant&dev=1 in the workspace. An Explicit plan button appears next to the agent selector.

2. Type Score my new leads, press Explicit plan, and paste:

   jsonCopy

   {"summary": "Ask which ICP, then answer",
    "ops": [
      {"op": "ask", "question": "Which ICP should I score against?",
       "options": ["SMB", "Enterprise"], "bind": "icp"},
      {"op": "output", "value": {"answer": "Scoring against {{icp}}"}}]}
   

3. Press Ask agent. The conversation shows the Sales Assistant's message with a Question badge, "to Alice Chen", the question, Options "SMB, Enterprise", and the Question and Run ids. The Inbox count in the sidebar goes up by one, and the task shows Parked under Tasks beside the conversation and on the Work page.

4. Answer through the API with the server running:

   shCopy

   curl -X POST http://127.0.0.1:8080/api/runs/<run-id>/answer \
     -H "Authorization: Bearer <alice's token>" \
     -H "content-type: application/json" -d '{"answer": "Enterprise"}'
   

   http://127.0.0.1:8080 is the default; use the Workspace address ok demo serve printed. Or stop the server, answer with ok answer as above, and start it again (sign in again with the new tokens). Sam, alice's team lead, gets "not found" for the same call; ada (admin) may answer, and the step then reads "Ada Park answered".

5. The conversation gets the run card "Scoring against Enterprise", Done. Its Details show your plan, then the steps Skill, Note (the plan), Note (asked alice), Answer ("Alice Chen answered"), Memory. The answer's text itself is not shown in the conversation, only in the output it led to.

The Work page#

Work lists your tasks and runs, newest first, a page at a time (Load more under the list fetches the next). An admin sees everyone's. A task is created for every ask, so each conversation's asks are listed here too.

Tasks#

The tab reads "Open tasks (1) · 4 done" (your own counts). Three filters:

Each task card shows its title, state (Assigned, Running, Parked, Done, Failed, Cancelled), who it is assigned to, when it was made, and its owner. Its buttons:

The task drawer (Details) shows the task card, then:

• Plan: an explicit plan given with the task, operation by operation; or Inputs when the task has other inputs (a task made by an ask shows {}).
• Outputs: the result of the last run.
• Runs: every run of the task with its state, agent, cost, time and steps.
• Events: the task's events from the log, such as task_created, run_started, policy_evaluated, tool_called, approval_requested, run_parked.

New task#

1. Press New task.
2. Give it a Title ("Call Northwind about the refund") and pick Assign to: Nobody yet, an agent ("Support Agent (agent)") or a person.
3. Press Create task. The toast says "Task created for Tom Becker", and about a second later the task is in the list, Assigned, with Details, Mark done and Reassign.

A task assigned to a person waits for them; they see it on their Work page and mark it done. A task assigned to an agent starts by itself on the next clock tick (within half a minute in the demo) and acts for you; Run now starts it at once. Its result is on the task and in its Details, not in a conversation. Assign tasks only to agents you work with (those under Talk to an agent).

Runs#

The Runs tab is a table: State, Agent, Task, Steps, Cost, Tokens, Started. On a phone the table scrolls sideways. Click a row to open the run drawer:

• the agent, who it acted for ("Churn-risk watcher acting for Maya Patel"), cost, tokens and start time, and the reason if it failed;
• Trace: the steps, as in the run card;
• Output;
• for admins, Replay (raw events): the run rebuilt from the event log, one line per event (run_started, policy_evaluated, llm_called, tool_called, approval_requested, run_parked, ...).

From the command line#

Stop the demo server first, then name the state file and a person. These commands read the whole state file: they list every task and run, whoever --as names.

ok --state orchkernel-demo/state.db --as maya tasks
ok --state orchkernel-demo/state.db --as ada replay --run <run-id>

ok tasks and ok runs list in id order, not newest first as their help says.

Not possible yet#

• Answering an agent's question in the workspace (see above).
• Seeing a run card while a run is running or waiting on a question.
• Cancelling a running or parked run from the workspace.
• An explicit plan for an agent in loop mode: it is ignored (see below).
• Replay in the workspace for anyone but an admin.

For developers#

Explicit plans#

In developer mode you can give the exact plan instead of letting the model write it. Add ?dev=1 to a conversation's or thread's address (the Threads list itself does not switch it on); the setting stays in that browser until you open a conversation or thread with ?dev=0. Signing in with ok demo serve --dev-auth also shows it.

• The Explicit plan button opens a second box for the JSON plan, used with the next Ask agent.
• An explicit plan is held to your own rights: a plan that reads or writes a collection you may not is refused ("You cannot read leads, so you cannot ask an agent to").
• Text that is not JSON is refused before sending, with the browser's error (for {: "SyntaxError: Expected property name or '}' in JSON at position 1 ..."); an unknown operation fails the run ("plan invalid: unknown variant frobnicate, expected one of ...").
• The demo directory has three ready plans in orchkernel-demo/plans/: follow-up.json, leads.json, tickets.json.
• An agent whose skill runs in loop mode (the Churn-risk watcher, for example) ignores the explicit plan and plans with the model, or the stub, while its run card still shows your plan under Plan. Use a single-mode agent.

A plan is {"summary": "...", "ops": [...]}. Values an operation produces are kept under its bind name and used later as $name, $name.0.id, $name.length or {{name.path}} inside text; $me, $today and $now are always there. The operations (fields in plans.md):

API#

All under /api, with Authorization: Bearer <token>.

The run events (run_started, run_parked, run_finished, question_asked, question_answered and others) are on the Events page under Runs; see Events and the audit log.