Skip to main content

Missions

This page shows how to create a mission, try it, publish it and run it, from the dashboard and with the tools of the agent. What a mission is, why it gives an agent money and not a schedule, how the run envelope relates to the wallet's budgets, and where a person decides are explained in Missions.

Missions are available to every organization, on every plan.

What a mission contains​

A mission has a stable key (kebab-case, unique among the non-archived missions of the organization, for example lead-enrichment) and one or more versions. A version holds:

FieldWhat it decides
title, briefThe short name, and the task in Markdown (at most 8000 characters) that the agent reads at the start of every run. Say which services to use and which never to use.
sourcesThe x402 endpoints the mission may pay, each written METHOD host/path (for example POST api.exa.ai/search), at most 50, one per endpoint. An endpoint that is not on the list is refused. Each source may carry a plan: callsPerUnit (paid calls for one unit, or for one run when the task has no unit) and callPriceRef (the planned price of one call). The plan estimates the cost of a unit. It never blocks a payment.
recipientsEVM addresses the mission may transfer USDC to, at most 50.
Unit fieldsunitLabel (what the task counts: lead, page, request), unitPriceRef (target price per unit) and unitCount (estimated units per run). They go together or not at all. The run envelope is the unit price times the unit count. A mission without unit gives the run envelope directly, in envelopeRef.
durationDaysHow long a run lasts, counted from its start. One day by default.
maxPaymentRefA cap for one payment inside the mission. Empty keeps the cap of the wallet.
exemptFromWalletBudgetsWhen true, the runs do not count against the day, week and month budgets of the wallet. Each run stays bounded by its own envelope.
maxActiveRunsPerWalletA limit on simultaneous active runs per wallet. Empty means no limit, and it is the default. Set it only to slow down an agent that keeps restarting the mission.
sharingWhich wallets may run the published version: the tuning wallet only, the application, or the organization.
mode, frequencyHow a run starts, see Publish.

Amounts are written in the display currency of the organization. In the API they are integer strings in cents: 30.00 euros is "3000", and a decimal such as "0.05" is refused with a 400. The one exception is callPriceRef, which takes up to three decimals of a cent because an x402 call often costs less than one cent: 0.003 euro is "0.3".

From the dashboard​

The Missions entry of the application menu opens the page. It lists the missions in two groups, the ones To finish (a draft is being tuned) and the published ones, with a filter by state. An agent can also draft a mission: it then shows up in the list, to be tried and published.

  1. Choose New mission, pick the tuning wallet (the wallet on which the draft is written and tried), give the mission a key and fill in the form: title, task, sources with their plan, allowed recipients, target price per unit, units per run, envelope per run, run duration, the cap per payment, the exemption from the wallet budgets and the simultaneous runs per wallet.
  2. The page of a mission shows its published version, a Cost by source card (what each source cost, in amount and share; a mission that only ran as trials shows the figures of the trials), its runs, and an activity log.
  3. From the More actions menu of the page, Discard draft drops the open draft and Archive forbids new runs and drafts. Runs already started go on until they end.

Editing a mission that has a published version opens a draft of the next version, and the published version keeps running.

Try it​

The agent, or you, asks a trial of the draft on the tuning wallet. What a trial is, and why publishing needs one, is explained in Missions. The request sizes the sample:

  • On a task with units, the request names the sample size (unitCount, a few units, never more than the unit count of the draft). Its run envelope is the sample times the unit price. Without a sample size the request is refused with 422 MISSION_RUN_OUT_OF_MISSION.
  • On a task without unit, the trial gets the envelope of the draft.
  • A draft has at most one trial waiting for approval at a time (409 MISSION_TRIAL_PENDING).

The request lands in the Inbox as "asks for a trial of the mission": an operator of the tuning wallet validates it in a signed-in session. When the draft carries overrides, shown under What the draft loosens, a person who can set the policy (Owner or Admin) approves them in the Inbox too, and the trial waits for both. If the overrides are declined, the pending trials are declined with them: change the draft and ask again.

