Core Concepts

Invocations

View as Markdown

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

1const invocation = await runtime.invocations.create({
2  provider: "stagehand",
3  method: "agent",
4  target: { type: "browser_page", page: "active" },
5  input: {
6    instruction: "Find the invoice total on the current page.",
7  },
8});

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

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

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.

1const run = await runtime.currentRun();
2
3const { events } = await run.events.list();
4const { commands } = await run.commands.list();
5const { artifacts } = await run.artifacts.list();