> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://platform.bctrl.ai/llms.txt.
> For full documentation content, see https://platform.bctrl.ai/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://platform.bctrl.ai/_mcp/server.

# Invocations

> Hosted agent work BCTRL runs inside a runtime - act, observe, extract, and browser-use.

An **invocation** is hosted agent work BCTRL runs inside a runtime. Rather than driving the browser yourself over CDP, you describe what you want in natural language and BCTRL executes it: a single Stagehand action, a structured extraction, or a multi-step browser-use agent.

Invocations are durable, cancellable, and awaitable. You create them against a runtime (live control) and read their history from the run (observability).

## Create and wait

`createAndWait` creates the invocation and polls until it finishes - the common case when you just want the result.

```ts
import { z } from "zod";

const invocation = await bctrl.runtimes.invocations.createAndWait(
  runtime.id,
  {
    action: "extract",
    instruction: "Extract the invoice total.",
    schema: z.object({ total: z.number() }),
  },
  { timeoutMs: 60_000 }
);

console.log(invocation.status, invocation.output);
```

Pass a Zod schema as `schema` and the SDK converts it to JSON Schema on the wire and validates the output. The `timeoutMs` option is your client-side wait budget across long-poll requests.

## Actions

Every invocation has an `action`. The lower-level `create` takes the action directly:

```ts
const inv = await bctrl.runtimes.invocations.create(runtime.id, {
  action: "act",
  instruction: "Click the export button.",
});
```

| Action           | What it does                                        |
| ---------------- | --------------------------------------------------- |
| `act`            | Perform one natural-language action on the page.    |
| `observe`        | Inspect the page and return Stagehand guidance.     |
| `extract`        | Pull structured data, optionally against a schema.  |
| `stagehandAgent` | Run a multi-step Stagehand agent flow.              |
| `browserUse`     | Run a browser-use agent task.                       |
| `solveCaptcha`   | Solve a [CAPTCHA](/sdk/captcha) on the active page. |

## Typed helpers

Stagehand and browser-use actions have typed helpers so you do not write the `action` field by hand:

```ts
// Stagehand
await bctrl.runtimes.invocations.stagehand.act(runtime.id, {
  instruction: "Click the export button.",
});

await bctrl.runtimes.invocations.stagehand.extract(runtime.id, {
  instruction: "Extract the invoice total.",
  schema: z.object({ total: z.number() }),
});

await bctrl.runtimes.invocations.stagehand.agent(runtime.id, {
  instruction: "Download every invoice from the last quarter.",
  maxSteps: 30,
});

// browser-use
await bctrl.runtimes.invocations.browserUse.agent(runtime.id, {
  instruction: "Find the cheapest flight and add it to the cart.",
  maxSteps: 50,
});
```

Helpers accept a saved [AI provider](/sdk/ai-providers) (`aiProviderId`), [toolsets](/sdk/tools) (`toolsetId`, `toolIds`), and per-call knobs like `model` and `temperature`.

## Create, then wait separately

For long-running agents, create now and await later - or cancel:

```ts
const inv = await bctrl.runtimes.invocations.create(runtime.id, {
  action: "browserUse",
  instruction: "Reconcile this month's transactions.",
});

const result = await bctrl.runtimes.invocations.wait(runtime.id, inv.id, {
  timeoutMs: 30_000,
});

// or stop it
await bctrl.runtimes.invocations.cancel(runtime.id, inv.id);
```

## Read invocation history

Invocations belong to a [run](/sdk/runs). Read them from the run side:

```ts
const { data } = await bctrl.runs.invocations.list(runId);
const one = await bctrl.runs.invocations.get(runId, inv.id);
```

## Next

* [Hosted agents](/sdk/hosted-agents) - Stagehand and browser-use in depth
* [AI Providers](/sdk/ai-providers) - bring your own model keys
* [Schema authoring](/sdk/essentials) - Zod and JSON Schema output