Publish​

Publishing needs all of these:

  • a completed trial of the current content of the draft (409 MISSION_DRAFT_NOT_TESTED otherwise);
  • at least one completed trial of that content that made a payment (409 MISSION_TRIAL_UNPAID otherwise), with or without sources;
  • the approval of the overrides when the draft has any (409 MISSION_OVERRIDES_NOT_APPROVED otherwise).

An operator of the tuning wallet, in a signed-in session, chooses the Publish button (labelled with the version, for example Publish v2) and sets:

FieldWhat it decides
Shared withWhich wallets may run the published version: the tuning wallet, the application, or the organization. Sharing with the whole organization also needs the right to edit the organization settings.
Start of a runon_demand (On demand), auto (Automatic) or frequency (Automatic, limited frequency). What each does is in Run modes.
Runs per walletFor frequency, a count per day, week or month, per wallet.

The dialog shows a publication digest, a fingerprint of what you are about to publish. Publishing with a stale digest is refused (409 MISSION_DIGEST_MISMATCH), which stops a version from changing under you.

Publication tightens the unit price. On a draft with a unit, Keyban reads the latest completed trial that paid. Its observed cost per unit is the amount paid divided by the units declared done. The published unit price becomes that cost plus about 20 percent, rounded up to two significant figures (whole cents below 0.10), when that is lower than the unit price of the draft. The run envelope follows: the new unit price times the estimated units. The price never rises at publication, and no new trial is needed. The publish dialog shows the price and the run envelope that will be published, and the completed trial carries them beforehand. Set the unit price of a draft with a margin: it is corrected downwards after the trial.

Runs​

Any wallet inside the sharing of the published version may start a run, with start_mission_run. A run may declare a lower unit price than the mission, never a higher one (422 MISSION_RUN_OUT_OF_MISSION). The units a run declares done are a count of what was delivered, used for the cost per unit.

  • Several runs at once. Without maxActiveRunsPerWallet, a mission may have several runs active at the same time, started by other conversations or other agents: the budgets of the wallet bound the spending.
  • A run that waits. In on_demand mode, an operator of the running wallet approves the run in the Inbox. The agent keeps waiting for it with wait_for_mission_run, withdraws it with abandon_mission_run, or tells the user.
  • Cancel. An operator can cancel an active run, which stops it and releases its pending payments.
  • Standing approvals. The API lists and revokes the standing approvals of the operators of the wallet (GET /v1/missions/standing-approvals, DELETE /v1/missions/:id/standing-approvals/:walletId); the dashboard has no screen for them. What a standing approval lifts is explained in Missions.

A run has one of these statuses: pending_approval, active, declined, abandoned, completed, cancelled or expired. The page of a mission lists its runs, and the Missions card of a wallet lists the runs of that wallet.

What the agent can do​

The mission tools are served to the agent by the wallet MCP. When one machine holds several wallets, the agent works on the wallet it drives, and list_my_wallets and use_wallet switch it (use_wallet lasts for that server only, unless its global input is set, which makes the wallet the default for later starts). The tools are listed on the Wallet MCP tools page. What the agent may and may not decide is in Missions.

ToolUse
list_missions, get_missionRead the existing missions, their statistics, the limits that currently block a start (with their retryAt), and per version the spend by source (versionStats, with the observed unit price and the share of each source).
create_missionWrite a mission and its first draft. It creates the draft right away.
update_missionChange the open draft, or open a draft of the next version from a published one, right away.
request_mission_trialAsk a trial of the draft, with the sample size on a task with units. The user sees a card and validates it in the Inbox.
wait_for_mission_runWait for the decision on a trial or a run. Each call waits up to 45 seconds, and the agent calls it again while the decision is pending.
publish_missionCheck that the draft can be published and show the user the page where they publish it. It does not publish.
discard_mission_draftDrop the open draft.
start_mission_runStart a run of a published mission, optionally with units or unitCount. It returns a run id, active at once or pending_approval in on_demand mode.
x402_pay_in_mission, transfer_usdc_in_missionPay inside an active run. They take the run id as missionRunId, which is required.
get_mission_run, list_mission_runs, list_runs_of_mission, list_mission_run_paymentsRead what a run has spent, what is left and the units remaining.
log_mission_progressRecord the units done and a note.
complete_mission_run, abandon_mission_runFinish a run, or withdraw one that is still waiting for approval.

