Outside Agent

ONE-CALL macro for a PURE conversational agent that answers the user in a persona, within a safety policy, on some channels. Do NOT use this as the finished shape when the creator provides a fixed list of questions, questionnaire, application, lead form, or intake: use createAgent, fetch the `structured-intake` recipe, and author the questions in top-level `intakeForm` so the compiler supplies deterministic extraction and completeness handling. For a plain conversational agent, give `name`, `purpose` (what it's for), optionally `persona` (its tone/voice) and `safetyPolicy` (boundaries), and `channels` (defaults to ["web"]). It creates the draft AND sets a complete authored config — you do NOT hand-wire the MessageReceived→ComposeReply→MessageGenerated→SendMessage chat chain or attach a messenger/composer capability; the platform's baseline supplies all of that for an `agentic` agent. Returns the created agent + the config it set; then simulateBuild / reviewAgent / publishAgent it like any draft. Use setAuthoredConfig or patchAuthoredConfig afterwards to add capabilities, connectors, or reactive rules. (For a NO-LLM fixed-script bot, use createAgent + setAuthoredConfig with replyMode "deterministic" instead.)

createConversationalAgent

Create a new draft agent for the creator. Provide a `name`. `visibility` defaults to `public` (anyone can chat over web or SMS); pass `visibility: "private"` to make it reachable ONLY by the owner and the E.164 numbers on its allow-list (a private web visitor must sign in; an un-listed SMS sender is ignored). You can also flip visibility later with setAgentVisibility, and manage access with addAllowedNumber. Returns the agent, including its `id` — pass that id to setAuthoredConfig and publishAgent. The result also echoes `ownerId` (the tenant the agent is filed under) and a `manageUrl` Console deep link, so you can confirm WHERE it landed.

createAgent

Delete one capability eval (and its run history) — pass `evalId`. Returns `{ ok: true }`.

deleteCapabilityEval

Permanently remove ONE knowledge-base source — and its indexed chunks — from an agent's knowledge base. Pass `{ agentId, sourceId }`, where `sourceId` is an `id` from getKnowledgeBase's `sources` (or a `sourceId` seedKnowledgeText returned). Use this to CORRECT the base when a fact is disproved or superseded — delete the stale source outright instead of seeding a 'disregard the above' document, which would leave contradictory passages competing in retrieval forever. (seedKnowledgeText already UPSERTS by exact title and gates near-duplicates; reach for delete when there's no clean replacement to re-seed, e.g. dropping a whole obsolete source.) Deleting a FILE source removes the WHOLE file's chunks, not one fact within it. Irreversible — re-seed to restore. No-op-safe: an unknown or already-deleted `sourceId` (or one on an agent you don't own) returns a not-found error. Returns `{ ok: true }`.

deleteKnowledgeSource

Remove a connector from the agent (by `connectorId`). The agent can no longer use that toolkit; existing end-user connections are left untouched.

disableConnector

Dismiss one OPEN flag without converting it — for a one-off the creator confirms needs no guard (a user typo, a transient outage, behavior that is actually correct). Pass `agentId` AND `flagId` (both required; the flag must belong to that agent); returns the resolved flag. Prefer convertFlagToEval when in doubt: a dismissed flag protects nothing, a converted one guards the behavior forever.

dismissFlag

Compile the draft and run it against generated scenarios WITHOUT publishing, returning a COMPACT summary instead of the full traces: `{ scenarioCount, repliedCount, failures, coverage }`, where each failure is `{ scenario, command, target, code, reason }`. This is the fast way to spot a payload/wiring bug — e.g. "every scenario fails on SendMessage because the message field is missing" — without paging through the full cascade. `coverage` is the INVERSE signal: `coverage.rulesNeverFired` lists reactive rules that fired in NO scenario (usually a wrong `when.event`, an unsatisfiable `condition`, or a dangling `then.target`) — treat a non-empty list as likely dead wiring, NOT a pass; `coverage.intentsWithoutScenario` lists behaviorIntents no scenario exercised (usually because the intent has no `examples`, so it was never tested — add one). Drill into simulateBuild only when you need the full trace for one scenario. Read-only.

simulateBuildSummary

Compile the draft and run it against generated scenarios WITHOUT publishing; returns the FULL event-cascade traces per scenario. This can be LARGE — prefer simulateBuildSummary for a compact pass/fail-at-a-glance read, and only call this when you need the full cascade to debug a specific scenario.

simulateBuild

Run the SAME compile + safety/purpose review that publishAgent runs, but WITHOUT publishing — returns `{ canPublish, blockers, findings, validation, delta? }`. simulateBuild only checks behavior (rules → events); this checks publish-readiness, so use it to iterate on review blockers cheaply before going live. `canPublish: true` with no blockers means publishAgent would succeed. `blockers` is the friendly human-facing list; each carries STRUCTURED targeting — `subjectId` (the exact rule/intent/capability id flagged), `subjectKind`, `fieldPath`, and a `quote` of the offending span — so you fix the right thing in one pass instead of guessing which item the review meant. `findings` is the FULL machine shape publishAgent's report carries (id, category, severity: info|warning|blocker, confidence 0..1, summary, evidence[], subjectId, fieldPath, suggestedRemediation, ...) for EVERY severity — so you can iterate blockers off reviewAgent ALONE with no publish round-trip and never under-count. Read verdict STABILITY from `confidence`: a deterministic gate emits confidence 1 (reproducible); a finding with severity "blocker" and confidence < 0.8 is a MARGINAL LLM-judge verdict that did NOT gate publish (it may shift run-to-run). `validation` is core's static validation block (errors/warnings). To track progress across iterations, pass `priorBlockers` (the `blockers` array you got from your LAST reviewAgent call); the result then includes a `delta` of `{ cleared, introduced, kept }` so you can tell whether your last edit helped. The review also dry-runs the draft and promotes a runtime failure (a rule that fails on every message) to a distinct "a rule fails when it runs" blocker, separate from "a behavior has no rule". The result also carries a NON-GATING `bloat` nudge (`{ count, message }`, present only when > 0) counting the config's dead/redundant parts — call `compactAgent` for the full prune report; it never affects `canPublish`. Note the review depends on `replyMode` (a deterministic agent skips the AI judge — see setAuthoredConfig).

reviewAgent

Enable one external connector on the agent so it can act in that third-party app on behalf of the end user. `connectorId` MUST be a real toolkit id (from listConnectors / getConnector) — an id that doesn't exist in the provider's catalog is rejected, so discover it first instead of guessing. Optionally pass `enabledTools` (a subset of the connector's tool slugs) to narrow what the agent may call — recommended for large toolkits (check `toolCount`) so you don't load hundreds of tools into the model. To actually USE the connector in conversation you ALSO need to attach the `connector-tool` capability in setAuthoredConfig, PIN it to this `connectorId`, and choose the ownership `scope` on that instance: `end-user` (each user OAuths their own account at runtime — today's default) or `creator` (the agent uses the creator's single shared account, linked once from the agent config page; users can't override it). That per-connector ownership choice DRIVES connector-tool resolution and lives on the connector-tool INSTANCE (`scope`), so you rarely need `bindingPolicy`. (`bindingPolicy` — `{ default: 'creator'|'none', override: 'forbidden'|'allowed'|'required' }` (ADR 0005) — remains only for native binding flows and is NOT what drives connector-tool resolution: `default` says whether the agent carries a creator-set account (`creator`) or none; `override` says whether an end user may bind their own; `creator`+`forbidden` LOCKS to the creator's one account, `none`+`required` makes every user connect their own, `none`+`forbidden` is invalid; omit it for normal toolkits.) CUSTOM HTTP CONNECTOR (no Composio toolkit needed): to call an API Composio does NOT cover — a carrier/AMS REST API, an internal service — OR to POST to a Zapier catch-hook, pass a `manifest` instead of relying on the catalog: `{ provider: 'http', baseUrl, auth: { type: 'none'|'bearer'|'header', header? }, tools: [{ name, method, path, params?, body?, responseMap? }] }` (auth carries NO secret field — the key is set in the Console, never here). A manifest connector needs NO catalog entry and NO per-end-user OAuth — `connectorId` is YOUR OWN chosen slug (e.g. 'coastal-ams'), the existence check is SKIPPED, and it is callable as soon as enabled (still attach `connector-tool` + PIN the id, with `scope: 'creator'` since a manifest runs as the creator's own credential). In each tool, `path` may contain `{param}` placeholders filled from `params` (a map of name→'string'|'number'|'boolean'); `body` (write methods) is the JSON body fields; `responseMap` projects the raw JSON into clean fields for the agent as `{ outField: '$.json.path' }` (tiny JSONPath — `$.a.b`, `$.arr[0].c`). CREDENTIAL — for `bearer`/`header` auth, DO NOT put a token here: LEAVE `secretRef` UNSET. A raw API key must NEVER pass through this tool — it would enter your context and the transcript. There is a dedicated WRITE-ONLY Console field for the key, so do NOT ask the creator for a secret NAME, do NOT tell them to set a server/env var, and do NOT hunt for an MCP tool to store the secret (there is none) — the creator types the actual key themselves in the Console (agent Configuration → "Connector API keys") AFTER you author the shape. During the interview just ask the auth TYPE (bearer vs a header name); never ask where the key is stored. Author only the SHAPE (`auth: { type: 'bearer' }`, or `{ type: 'header', header: 'X-Api-Key' }`) with no `secretRef`; the connector is then in a PENDING-CREDENTIAL state, and this tool's response returns `credentialRequired` — RELAY it to the creator: they enter the real key in the Console on the agent's Configuration page, under "Connector API keys", which stores it encrypted and mints the handle. Publish is BLOCKED until the key is set. IMPORTANT — the `baseUrl` and each tool's catch-hook `path` ARE creator-specific: when a creator says "post to my Zapier" / "connect my API", ASK for the real hook URL and use it VERBATIM; NEVER invent, guess, or leave a placeholder like `/hooks/catch/<id>/<key>` — but the API KEY is the one thing you do NOT take here (it goes to the Console). A no-auth Zapier hook needs no credential: `auth: { type: 'none' }` and it's usable immediately. And do NOT route a Zapier catch-hook or a plain REST API through listConnectors/Composio — those are custom `http` connectors defined by THIS manifest, not Composio toolkits (listConnectors only covers Composio's OAuth toolkits). Zapier is just an http connector whose tool is a POST to the catch-hook: `{ provider:'http', baseUrl:'https://hooks.zapier.com', auth:{type:'none'}, tools:[{ name:'log_call_note', method:'POST', path:'/hooks/catch/<id>/<key>', body:{ summary:'string', phone:'string' } }] }`. Outbound requests are guarded (only public hosts; loopback/private/link-local are blocked outside dev), and a manifest write is still governed by an `actionBudgets` `connector_write` entry.

enableConnector

Generate the STANDARD BATTERY for behavior intents that don't have one yet: for each intent, the platform writes three scenario evals — a 'happy' path, an 'edge' case, and an 'adversarial' probe (a user actively trying to make the agent violate the requirement) — each linked to its intent, tagged, and persisted with `origin: 'generated'`. Returns `{ generated, alreadyGeneratedIntentIds, unknownIntentIds }` where `generated` is the created evals. The battery is FROZEN once COMPLETE: an intent whose generated cases already cover all three tags is SKIPPED (listed in `alreadyGeneratedIntentIds`), so every config version replays the identical suite and version-to-version score deltas mean the AGENT changed, not the tests. An INCOMPLETE battery (an earlier interrupted write) self-heals: its remnants are replaced with a fresh trio. Delete a generated case to force regeneration. Pass `intentIds` to scope generation; omit it to cover every intent without a battery. This is what gives every requirement a comparable rigor floor. NOTE: runQualitySuite runs this automatically for every uncovered intent before grading, so you rarely need to call it yourself — use it to write tests WITHOUT grading, or with `intentIds` to scope regeneration after deleting a case. This spends model credits, so it is credit-gated.

generateEvalBattery

Resolve one AuthoredConfig recipe by `name` (from listRecipes), returning `{ name, title, description, config }` — a real, schema-valid config skeleton with the wiring already correct. The `config` is a SHAPE TO ADAPT, not a finished agent: replace the placeholder purpose/persona/message text and `<…>` markers, pick real capability ids (cross-check getCatalog) and connectors (listConnectors), then pass it to setAuthoredConfig. Returns null if no such recipe exists. Read-only.

getRecipe

Look up one connector by its toolkit `connectorId` (e.g. from listConnectors, or one you already know like "gmail"). This is the RELIABLE exact-existence check (unlike listConnectors' page-limited substring search). Returns `{ connector, providerMode }`: `connector` carries its `title`, `description`, `categories`, `noAuth`, and `toolCount`, OR is `null` when no such toolkit exists. A genuinely absent slug resolves to `connector: null` — it is NOT an error; an `ok:false` error means an ACTUAL provider failure (timeout/auth/5xx), so retry it rather than concluding the toolkit is missing. `providerMode` makes the null authoritative: `connector: null` proves absence only when `providerMode` is `live-composio` (the real credentialed catalog); on `no-catalog` (keyless dev) EVERY lookup is null and proves nothing. Use it to confirm an id and decide whether to scope `enabledTools` before enableConnector. Read-only.

getConnector

STEP 1 of uploading a large Word (.docx) template for the `docx-fill` capability WITHOUT inlining its bytes. Prefer this over setting `templateBase64` whenever the template is large or dense (a multi-page form, embedded images): a big base64 blob is unreliable to emit verbatim as tool args and bloats every config round-trip. Pass `{ agentId, filename? }`; returns `{ uploadUrl, storagePath, contentType }`. Then, IN YOUR SHELL (the bytes never pass through this tool), upload the local file directly: `curl -X PUT -H "Content-Type: <contentType>" --upload-file <local.docx> "<uploadUrl>"`. The URL is short-lived — upload promptly. Then call `registerDocumentTemplate` with the returned `storagePath` to get the template's placeholders and finish wiring. (Small template, or a dev host with no storage bucket where this tool isn't available? Just set `templateBase64` on the capability config instead.)

createTemplateUploadUrl

Read one of the creator's agents by id (name, status, slug, visibility). Read-only.

getAgent

Get the <script> snippet and step-by-step install instructions to add this agent as a floating chat widget on a website. Requires the agent to be PUBLISHED and to have webWidget.enabled set (turn it on with setAuthoredConfig, then publish). Returns `{ enabled, slug, snippet, scriptUrl, previewUrl, appearance, instructions: { generic, byPlatform, selected? } }`: paste `snippet` just before </body> on every page. Pass an optional `platform` (shopify | wix | wordpress | webflow | squarespace | html) to get tailored steps under `instructions.selected`. If the widget is off or the agent isn't published yet, `snippet` is null and `instructions.generic` says what to do first. Read-only.

getWidgetEmbedCode

Owner-only. Grant a Firebase uid delegated authoring access to this agent; the owner keeps billing + control.

grantEditor

Provision (or retry) the Twilio phone number for a PUBLISHED sms/voice agent, AND the way to READ an agent's number over this surface. Decoupled from publish: publishing kicks issuance off in the background, so call this to check/retry it explicitly — e.g. after publishAgent returned `numberPending`, or after a transient failure. IDEMPOTENT: if the agent already has an active number it is returned unchanged. AREA CODE: pass an optional `areaCode` (a 3-digit NANP code like "305") to bias the search to that area code — the number will be in it or issuance FAILS LOUDLY (`no_inventory_in_area_code`, nothing is bought); omit it to take whatever Twilio inventory is available. To make a FRESH agent auto-issue in a given area code the moment it publishes, set `numberAreaCode` on the authored config instead (setAuthoredConfig) — the background issuance reads it. Returns `{ ok: true, e164, status }`, or `{ ok: false, reason }` — `no_inventory` (no number available at all, try again later), `no_inventory_in_area_code` (the requested area code had none right now — retry later, or the creator can email [email protected] to have a specific DID bought and swapped on), `provisioning_failed` (transient infra, retry), `not_configured` (server is missing Twilio settings — NOT retryable, tell the operator), `agent_not_published` (publish first), `already_has_number` (it already has an active number — this tool NEVER swaps or releases a live number; to change or remove it the creator must email [email protected]). On `already_has_number` the result ALSO carries `e164` + `status` for the existing number (so you can read and hand the creator the agent's number even when the background issuance already provisioned it before you called this); while it's still provisioning, `e164` is null and `status` is `provisioning` — call again shortly.

issueNumber

Read-only LEANNESS report for an already-built agent — coding agents treat every edit as ADDITIVE, so agents accrue dead weight (unreachable capabilities, tables nothing writes to, one-row demo lookups, hardcoded PII, over-declared intents, a near-cap soul) that nothing ever prunes. compactAgent compiles the config and runs the DETERMINISTIC bloat checks (no server LLM, no credit spend), returning `{ ok, headline, provenSafe, needsReview, proseCompaction, summary, note }`. `headline` is an HONEST computed metric — `movingParts`, `vestigialParts`, `movingPartsAfterProvenSafe`, and `promptSurfaceChars` (the model-facing prose weight). STRUCTURAL bloat splits into two buckets: `provenSafe` is PROVABLY-DEAD items whose removal is behavior-neutral (bulk-approvable); `needsReview` is the judgment-call bucket (looks like bloat but may be intentional/roadmap) to approve one at a time. NOTE: bulk-approve is currently gated until the keep-intentional opt-out ships, so `provenSafe` is empty for now and every structural prune arrives in `needsReview` — approve each after confirming it isn't mid-build. Each proposal carries a `code`, the `subjectId` it targets, a human `summary`, and an `applyInstruction`. `proseCompaction` is the SEMANTIC pass: a worksheet of the model-facing prose (`fields` with char weights), the `baselineCoveredIntents` the baseline already covers, cross-field `duplicationHints` (near-duplicates by shared significant tokens, so REWORDED restatements are caught, not just byte-identical copies — each carries `sharedTokens`), and a `rubric` — YOU (this coding agent) reason over it, dedupe across fields, cut verbosity WITHOUT dropping any distinct instruction, and PROPOSE before→after rewrites to the human; the reasoning is yours, there is no second LLM. When every must-have intent is baseline-covered, `note` warns that dropping them ALL empties the requirement ledger (REQUIREMENT_LEDGER_THIN) — keep 2–3 terse musts backed by evals instead. compactAgent WRITES NOTHING: apply an approved prune/rewrite through patchAuthoredConfig/setAuthoredConfig (which gate removals behind acknowledgeDrops/acknowledgeRemovals), then ALWAYS re-run reviewAgent — an INTENT_REGRESSION or DROPPED_REQUIREMENT means you cut something load-bearing, so revert it. Run it after publish, or whenever an agent has grown across many edits.

compactAgent

Discover the TRIGGER types a connector can fire (the inbound/event side — e.g. "a new Google Task was added"). Pass `connectorId` (a real toolkit id from listConnectors). Returns each trigger's `type` (use it in setAuthoredConfig's `connectorTriggers`), `name`, and `description`. A trigger lets the agent ACT ON ITS OWN when something happens in the end user's connected account — distinct from connector tools, which the agent calls on demand. To use one: declare it in `connectorTriggers` AND add a reactive rule with `when: { event: "ConnectorTriggerReceived" }` that does something (notify, call a tool, …). Read-only.

listConnectorTriggers

List the E.164 numbers allowed to reach a PRIVATE agent (oldest first, each with its optional label). The owner is implicitly allowed and is NOT in this list. Read-only.

listAllowedNumbers

List the agent's capability evals with their latest result — pass `agentId` (optionally `instanceId` to scope to one capability). Each returns `{ id, capabilityInstanceId, moduleId, evalKind, name, input, expected, lastScore, lastRunAt, ... }`; `lastScore` (0..1) and `lastRunAt` are null until the eval has been run. Read-only.

listCapabilityEvals

List the run history for one eval, newest first — pass `agentId` AND `evalId` (both required; the eval must belong to that agent). Each run is `{ id, score, output, rationale, judgeModality, configRef, ranAt }`, where `configRef` identifies which config version was exercised (for spotting regressions across edits). Read-only.

listCapabilityEvalRuns

Return the BUILT-IN capability catalog (the palette of skills with their ids, config shapes, and examples) so you use real capability ids, not guesses. PREFER getCatalogSummary first — the FULL catalog serializes every module's JSON Schema plus the worked examples and is large enough to exceed an MCP client's per-result token cap. Pass `moduleIds: ["<id>", …]` to fetch the full JSON Schema for ONLY those modules (discover the ids with getCatalogSummary); omit it only when you truly need the whole palette. For EXTERNAL connectors (Google Calendar, Gmail, a CRM, …), use listConnectors instead — those are enabled separately with enableConnector. Each module also carries the FULL `pitfalls` it declares — its KNOWN failure modes (`code`, `failureMode`, `guidance`, `severity`): how the capability is commonly misused and how to avoid it, so you wire it right the first time (getCatalogSummary lists only `code` + `severity`; this is where the prose lives — the same pitfalls are re-checked at the end-of-build review).

getCatalog

Return the COMPACT capability catalog — per module, the config keys it needs, its commands (with required + accepted payload fields) and the events it emits (the fields a rule can read as `event.<field>`) — WITHOUT the full JSON Schemas. It also carries `valueExprForms`: the full vocabulary a `then.payload` leaf may take — `{const}`, `{object}`, `{template}` (interpolate `{{name}}` placeholders in a string with `vars` — each var itself a value-expr — for a personalized body/message), `{select}` (pick ONE element out of a prior-lookup array by matching a field and return one of its fields — e.g. resolve a user-named list into its real id from a connector's list result, so the model never authors the id and a fabricated one can't flow downstream; no match ⇒ the key is omitted), and every `{ref}` root (`event.`, `endUser.id` — the trusted server-known identity of the person, bind durable keys like a data-table keyField or escalation id to it, `state.`, `settings.`, and `chain.<EventType>.last.payload.<field>` to pull a value from an event emitted EARLIER in the same reactive chain) — so you don't have to infer the ref forms from examples. An order of magnitude smaller than getCatalog: prefer this when you're wiring reactiveRules and just need the field names, and only fall back to getCatalog when you need a full schema. Each module also lists any `pitfalls` it declares — its KNOWN failure modes — but here as `code` + `severity` ONLY (no prose): enough to see THAT a capability has common misuses and how serious. Pull the full `failureMode` + `guidance` for the ones that matter with getCatalog({ moduleIds }) — the same modules you fetch full schemas for when wiring (the same pitfalls are re-checked at the end-of-build review). Read-only.

getCatalogSummary

List the canonical AuthoredConfig RECIPES — known-good starting shapes for common agent patterns (conversational, no-LLM deterministic bot, scheduled reminder, escalating reminder ladder that self-cancels, classify-and-branch routing, human escalation, RSVP/guest list, structured intake (a typed, ordered `intakeForm` that automatically compiles the proven whole-transcript extraction, per-conversation record, focused missing-field recovery, completeness gate, PDF, email, and truthful delivery confirmation), owner-uploaded roster/worklist, per-user scheduled recap, multi-step generate-then-deliver, knowledge-base grounded, connector-trigger reaction). Pass `query` with the task IN YOUR OWN WORDS (e.g. `listRecipes({ query: "chase an overdue invoice until paid" })`, `"answer from our FAQ"`, or `"ask callers these questions and submit their answers"`) and the best-fitting recipes are ranked first; omit it to skim the whole library. A creator-provided fixed question list, questionnaire, application, lead form, or intake MUST use `structured-intake`, not the generic conversational shape. Returns each recipe's `name`, `title`, `description`, and `keywords`. Fetch the full skeleton with getRecipe(name), adapt it (purpose, form fields/groups, verification, delivery, branding), then setAuthoredConfig it. Start here instead of composing a config from scratch. Read-only.

listRecipes

List the interactions the creator FLAGGED while reviewing real conversations on the Console — the feedback inbox this loop drains. Returns the agent's flags newest-first, each `{ id, correlationId, excerpt, note, status, evalId }`: `excerpt` is the transcript span frozen at flag time (`{ role: 'user'|'agent', text }[]` — what actually happened), `note` is the creator's correction (what SHOULD have happened — treat it as the requirement), DISPUTED TESTS: a `correlationId` starting `eval:` flags an EXISTING test from the Quality page's conversation view — the creator read the test's conversation and believes the RUBRIC is wrong, not the agent. For those, review the eval (the id follows `eval:`) and its criteria against the excerpt + note; if the creator is right, FIX THE TEST (replace it via deleteCapabilityEval + addScenarioEval with corrected criteria, or adjust the behaviorIntent) and then dismissFlag — do NOT convertFlagToEval (that would mint a duplicate test), `status` walks 'open' → 'converted' | 'dismissed' (default filter: 'open'; pass `status: 'all'` for history), and `evalId` points at the scenario eval a converted flag became. THE LOOP: a flag is a failing test the agent already failed for real. Process each open flag: (1) read the excerpt + note and decide whether it reveals a MISSING requirement — if so, add a behaviorIntent for it first (setAuthoredConfig/patchAuthoredConfig); (2) convertFlagToEval with sharpened judge criteria and the intent link; (3) fix the config so the behavior actually changes (guidance, soul, rules, or an intent example); (4) runQualitySuite and confirm the flag-derived eval passes AND nothing else regressed; (5) publish. Dismiss (dismissFlag) only what the creator confirms is a one-off. Read-only.

listFlaggedInteractions

Owner-only. List the editors granted authoring access to this agent.

listEditors

List the creator's agents (id, name, status, slug). Read-only.

listAgents

List the connectors currently enabled on the agent (each with its `connectorId` and the `enabledTools` scope, if any). Read-only.

listEnabledConnectors

List every daily sweep configured on this agent — each with its `name`, kind, fire time (`fireHour`/`fireMinute` + `timezone`), connector-list fields (`connectorId`, `listTool`, `listArgs`, `rowsPath`, `phonePath`, `contextPaths`), `instruction`, pacing, and weekday setting. Read-only. Call BEFORE configureDailySweep when unsure what exists: configuring an existing `name` OVERWRITES it, and an agent holds at most 6 sweeps.

listDailySweeps

List the agent's EVAL-able capability instances — the individual steps you can write re-runnable unit tests against. Compiles the DRAFT and returns one entry per instance: `{ instanceId, moduleId, evalKind, judge, supportsDeterministic }`. Use `instanceId` as the `capabilityInstanceId` when you add an eval. `evalKind` is `capability` (feed it an input, score the output) or `tool-selection` (feed the composer a user message, assert which tools it calls). `supportsDeterministic` says whether an exact `deterministic` matcher is allowed; `judge` (`text`|`image`|null) says which model judge scores fuzzy outputs. Read-only.

listEvalTargets

List the valid `then.target` instances for the agent's reactive rules — so you don't have to guess an instance id or probe with a bad rule to learn it. Compiles the DRAFT and returns `{ targets }`, each `{ id, module, emits }`: `id` is a compiled capability instance usable DIRECTLY as a rule's `then.target`, `module` is the capability it runs (for an ATTACHED capability the bare module id — e.g. "messenger" — is ALSO a valid target and additionally enables synchronous payload validation), and `emits` are the event types that instance can produce (wire another rule's `when.event` off one to chain behaviors). The list includes the auto-wired BASELINE instances (the agentic composer + `replier`) and the `escalation` instance when human-in-the-loop is on — targets that aren't in getCatalog and are otherwise undiscoverable. Read-only.

listTargets

List the valid `when.event` values a reactive rule can fire on for this agent — so you don't have to hand-assemble them from getCatalog + the draft, or probe with a bad rule to learn them. Compiles the DRAFT and returns `{ triggerEvents }`, each `{ event, source, emittedBy }`: `event` is the type usable DIRECTLY as a rule's `when.event`; `source` is how it becomes fireable — `builtin` (`MessageReceived`, the universal external chat entry point, always present), `capability` (an event an ATTACHED capability instance emits — `emittedBy` lists the instance ids, so you can chain a rule off another rule's command), `connector-trigger` (`ConnectorTriggerReceived`, present ONLY when a connector trigger subscription is in the draft's `connectorTriggers`), or `signal` (a custom composer signal you declared). An event NOT in this list is unfireable for this draft: attach the capability/connector trigger or declare the signal first. This is the `when.event` companion to listTargets (which lists the valid `then.target`). Read-only.

listTriggerEvents

Apply a PARTIAL update to an already-configured agent without resending the whole config — tightens the iterate loop when you only want to change one field. Pass `agentId` and `set`, an object of the top-level fields to change (e.g. `{ purpose: "…" }`, `{ channels: ["web","sms"] }`, `{ guidance: [...] }`, `{ activityDisplay: "all" }`). Each key in `set` REPLACES that field wholesale (arrays/objects are NOT deep-merged — predictable); fields you omit are left untouched. The merged config is re-validated exactly like setAuthoredConfig (capability ids + reactive-rule payloads are checked, so a bad patch is rejected with the same field-level errors), and the result returns the full merged config plus any `channelAdvisories` and `capabilityAdvisories` (the known pitfalls of the attached capabilities). The agent must already have a config (create it with createAgent/createConversationalAgent and setAuthoredConfig first). PROTECTED REQUIREMENTS: patching `behaviorIntents` to drop or downgrade a published `priority: "must"` intent is rejected unless you pass `acknowledgeRemovals: [<the intent id>]` — the same durable-requirement guard as setAuthoredConfig, so an incremental edit can't silently erase a hard requirement. QUALITY LOOP: after changing an agent's behavior (soul, behaviorIntents, capabilities, guidance), run runQualitySuite and read `rollup.regressions` — it diffs against the previous completed run and shows exactly which requirements your change made WORSE ('newly_failing', 'score_drop', 'requirement_dropped'). New behaviorIntents get their standard test battery written automatically by that same call. Don't publish a change that introduced regressions without either fixing it or telling the creator why it's acceptable.

patchAuthoredConfig

Preview what the DRAFT would do with ONE user message, WITHOUT publishing and WITHOUT the scenario harness — pass `agentId` and `message`. Returns `{ reply, producedTypes, failures }`: the reply the agent would send, the event cascade it triggered (so you can see which rules fired), and any command failures. NOTE: this is a DETERMINISTIC preview — the rule wiring and which capabilities fire are faithful, but the reply TEXT is a stand-in, not the live model's exact wording (that appears once published). Use it to catch a silent agent, a mis-wired rule, or a failing command far faster than a publish round-trip. Read-only.

tryAgent

Arm the draft's AGENT-WIDE standing schedules (declared on the scheduler capability's `config.schedules: [{ label, spec }]`) on the agent-level session and advance its clock, returning each firing's cascade — so you can confirm an agent-wide cadence (a weekly announcement, a daily digest) ARMS and drives its `TimerFired` rule WITHOUT hand-firing a TimerFired. Returns `{ correlationId, until, armed, firings, events, failures? }`: `armed` is what was scheduled, `firings` are the occurrences that fell due (label + 0-based occurrence + firedAt), `events` is the produced cascade (look for the broadcast/digest each firing drove). Omit `until` for a deterministic default window (35 days past each schedule's anchor); pass an ISO `until` for a specific horizon. `armed: []` means no standing schedules are configured. Read-only — nothing is persisted or sent.

