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

# Sessions

> Learn about MultiOn sessions

## What is an agent session?

![Session Lifecycle](/_fern-img/3f95908ef203a205b87a3ebbf65c8c585edeab1e354e6e06430b3681ff1bacfa.webp)

An agent session is a stateful instance of interaction with our agent for a specific user query or workflow. Each agent session is fully isolated and can be used to perform multiple sequential steps. When a session is created with a command, the agent generates a plan to complete the command.

With [browse](/autonomous-api/browse), the agent will step automatically until the action is completed or the agent requires additional input. With [step session](/step-api/sessions/step), you can supply additional information to refine the plan and help the agent at each step.

* **Session lifecycle:** An agent session begins when you initiate it with an input URL and an instruction prompt and ends when it has been closed or the session has expired. A session survives for 10 minutes if left inactive.
* **Local mode:** By default, sessions are hosted remotely in the cloud using our virtual headless browser. In local mode, our server-hosted agent interacts with your installed Chrome browser extension. Learn more [here](/learn/browser-extension).
* **Security:** In remote mode, each agent session is fully isolated, protecting the integrity of your data and interactions.

## Browse automatically

[Browse](/autonomous-api/browse) allows you to automatically create an agent session with a URL and a command. It will step through the session until the action is completed or the agent requires additional input.

#### TypeScript

```ts
import { MultiOnClient } from "multion";

const multion = new MultiOnClient({ apiKey: "YOUR_API_KEY" });

const browseResponse = await multion.browse({
  cmd: "Find the top comment of the top post on Hackernews.",
  url: "https://news.ycombinator.com/"
});
```

#### Python

```python
from multion.client import MultiOn

client = MultiOn(
    api_key="YOUR_API_KEY"
)

browse_response = client.browse(
    cmd="Find the top comment of the top post on Hackernews.",
    url="https://news.ycombinator.com/"
)
```

## Create a session manually

[Create session](/step-api/sessions/create) allows you to manually create an agent session with a URL. You can continue the session using the `session_id` returned in the response.

#### TypeScript

```ts
import { MultiOnClient } from "multion";

const multion = new MultiOnClient({ apiKey: "YOUR_API_KEY" });

const createResponse = await multion.sessions.create({
  url: "https://news.ycombinator.com/"
});

const sessionId = createResponse.sessionId;
```

#### Python

```python
from multion.client import MultiOn

client = MultiOn(
    api_key="YOUR_API_KEY"
)

create_response = client.sessions.create(
    url="https://news.ycombinator.com/"
)

session_id = create_response.session_id
```

### Local mode

Use the `local` flag to run the agent locally on your browser. Make sure the [browser extension](/learn/browser-extension) is installed and **API Enabled** is checked.

#### TypeScript

```ts
const createResponse = await multion.sessions.create({
  url: "https://news.ycombinator.com/",
  local: true
});
```

#### Python

```python
create_response = client.sessions.create(
    url="https://news.ycombinator.com/",
    local=True
)
```

### Speed modes

Use the `mode` param to specify the speed model of the agent. This setting determines which LLM model is used under the hood, affecting the balance between processing speed and task complexity:

* `standard`: Optimized for complex tasks that require more detailed analysis or multi-step reasoning.
* `fast`: Suitable for general tasks and quicker responses, ideal for simpler queries or when speed is a priority.

Choose the mode that best fits your specific use case and performance requirements.

#### TypeScript

```ts
const createResponse = await multion.sessions.create({
  url: "https://news.ycombinator.com/",
  mode: "fast"
});
```

#### Python

```python
create_response = client.sessions.create(
    url="https://news.ycombinator.com/",
    mode="fast"
)
```

### Use proxy

Use the `use_proxy` flag to enable proxy for the session to bypass IP blocks and bot protections. When enabled, the agent will be slightly slower to respond.

#### TypeScript

```ts
const createResponse = await multion.sessions.create({
  url: "https://news.ycombinator.com/",
  useProxy: true
});
```

#### Python

```python
create_response = client.sessions.create(
    url="https://news.ycombinator.com/",
    use_proxy=True
)
```

## Step through a session

[Step session](/step-api/sessions/step) allows you to step through an agent session with a command. It will return a response with the status of the agent. Status can be one of `CONTINUE`, `ASK_USER`, and `DONE`. If the status is `ASK_USER`, you can provide additional information to the agent in the `cmd` field.

#### TypeScript

```ts
const stepResponse = await multion.sessions.step("session_id", {
  cmd: "Find the top comment of the top post on Hackernews."
});

const status = stepResponse.status
```

#### Python

```python
step_response = client.sessions.step(
    session_id="session_id",
    cmd="Find the top comment of the top post on Hackernews."
)

status = step_response.status
```

You can keep stepping through the session until the status is `ASK_USER` or `DONE`.

#### TypeScript

```ts
let status = "CONTINUE";

while (status === "CONTINUE") {
  const stepResponse = await multion.sessions.step("session_id", {
    cmd: "Find the top comment of the top post on Hackernews."
  });
  status = stepResponse.status
  // Do something if status is "ASK_USER"
  // Do something else if status is "DONE"
}
```

#### Python

```python
status = "CONTINUE"

while status == "CONTINUE":
    step_response = client.sessions.step(
        session_id="session_id",
        cmd="Find the top comment of the top post on Hackernews."
    )
    status = step_response.status
    # Do something if status is "ASK_USER"
    # Do something else if status is "DONE"
```

### Get session screenshot

Use the `include_screenshot` flag to include a screenshot URL of the session in the response.

#### TypeScript

```ts
const stepResponse = await multion.sessions.step("session_id", {
  cmd: "Find the top comment of the top post on Hackernews.",
  includeScreenshot: true
});

const screenshot = stepResponse.screenshot
```

#### Python

```python
step_response = client.sessions.step(
    session_id="session_id",
    cmd="Find the top comment of the top post on Hackernews.",
    include_screenshot=True
)

screenshot = step_response.screenshot
```

## Close a session manually

To close a session before it expires, use [close session](/step-api/sessions/close).

#### TypeScript

```ts
await multion.sessions.close("session_id");
```

#### Python

```python
client.sessions.close(
    session_id="session_id"
)
```