x402_pay and transfer_usdc refuse a missionRunId: a payment of a run goes through the …_in_mission tool. Each payment counts against the run envelope. Without a run id a payment is evaluated under the wallet policy alone, unless the policy requires a mission.

What the agent sees​

In agent apps that show cards, the mission tools show the user a card. The request card of a trial or a run shows the plan per source (calls times price, with a subtotal), the estimated cost of a unit against the unit price, the run envelope, the sample size of a trial, and, when a version is already published, what changes from it: a new source, a removed source, a changed plan, a changed price or run envelope. It carries the validation button that leads to the Inbox, then follows the run while it plays. The card of a completed run gives the average cost per unit of that run, what was paid, the number of payments, the units delivered, the table of the sources, and the run envelope. After a successful trial it also carries the button to publish in the dashboard, or says what is missing. Agent apps that show no card get the same facts in text.

How the agent plays a mission​

  1. Write. The agent reads what the wallet already pays and the missions that exist, then creates the draft right away with the sources it proposes and their plan, and a unit price that is the planned cost of one unit plus a margin. It does not ask the user for amounts: the user corrects them in the chat, and the agent applies the corrections with update_mission.
  2. Try. The agent asks the trial right after the draft, then calls wait_for_mission_run until the operator decides. Once the trial is active it plays the sample like a run, without asking again, and completes it. The trial must make at least one payment.
  3. Publish. A person publishes in the dashboard. The agent cannot.
  4. Run. The agent starts a run, waits for its approval when the mode is on_demand, pays with the …_in_mission tools, logs progress, delivers the result, then completes the run.
  5. Optimize. To make a mission cheaper, the agent reads versionStats of the published version to see which source weighs what, looks for a cheaper service, opens a draft of the next version with update_mission, and asks a trial. The card of the completed trial compares the cost per unit.

Refusals of start_mission_run​

  • MISSION_RUN_FREQUENCY_REACHED (409): the wallet used its allowance for the period. params.retryAt is when it may start again, in UTC. Do not retry before.
  • MISSION_RUN_LIMIT_REACHED (409): the mission limits the simultaneous runs per wallet and the wallet reached it. Finish one of your own runs, or tell the user.
  • MISSION_RUN_PENDING (409): in on_demand mode, a run of this mission already waits for approval on this wallet.
  • MISSION_NOT_PUBLISHED (409): nothing is published yet, or the mission is archived.
  • MISSION_RUN_WALLET_OUT_OF_SCOPE (403): the wallet is outside the sharing of the mission.
  • MISSION_RUN_OUT_OF_MISSION (422): the run does not fit the mission, for example a unit price above the mission price, units on a mission without unit, or a currency that differs from the one of the wallet.

A payment that breaks the run envelope, the endpoints and recipients of the mission or the deadline of the run is refused with a policy/… reason. See Refusal reasons.

Limits​

  • A trial cannot declare more units done than its sample.
  • A brief is at most 8000 characters, a title at most 200, and the source and recipient lists at most 50 entries each.
  • An endpoint is written METHOD host/path with a plain path: no query string, no percent-encoding, no . or .. segment. Keyban refuses with MISSION_ENDPOINT_INVALID what it cannot read unambiguously.
  • A run cannot be edited. A run that no longer fits is replaced by a new one.
  • Every amount of a mission is in the display currency of the organization. If the currency of the wallet policy changes after a run starts, the run stops matching and payments are refused.