> 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.

# Invocations

> Hosted AI work that runs inside a browser runtime.

Invocations ask BCTRL-hosted agents to do work inside a runtime. They are different from CDP connections:

* Connections are for external tools like Playwright, Puppeteer, Selenium, and debuggers.
* Invocations are for hosted AI work such as Stagehand or browser-use agent execution.

Browser runtimes allow one active controller. An invocation runs only when no CDP connection lease or other hosted invocation owns the runtime.

## Create an invocation

```ts
const invocation = await runtime.invocations.create({
  provider: "stagehand",
  method: "agent",
  target: { type: "browser_page", page: "active" },
  input: {
    instruction: "Find the invoice total on the current page.",
  },
});
```

Use `target.page: "new"` when the hosted agent should start on a fresh browser page. Stagehand also supports `method: "act"`, `method: "observe"`, and `method: "extract"` for page-level work. Add `files` to stage storage files into the runtime, and add `outputSchema` when the final answer must validate against JSON Schema.

## Wait for completion

```ts
const result = await space.invocations.wait(invocation.id, {
  timeoutMs: 60_000,
});
```

Invocation responses expose the final outcome in `result`. Detailed lifecycle events live in run events.

## Observe the run

Invocations write to the runtime's active run.

```ts
const run = await runtime.currentRun();

const { events } = await run.events.list();
const { commands } = await run.commands.list();
const { artifacts } = await run.artifacts.list();
```

## Related

* [Connections](/sdk/core-concepts/connections)
* [Runs](/sdk/core-concepts/runs)
* [Run Events](/sdk/observability/run-events)