Sessions

What is an agent session?

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, the agent will step automatically until the action is completed or the agent requires additional input. With step session, 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.
• Security: In remote mode, each agent session is fully isolated, protecting the integrity of your data and interactions.

Browse automatically

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.

1
import { MultiOnClient } from "multion";
2
3
const multion = new MultiOnClient({ apiKey: "YOUR_API_KEY" });
4
5
const browseResponse = await multion.browse({
6
  cmd: "Find the top comment of the top post on Hackernews.",
7
  url: "https://news.ycombinator.com/"
8
});

Create a session manually

Create session allows you to manually create an agent session with a URL. You can continue the session using the session_id returned in the response.

1
import { MultiOnClient } from "multion";
2
3
const multion = new MultiOnClient({ apiKey: "YOUR_API_KEY" });
4
5
const createResponse = await multion.sessions.create({
6
  url: "https://news.ycombinator.com/"
7
});
8
9
const sessionId = createResponse.sessionId;

Local mode

Use the local flag to run the agent locally on your browser. Make sure the browser extension is installed and API Enabled is checked.

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

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.

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

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.

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

Step through a session

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

1
const stepResponse = await multion.sessions.step("session_id", {
2
  cmd: "Find the top comment of the top post on Hackernews."
3
});
4
5
const status = stepResponse.status

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

1
let status = "CONTINUE";
2
3
while (status === "CONTINUE") {
4
  const stepResponse = await multion.sessions.step("session_id", {
5
    cmd: "Find the top comment of the top post on Hackernews."
6
  });
7
  status = stepResponse.status
8
  // Do something if status is "ASK_USER"
9
  // Do something else if status is "DONE"
10
}

Get session screenshot

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

1
const stepResponse = await multion.sessions.step("session_id", {
2
  cmd: "Find the top comment of the top post on Hackernews.",
3
  includeScreenshot: true
4
});
5
6
const screenshot = stepResponse.screenshot

Close a session manually

To close a session before it expires, use close session.

1
await multion.sessions.close("session_id");