Headless dispatch with BYOA work types

Install and publish the three BYOA templates, dispatch a run by project + goal + workType through the external facade, and read the result with get_receipt.

BYOA (Bring-Your-Own-Agent) dispatch lets an external caller - anything authenticated with an org API key, not a Rensei-launched session - fire a governed agent run against one of three built-in work types and poll for its outcome. This page covers the templates, the prerequisites that make a dispatch actually resolvable, and how to read the result. For the wire-level tool contract (arguments, JSON-RPC framing, rate limits), see BYOA MCP Facade; for the rest of the external facade (code intelligence, A2A), see Use Rensei from any agent session.

The three BYOA templates

Each work type maps to its own official, independently installable workflow template:

`workType`	Template slug	Template name	Use for
`research` (default)	`byoa-research-request`	BYOA Research Request	Analysis, investigation, spike
`implement`	`byoa-implement-request`	BYOA Implement Request	Code changes, feature work
`review`	`byoa-review-request`	BYOA Review Request	PR/diff review, audit

Install and publish a template into a project

A template must be installed into your project and published before it can be dispatched - an installed-but-unpublished workflow does not resolve.

Template install is a humans-only write: it runs through a WorkOS user session (dashboard or CLI browser login), never an rsk_* API key or a requester-registration credential. Provision the templates once from a human session; dispatch afterward is the part an API key can do.

Install. From app.rensei.ai, open your project, go to Workflows > Templates, and install each BYOA template you need (or POST /api/templates/{slug}/install/{version} with your projectId, from a human-authenticated session).
Publish. A fresh install lands as a draft. Open the installed workflow in the editor and click Publish, or POST /api/workflows/{workflowId}/publish - see Publish & Deploy for the full draft/publish/deploy lifecycle. Only published workflows are dispatchable.
Confirm. Call the list_workflows MCP tool (see below) - each installed, published BYOA template appears with its workType.

Dispatching

Once at least one BYOA template is published in the project, dispatch through the facade's dispatch tool - project (slug or id), goal (free text), and workType:

curl -s -X POST https://app.rensei.ai/api/cli/mcp \
  -H "Authorization: Bearer $RENSEI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "dispatch",
      "arguments": {
        "project": "my-project",
        "goal": "Implement a /health endpoint and cover it with a test.",
        "workType": "implement"
      }
    }
  }'

The result (JSON-stringified inside result.content[0].text) returns { instanceId, sessionId, receiptUrl, streamUrl } - keep instanceId, it is what you poll with get_receipt. See BYOA MCP Facade > Dispatching an agent for the full argument reference, including the workflow argument that targets any published workflow by slug or id, not only the three BYOA templates.

Dispatch runs headless, non-interactively, end to end. An interactive session - one you can prompt and steer turn by turn - cannot be launched by an API key at all; it requires a human WorkOS user identity, the same humans-only rule that gates template install. If an external request genuinely needs a human in the loop, model that as an approval step inside the authored workflow itself (an approval/gate node the workflow pauses on) rather than expecting the API key to open an interactive session - the workflow's approval gate is the human-in-the-loop path available to an external caller.

Prerequisites for a resolvable dispatch

A dispatch call can succeed at the facade layer (auth, scope, project, Cedar policy) and still have nothing to run the agent with, if the project has no way to resolve a model. Three things need to exist before a dispatch is actually resolvable:

An org credential for the model provider. A stored credential (BYOK secret, or a metered/shared auth mode with no secret to store) for the provider you want the run to use. See Credentials Overview.
A model profile carrying that credential. A profile names a provider + model + auth mode + credential. See Model Catalog & Routing > Profiles.
A profile assignment keyed by the right work type. This is the step most external integrators miss, because BYOA's dispatch workType (research / implement / review) is not the key the profile-assignment lookup uses.

Why the workType you dispatch with is not the workType you route with

Each BYOA template dispatches through a system agent card whose own workType field uses the platform's canonical work-type vocabulary (the same one SDLC phases use: research, development, QA, acceptance, ...) rather than the three BYOA dispatch names. The card-level workType is what a run actually resolves a model profile against:

BYOA dispatch `workType`	Agent-card `workType` (what profile assignments key on)
`research`	`research`
`implement`	`development`
`review`	`qa`

Set up work-type routing (Settings > Model Profiles > Work-Type Routing, org or project scope) for research, development, and qa - not for implement/review - or those two dispatch types fall through to whatever your org/project default profile resolves to, silently.

Reading the outcome

Poll get_receipt with the instanceId from dispatch. The run's state lives in sessionStatus (pending -> running -> a terminal value: completed, failed, stopped, or cancelled):

curl -s -X POST https://app.rensei.ai/api/cli/mcp \
  -H "Authorization: Bearer $RENSEI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "get_receipt",
      "arguments": { "instanceId": "inst_abc123" }
    }
  }'

See BYOA MCP Facade > Polling for the receipt for the recommended back-off and BYOA MCP Facade > Receipt verification for checking the receipt's Ed25519 audit signature.

BYOA MCP Facade - the full dispatch tool contract, rate limits, troubleshooting
Use Rensei from any agent session - the rest of the external facade (code intelligence, A2A)
Publish & Deploy - the draft/publish/deploy lifecycle template installs land in
Model Catalog & Routing - profiles, work-type routing, and the routing cascade
Credentials Overview - provider credentials and auth modes