# Create Session — Browser Use

> Create an agent session, dispatch a task, or dispatch a follow-up task to an existing idle session. See the documentation

- Key: `browser_use-create-session`
- Type: Action (Write)
- Version: 0.0.2
- App: Browser Use (`browser_use`) — https://pipedream.com/apps/browser-use.md
- This page (HTML): https://pipedream.com/apps/browser-use/actions/create-session
- Hints: open-world
- Source: https://github.com/PipedreamHQ/pipedream/blob/master/components/browser_use/actions/create-session/create-session.mjs

## Description

Create an agent session, dispatch a task, or dispatch a follow-up task to an existing idle session. [See the documentation](https://docs.browser-use.com/cloud/api-v3/sessions/create-session)

## Props

| Prop | Type | Required | Description |
|---|---|---|---|
| `task` | `string` | No | Natural-language instruction for the agent. Example: Go to example.com and summarize the pricing page. Required when dispatching to an existing session. |
| `model` | `string` | No | Browser Use agent model. claude-sonnet-4.6 is balanced, claude-opus-4.6 is most capable, and gemini-3-flash is fast and lower cost. |
| `sessionId` | `string` | No | Select a Browser Use agent session or provide a session ID. Options are loaded from the connected account. |
| `keepAlive` | `boolean` | No | If true, the session stays idle after the task completes so it can accept follow-up tasks. |
| `maxCostUsd` | `string` | No | Maximum total session cost in USD. Example: 1.50. |
| `profileId` | `string` | No | Select a Browser Use profile or provide a profile ID. Options are loaded from the connected account. |
| `workspaceId` | `string` | No | Select a Browser Use workspace or provide a workspace ID. Options are loaded from the connected account. |
| `proxyCountryCode` | `string` | No | Lowercase proxy country code for browser traffic. Examples: us, de, jp. Enter none to disable Browser Use's proxy. |
| `outputSchema` | `object` | No | Optional JSON Schema for structured output. Example: {"type":"object","properties":{"price":{"type":"number"},"title":{"type":"string"}}}. |
| `enableScheduledTasks` | `boolean` | No | If true, the agent can create scheduled tasks tied to your project. |
| `sensitiveData` | `object` | No | Optional key-value pairs available to the agent through secure placeholders. Example: {"password":"secret-value"}. Keys are visible to the model; values are hidden but may appear in screenshots if typed into unmasked fields. |
| `enableRecording` | `boolean` | No | If true, Browser Use records the browser session and returns recording URLs after completion. |
| `skills` | `boolean` | No | If true, enables built-in Browser Use agent skills such as file management. |
| `agentmail` | `boolean` | No | If true, provisions a temporary email inbox for the session. |
| `cacheScript` | `string` | No | Controls deterministic script caching. Auto enables caching when the task contains @{{value}} placeholders and a workspace is attached. |
| `useOwnKey` | `boolean` | No | If true, uses your configured LLM provider key instead of Browser Use managed keys. |
| `autoHeal` | `boolean` | No | When script caching is active, validates cached script output and reruns the full agent if the result looks incorrect. |

## Run it

**MCP**

```ts
import { Client } from "@modelcontextprotocol/sdk/client/index.js"
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"
import { PipedreamClient } from "@pipedream/sdk"

const pd = new PipedreamClient({
  projectId: process.env.PIPEDREAM_PROJECT_ID!,
  clientId: process.env.PIPEDREAM_CLIENT_ID!,
  clientSecret: process.env.PIPEDREAM_CLIENT_SECRET!,
  projectEnvironment: "production",
})

const accessToken = await pd.rawAccessToken

const transport = new StreamableHTTPClientTransport(
  new URL("https://remote.mcp.pipedream.net/v3"),
  {
    requestInit: {
      headers: {
        Authorization: `Bearer ${accessToken}`,
        "x-pd-project-id": process.env.PIPEDREAM_PROJECT_ID!,
        "x-pd-environment": "production",
        "x-pd-external-user-id": "{external_user_id}", // any stable ID for this user in your system
        "x-pd-app-slug": "browser_use",
      },
    },
  },
)

const mcp = new Client({ name: "my-agent", version: "1.0.0" })
await mcp.connect(transport)

const { tools } = await mcp.listTools()

// listTools() hands your model this tool's input schema, so it can
// fill the arguments itself:
const result = await mcp.callTool({
  name: "browser_use-create-session",
  arguments: {
    task: "Task",
    model: "Model",
  },
})
```

**TypeScript**

```ts
import { PipedreamClient } from "@pipedream/sdk"

const pd = new PipedreamClient({
  projectId: process.env.PIPEDREAM_PROJECT_ID!,
  clientId: process.env.PIPEDREAM_CLIENT_ID!,
  clientSecret: process.env.PIPEDREAM_CLIENT_SECRET!,
  projectEnvironment: "production",
})

const result = await pd.actions.run({
  id: "browser_use-create-session",
  externalUserId: "{external_user_id}", // any stable ID for this user in your system
  configuredProps: {
    browser_use: { authProvisionId: "apn_xxxxxxx" },
    task: "Task",
    model: "Model",
  },
})

console.log(result)
```

**cURL**

```bash
curl -X POST https://api.pipedream.com/v1/connect/{project_id}/actions/run \
  -H "Content-Type: application/json" \
  -H "X-PD-Environment: production" \
  -H "Authorization: Bearer {access_token}" \
  -d '{
    "external_user_id": "{external_user_id}",
    "id": "browser_use-create-session",
    "configured_props": {
      "browser_use": { "authProvisionId": "apn_xxxxxxx" },
      "task": "Task",
      "model": "Model"
    }
  }'
```

---

- App: https://pipedream.com/apps/browser-use.md · All apps: https://pipedream.com/apps