previewSchedule

Compile the agent's guidance into runtime policies, run the full safety review, and publish it to the web. On success returns the public link (the creator can share it immediately). Phone numbers are DECOUPLED from publish: when the agent has an sms/voice channel, publishing KICKS OFF number issuance in the background and returns `numberPending: true` — it does NOT wait for or fail on the number. Call `issueNumber` to check/retry the number (it's idempotent), or read it later via getAgent. If the review blocks publishing, returns the blockers to fix — adjust the config and call again. PENDING RESULT: the safety review runs server-side; if it hasn't finished within the in-request window, this returns `{ pending: true, agentId, buildId }` (NOT an error and NOT a timeout — the build keeps running). When you get that, call `getPublishStatus` with the returned `agentId` AND `buildId` to read the final outcome; do NOT re-call publishAgent (that starts a NEW build). AFTER PUBLISH: the platform re-grades the published agent automatically in the background (the same suite runQualitySuite runs); call getQualityReport a few minutes later to read the fresh grade and its `regressions`, and treat a post-publish regression as a bug to fix, not noise.

publishAgent

Force the agent's LIVE conversations onto a specific published build NOW — the opt-in override for an urgent or safety fix. By DEFAULT a re-publish does NOT touch conversations already in flight: each one stays pinned to the build it started on and only re-resolves to the latest at its own idle gap or continue-as-new boundary (and even then only if the change is compatible). This tool is the deliberate firehose for when you can't wait for that. Pass `{ agentId, buildId, mode? }` where `buildId` is the TARGET build (the one you just published — read it from getAgent / the publish result). `mode` is `"compatible-only"` (the DEFAULT — safe): a conversation the target build is BREAKING for (it would strand that conversation's accumulated in-flight state) is SKIPPED and reported back, never migrated; only compatible conversations are swapped. `mode: "all"` is the explicit DATA-LOSS override: it migrates EVERY conversation including breaking ones, and lists each breaking one under `dataLossOverrides` so the loss is on record — use it only when the fix is more important than the in-flight state. Returns a compatibility report `{ buildId, total, migrated, skipped, endedOrIdle, skippedReasons: [{ correlationId, reasons }], dataLossOverrides? }`: `migrated` got the swap, `skipped` were breaking (compatible-only), `endedOrIdle` had already ended (nothing to migrate — they pick up the latest on their next turn anyway), and `skippedReasons` explains WHY each was breaking. A migrated conversation swaps forward-only (its future turns use the new build; past events are never re-folded) and surfaces a DefinitionUpgraded event on its next turn.

forceMigrateLiveConversations

Read the agent's EVAL COVERAGE at a glance — which capability steps have re-runnable unit tests, which steps are still UNTESTED, and which existing evals never ran, are failing, or are orphaned — so you close the gaps instead of re-deriving them from listEvalTargets + listCapabilityEvals. Compiles the DRAFT and returns `{ targets, orphanedEvals, summary }`. Each target is an eval-able instance (same shape as listEvalTargets) plus its rolled-up cases: `evalCount`, `neverRunCount` (authored but never executed), `failingCount` (last score < 0.7), and `evals` (each case's id, name, lastScore, lastRunAt). An UNCOVERED target (`evalCount: 0`) carries a `suggestion` — a concrete first case to author for that step (the right input shape and expectation kind). `orphanedEvals` are cases whose target instance no longer exists in the current draft (left behind by a config edit) — delete them or re-add them against the new instance id. `summary` totals it: `{ targetCount, coveredCount, uncoveredCount, evalCount, neverRunCount, failingCount, orphanedCount }`. Workflow to CLOSE a gap: getEvalCoverage → addCapabilityEval for each uncovered target (start from its `suggestion`) → runCapabilityEval to score each new case → getEvalCoverage again to confirm `uncoveredCount: 0` and nothing failing. Read-only.

getEvalCoverage