Asking several agents together

Some questions need more than one agent. Search Console lives with the SEO Analyst and GA4 with the Analytics Analyst; "how did marketing do last month?" needs both. In OrchKernel you pick both agents in the message box, write one ask, and press Send. Each agent looks at its own part, at the same time, and you get one combined answer, or each agent's answer on its own if you prefer. Or one agent leads: it asks the others what it needs and answers you itself.

This page covers picking several agents, the choices before Send (how they answer, the dates, who answers their questions, who else sees the answers), following the ask on its card, agents asking other agents, and what you can do while it runs and after it ends. Asking one agent is in Asking an agent; setting an ask to run again every Monday is in Repeats.

The page describes the golive branch. What is not possible yet is listed at the end.

Before you start#

The examples use the demo company from the quickstart, signed in as sam (Sam Ortiz, the sales lead). The demo binds the Marketing app to Sales, so Sam can ask the SEO Analyst, the Analytics Analyst and the Marketing Lead.

Without a model key the demo's stub planner answers every agent, and it knows none of these asks: each agent, and the agent that combines them, answers with the stub's "No model is configured" note. The card, its rows, Based on and the costs still show as described below, so you can follow the steps; the answers themselves need a model (see Models).

Picking several agents#

1. Open Threads, choose New thread, give it the goal "Marketing review" and create it.
2. In the message box type @SEO and pick SEO Analyst. Its chip appears at the start of the box, and its name stays in your text as @SEO Analyst.
3. Type check GSC, and then @Analytics and pick Analytics Analyst. Both chips stay: picking an agent adds it and never replaces the one before.
4. Finish the sentence: check GA4 for the last 28 days. The box now reads "@SEO Analyst check GSC, @Analytics Analyst check GA4 for the last 28 days", and Send reads "Send to 2 agents".

What you wrote after each name is that agent's part. Each agent is told its part as you wrote it ("Your part, as Sam wrote it: check GSC"), and the card shows it under the agent's name.

How the chips behave:

• Adding. The @ button after the chips ("Add another agent to this ask") opens the picker; so does typing @. An agent already chipped reads "In this ask" in the picker. A name typed by hand (@Analytics Analyst followed by a space) becomes a chip too.
• At most 6. With six chips every other agent in the picker is greyed out with "At most 6 agents in one ask", and the @ button goes.
• Removing. ✕ on a chip removes it. Backspace at the very start of the box first selects the last chip; a second Backspace removes it, and "Removed Analytics Analyst" offers Undo. Deleting an agent's name from your text removes the whole name and keeps its chip.
• Nobody joins before Send. The chips are a draft. An agent joins the thread only when the ask is sent ("Joins when you send" on its chip).
• The draft is kept. The chips, the way they answer, the options and your text stay in this browser per thread, across a reload or a visit to another page, until you send or sign out (and for at most 7 days).
• An agent that goes off while you type. If an admin pauses a chipped agent, its chip turns grey, Send is blocked and its tooltip says why and what to do: "Analytics Analyst is paused by an admin. Remove it to ask the others." Nothing in your draft is lost.
• Posting without asking. With chips in the box, + › Post without asking agents posts your text to everyone in the thread and runs no agent; the chips stay for your next message.

On a phone the chips wrap to two rows, then "+2" opens the rest.

Coordinator#

Coordinator is a built-in agent everyone may ask. It is listed in the picker with the label "Built in" and "Combines what several agents found into one answer, and leads asks that need several agents". It has no team, tools or data of its own and works only with what the other agents answer.

• Chipped with other agents, it combines (its chip reads "combines"): it is never one of the agents asked. Under One leads it can lead instead.
• Chipped alone, it leads: the line under the box reads "Coordinator decides whom to ask (up to 8 agent runs)." It picks the agents your ask needs from the ones you may ask (your own teams' first), gives each a brief (what to look at, the dates, what to send back), asks them, and combines what they found into one answer. "@Coordinator what changed in marketing last month?" asks the SEO Analyst and the Analytics Analyst without you picking them. How its asks show and what waits for you is in Agents asking agents.

How they answer#

With two or more chips, a control in the box's row says how they answer. Click it to choose:

Under Combined, Combined by picks who writes the combined answer: Coordinator (the default), one of the chipped agents ("SEO Analyst answers its own part first, then combines"), or another agent you may ask. An agent whose playbook answers to combine (the Marketing Lead's marketing-review) uses its own playbook; any other uses the built-in combine playbook. An agent whose combine playbook could change data cannot combine ("… can change data, so it cannot lead or combine"), unless an admin approved it with a reason. With Coordinator chipped, Each answers is greyed out: "Coordinator combines; it has no part of its own".

The combined answer is written from the agents' answers only: figures as the agents gave them, which agent each finding came from, where two answers disagree, and which agents did not answer and what is missing because of it. When the agents used different dates, it says so first and does not compare across them.

One leads#

Choose One leads ("It asks the others what it needs"), then Led by: one of the chipped agents, or Coordinator when it is chipped. The line under the box reads "Marketing Lead leads and may ask SEO Analyst and Analytics Analyst. Questions go to you." and Send asks the lead alone.

• Who may lead. Coordinator, or an agent with a skill that may ask other agents and changes no data. Otherwise Send is refused: "Content Writer does not ask other agents, so it cannot lead: ask the agents Combined", or "… can change data, so it cannot lead or combine".
• Whom it may ask. The other agents you chipped, and the agents its own skill names. It need not ask them all: it decides from what your ask needs, and may answer without asking anyone.
• What you see. Your ask, then the lead's own card. While it waits, its line reads "Waiting for SEO Analyst and Analytics Analyst (1 of 2 done)" with an orange dot (agents are at work, not waiting on you). Under its card, each time it asked shows as a small card "Asked SEO Analyst and Analytics Analyst", a row per agent and "1 of 2 done". A lead that asked nobody reads "Marketing Lead answered without asking others".
• Stop. Stop on the lead stops it and every agent it is waiting for. Stop on one of those agents stops that agent only; the lead goes on with what it has.
• Changes. The small cards change only through the lead: they offer no Add an agent, Ask again or Combine again ("This ask changes only through its lead"). To ask differently, send a new ask.
• Its time limit. Wait up to and Spend up to cover the lead and every agent it asks. When the time runs out the lead is stopped too, and its questions and approvals are withdrawn.
• Repeats. Repeat… keeps One leads and its lead (see Repeats).

Before you press Send#

The line under the box says what Send will do: "Send asks SEO Analyst and Analytics Analyst; Coordinator combines their answers. Questions go to you. 3 agent runs." (Each answers: "…; each answers on its own."). A shared thread adds "Everyone here sees the answers." Send's own label reads "Send to 2 agents".

The dates the ask covers#

When your text names a period, the dates are shown before you send: "Period: 10 Sep to 7 Oct 2026 (change)". The agents never decide what "last month" means: every agent is given the same dates and told to start its answer with the dates it used, and the combined answer checks them.

Dates are read in the company's time zone (see Setting up a company). Numbers like "09/10" are read day first, or month first in a United States zone, and always shown in words.

• (change) opens two date fields and "Compare with the 28 days before"; Use these dates sends yours instead.
• When the ask names two different periods ("SEO for last month, GA for last week") and each sits in a different agent's part, each agent gets its own. When they cannot be split, the note reads "Two periods found · Choose one" with a button for each.
• Notes, never blocks: "Ends after today: figures will stop at yesterday", "This covers 14 months". A period longer than 400 days is refused unless an admin raised that limit.
• When the text names no period, nothing is shown, and the agents are told "If you use dated figures, say which dates."

Who answers the agents' questions#

Questions: you in the box's row says who an agent asks when something is unclear. Click it to choose:

If no answer in (no limit, 1 hour, 4 hours or 1 day, nights included) then: ask you, keep waiting, go on with its best guess or stop that agent. The person you pick is not added to the thread; they get each question in their inbox, with whose work it is and nothing else of the conversation. If they may not read what an agent reads, the control says so and its questions come to you first: "Pat Kim may not read Campaigns, which Analytics Analyst reads: its questions come to you first, and you can pass them on." How questions travel, are passed on and time out is in When an agent asks you a question.

With An agent…, an agent's question is first put to the agent you picked, as a short ask of its own, and its answer goes back to the agent that asked. If it cannot answer (it fails, is refused, answers only with a question, or its answer holds data no model the asking agent may use is cleared for), the question comes to you as usual. You can also make a chip answer questions from its menu: click the chip and choose Answers questions instead of Answers a part (offered while two other agents stay chipped). An agent answers questions or a part, never both; at most 2 agents answer an ask's questions.

More options#

Options (with two or more chips):

• Wait up to: 1 hour, 4 hours, 1 day (the default) or 3 days. Agents still at work then are stopped, and what came back is used.
• Spend up to: a limit for every agent run of this ask together, in the company's currency. Empty, the company's default applies ($5.00 in the demo); you may not go above the ceiling an admin sets.

Who else sees the answers#

Everyone who can see a thread sees every answer in it. An agent reads what the person who asked may read, so in a thread with other people an answer can show them data they may not read themselves. Before an ask in such a thread, the box checks everyone there against what the asked agents read:

1. Create a thread "Pipeline review" with Pat Kim as a contributor.
2. Chip SEO Analyst and Analytics Analyst and type review the last 28 days. Above the box: "Pat Kim may not read Campaigns, which Analytics Analyst reads. Everyone here sees the answers." with Ask in my own conversation and Ask anyway. Send waits for your choice.
3. Ask in my own conversation opens a new conversation with the same agents and text; nothing is posted in the shared thread.
4. Ask anyway, then Send: the ask carries a line everyone sees, Pat included: "Sam Ortiz chose to ask anyway: Pat Kim may not read Campaigns." The choice is recorded as an audience_confirmed event.

For the most sensitive data Ask anyway is not offered. Chip Sales Assistant in the same thread: "Pat Kim may not read Contacts and Leads, which Sales Assistant reads. Ask in your own conversation." (An admin sets how far Ask anyway goes; by default up to confidential data.) With three or more people the note shortens to "3 people here may not read Leads and Deals · Show who".

The same check runs before anyone new comes into a thread that already holds answers: writing @Pat Kim see above in a thread where Analytics Analyst answered from Campaigns reads "Pat Kim will see everything here, including answers drawn from Campaigns, which he may not read." before Pat is brought in. Only the collections and tools are checked, not row rules; see Not possible yet.

When no model may take an agent's data#

A model is cleared for certain kinds of data (see Which model may see which data). When no model an agent may use is cleared for data its skills read, its chip carries an amber dot and the box warns: "Sales Assistant may not be able to answer: no model is cleared for customers' personal details", with Fix this for admins and Ask an admin for everyone else. It warns and does not block, since your ask may never touch that data. What happens when a run does reach it is in When no model may take the data.

When Send is refused#

The server checks everything again before anything is posted. A refused ask posts nothing and runs nobody:

When the server refuses because of one agent, its chip is marked with the reason, and the box offers Remove Analytics Analyst and send to the others.

Sending twice by accident (a double click, a retry after a dropped connection) starts one ask: the second answers with the first.

Following the ask#

The ask appears as your message, then a card for the whole ask:

Combined answer from SEO Analyst and Analytics Analyst · combined by Coordinator Period: 10 Sep to 7 Oct 2026 SEO Analyst · check GSC · Working · Planning the next step Analytics Analyst · check GA4 for the last 28 days · Answered · 1 min 12 s · $0.04 Combines when both are done 1 of 2 done · $0.04 so far · waits up to 1 day · Stop all

Each agent's row in plain words:

Answers that a Combined ask folds into its card are not repeated in the conversation. The card follows the work live; if the connection drops the foot reads "Reconnecting…", and if the card cannot load it reads "Could not load this ask's progress · Try again", while the answers already posted still show.

When every agent has finished, one item lands in your inbox: "Combined answer ready: ", "SEO Analyst and Analytics Analyst answered: " (Each answers), "1 of 2 agents answered: ", or "No agent could answer: ". You get no separate Completed note per agent.

How an ask ends#

• Every agent answered: the combine runs and the ask is done.
• Some answered: the combine still runs on what came back, and says what is missing. With only one answer the combiner's row reads "Combining 1 of 2 answers", so the cost is no surprise; you may stop it.
• None answered: nothing is combined and nothing more is spent; the card lists each reason and your inbox says "No agent could answer".
• The combine cannot run (the ask's spending limit is used up, or the combiner is paused or has no model for the data): the card says why, "Not combined: …", and Combine again stays offered, with another combiner if you like.
• The ask's time runs out: agents still at work are stopped ("Ran out of time"), their approvals and questions are withdrawn, and what came back is combined.

While it runs and after#

Anyone else in the thread sees the card and its answers, but not Ask again, Add an agent or Combine again.

When an agent waits on your answer#

While an agent of the thread waits on your answer, a banner above the box reads "Analytics Analyst is waiting for your answer: Which GA4 property: www or app?" with Answer, which brings its question card into view ("2 agents are waiting for your answer" lists them). If you type in the box and press Send instead, the box asks rather than guessing: "Send as your answer to Analytics Analyst, or as a new ask to SEO Analyst and Analytics Analyst?" (with no chips, "… or as a message to everyone?"). Your answer goes to that question only, and the agent goes on.

Follow-ups#

Come back to the thread after a combined answer and the box starts with the same agents and the same way ("Same agents as your last ask."), never with Coordinator alone. After a single agent answered, it starts with that agent, as before.

In a one-to-one conversation#

A conversation with one agent stays between you and that agent. Pick a second agent there and the box offers: "This is your conversation with SEO Analyst. Ask both in a new thread?" Ask in a new thread opens a new conversation with both chips and your text; Send there asks both. The server refuses a group ask in a one-to-one conversation too (409 one_to_one, "ask several agents in a new thread").

When the thread or its people change#

When the server restarts#

An agent that was at work when the server stopped is asked again once when it starts, provided its records show it only read; the card then says "Asked again after a restart". One that may have changed something settles "Cut short by a server restart; it may have done part of it: see its steps". An ask still open when a company is restored from a backup is not asked again: its agents settle "Cut short: the company was restored from a backup".

Agents asking agents#

A lead, the Coordinator asked alone, and any agent whose skill lists agents it may ask can ask other agents from inside its run: it sends each a brief, waits for their answers, and answers you from them. Each agent it asks runs for you, as a short ask of its own: it sees your ask and the brief, both as data, never as instructions from you; it reads and answers, and anything that would change something waits for your approval.

What waits for you. Once a run carries something from outside your own request (another agent's answer, someone else's message), asking an agent you did not choose waits for your approval: "Coordinator wants to ask Analytics Analyst. This run carried an answer from SEO Analyst." That agent's row reads "Waiting for Sam Ortiz's approval", and the run waits for it with the others. Approve and it starts; Reject and its row reads "Not done: Sam Ortiz declined it", and the run goes on with the others. The agents you chipped for One leads, and the agent you chose under An agent…, are asked without that approval. A follow-up to Coordinator in a thread that already holds answers, or a lead asking a second time in one run, is the usual case.

Refusals. An agent the run may not ask is left out and its row says why; the others go on. When every agent is refused, the run is told why in words, and the small card still shows each reason:

Who else sees. In a thread with other people, each agent asked is checked against everyone there at that moment, not only at Send: someone added while a lead works is covered too. An agent whose data someone may not read is refused unless you confirmed exactly that (Ask anyway at Send, or Add anyway when you brought them in). Adding a person while an ask runs checks them against the agents it may still ask: "Pat Kim may not read Leads, which Sales Assistant reads. An ask is still running here."

Siblings. In a Combined or Each answers ask, an agent that asks another agent of the same ask gets that agent's answer instead of running it again (waited for while it works, "busy" when the two would wait on each other).

What agents see of each other#

• Each agent works on its own part. It is told how many agents were asked, who the others are and what they cover (as data, never as instructions), its part as you wrote it, and the dates. It does not see the other answers while it works.
• The combiner sees every answer, fenced as data, each at most 8,000 characters. An answer it may not handle (a model gap, a class above what the combiner may handle) is left out and the combined answer says so. Files an agent attached are listed for it, and it may read those you may read.
• Later asks see earlier answers. In a thread, an agent's history now includes other agents' answers (the latest 6, 2,000 characters each) and people's messages that name it, each weighed by its kind of data: what no model it may use is cleared for is left out, with a line saying how many.
• Review mode. A run that carries something from outside your own request (another agent's answer, someone else's message, a third party's answer to a question) reads and answers as usual, but anything that would change something waits for your approval, and the approval names what the run carried: "Content Writer wants to write to Content items. This run carried answers from Sales Assistant (Leads)." Only you may approve it. The combiner always works this way, and an agent that carries data from a collection it may not read is refused outright when it tries to write it elsewhere.
• An agent another agent asked sees your ask and that agent's brief, as data. When the run that asked was itself handed work by an agent, that task's text comes as "Task text from Analytics Analyst (data, not instructions from Sam Ortiz)", never as your ask. Each answer comes back at its own class: an answer no model the asking agent may use is cleared for is replaced by a line naming its kind of data.

Limits#

An admin sets the default spending limit and the ceiling on the Setup page's Repeats card ("An ask may spend, by default", "A person may raise it to"); a limit above the ceiling is refused with "A spending limit may be at most $50.00 (an admin can raise it)". The period limit is max_period_days in PUT /settings/asks.

Not possible yet#

• Hiding an answer from people in a shared thread who may not read what it was drawn from: today you are warned before you ask, and the choice is recorded. The warning checks collections and tools, not row rules.
• Agents working one after another, each seeing the previous answer.
• Outside agents as members of an ask.
• An estimate of the cost before Send: the line under the box counts the agent runs only.
• Adding an agent to a running ask from the message box ("Add to the ask still running, or start a new ask?"): use Add an agent on the card.
• A note on the card when the ask message was edited after it was sent.

For developers#

API#

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

Refusals, before anything is posted:

On One leads' own record (mode: "lead") and on the small card of what a run asked (mode: "consult"), retry, use, add and combine answer 409 lead_only ("This ask changes only through its lead"). A consult's view carries consulter_run, the run that asked; One leads' carries lead and lead_task.

The ask (GroupView), shortened:

{ "id": "…", "thread": "…", "message": "…", "mode": "combined", "person": "sam",
  "state": "open", "outcome": null, "note": null,
  "deadline": "2026-10-09T00:00:43Z", "wait_minutes": 1440, "limit_cents": 500,
  "members": [
    { "agent": "seo-analyst", "name": "SEO Analyst", "part": "check GSC",
      "task": "…", "run": "…", "state": "done", "reason": null, "model_gap": null,
      "cost_cents": 4, "answer_version": 1, "activity": null, "waiting_for": null } ],
  "combiner": { "agent": "coordinator", "task": "…", "run": "…", "state": "done" },
  "answered": 2, "of": 2, "cost_cents": 9,
  "period": { "from": "2026-09-10", "to": "2026-10-07", "words": "10 Sep to 7 Oct 2026" },
  "combined": [{ "message": "…", "based_on": [{ "agent": "seo-analyst", "answer_version": 1 }], "superseded_by": null }],
  "rule": { "ask": ["asker"], "answer_within_minutes": null, "then": "wait" },
  "may": { "stop": true, "combine_again": false, "ask_again": true, "add_agent": true, "repeat": true } }

state is open, combining, settled or stopped; outcome is all, partial or none. A member's state is queued, working, waiting, done, asked, failed, declined, stopped, timed_out, interrupted or refused, with reason in words.

The ask rule: { "ask": [<whom>], "answer_within_minutes": 5..4320, "then": "wait" | "assume" | "stop" }, with up to three people in order, each asker, thread_owner, team_lead or person:<id>. A single-agent ask takes rule too.

Events#

CLI#

With the server stopped:

ok --state orchkernel-demo/state.db --as sam ask --agent seo-analyst --agent analytics-analyst "Review the last 28 days"
ok --state orchkernel-demo/state.db --as sam group <id>

Repeat --agent to ask several together (at most 6). --each asks Each answers; --combine <agent> picks the combiner; --lead <agent> asks One leads, the lead asking the other agents named; --ask-whom <person> sends the agents' questions to that person; --wait 4h and --limit 5.00 set the time and spending limits; --from 2026-09-01 --to 2026-09-30 sets the dates. Progress goes to standard error and the answer to standard output; the exit code is 0 when every agent answered, 3 when some did and 1 when none did. --no-wait prints the ask's id and returns; ok group <id> shows it later. A refusal reads in words; --verbose adds the technical line. Like a single ok ask, it needs a model: the stub planner answers only inside ok demo serve.