Skip to main content
Glama
yinnho

AginxBrowser

by yinnho
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Rust

session_create

Create a persistent interactive browser session for multi-step workflows such as logging in, filling forms, and clicking through pages. Returns a session ID and preserves login state across idle time and server restarts.

Instructions

Create a persistent interactive browser session for multi-step interaction - clicking, typing, scrolling, reading state across page transitions. Use when the agent must INTERACT with a page (login flows, forms, pagination, click-through) rather than read it once. Returns session_id; persists 8 min idle. With persistent:true the login state survives idle eviction and server restarts - the same session_id revives logged-in.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
urlNoInitial URL to navigate to (optional). `start_url` is honored as an alias (#115) — callers guessing that name must not land on about:blank.
widthNoInitial viewport width in CSS pixels. Pinned for the session's life (survives navigation) so element rects and media queries anchor to the same layout across every page of the visit.
heightNoInitial viewport height in CSS pixels.
mobileNoMobile device emulation (coarse pointer, no hover) for the initial viewport.
accountNoRun as a named login identity (the multi-account layer): a private cookie jar seeded from the account record, write-back to the account store after every action. Concurrent logins (`taobao-scraper` vs `taobao-publisher`) never clobber each other. The account record survives the session — a later create with the same name picks up the warm jar. 1-64 chars of [a-zA-Z0-9_-].
cookiesNoCookies to inject before navigation: `"name=value"` strings or CDP-style objects `{"name","value","domain",...}`. Lets the session start already logged-in. Round-trips with session_cookies.
storageNoWeb Storage to inject after the initial navigation lands: {"local_storage": {"k":"v"}, "session_storage": {"k":"v"}}. For login states that live in localStorage rather than the cookie jar. Round-trips with session_storage.
ttl_secsNoIdle time-to-live in seconds before the session is evicted (default: 480, clamped 60..3600). Raise it for long workflows.
keepaliveNoExempt the session from the idle reaper: it lives until session_close or server exit, so a workflow interrupted by long non-browser steps keeps its login state.
use_proxyNoRoute through proxy (default: false)
persistentNoPersist the login state (cookies + localStorage/sessionStorage + viewport + dialog policy) to the server's local store after every action. If the session idles out — or the whole server restarts — the next call with the same session_id revives it logged-in (storageState-style recovery, no re-login). Explicit session_close drops the snapshot.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.5.8
    • changedInput schema / properties / url / description
      Previous value: -"Initial URL to navigate to (optional)"New value: +"Initial URL to navigate to (optional). `start_url` is honored as an\nalias (#115) — callers guessing that name must not land on about:blank."
  2. Changed2 schema fields changedv0.5.1
    • addedInput schema / properties / account
      Added value: +{
+  "default": null,
+  "description": "Run as a named login identity (the multi-account layer): a private\ncookie jar seeded from the account record, write-back to the account\nstore after every action. Concurrent logins (`taobao-scraper` vs\n`taobao-publisher`) never clobber each other. The account record\nsurvives the session — a later create with the same name picks up\nthe warm jar. 1-64 chars of [a-zA-Z0-9_-].",
+  "type": [
+    "string",
+    "null"
+  ]
+}
    • removedInput schema / title
      Removed value: -"SessionCreateParams"
  3. Changed6 schema fields changedv0.3.0
    • changedInput schema / properties / cookies / description
      Previous value: -"Cookies to inject before navigation ([\"name=value\", ...]). Lets the\nsession start already logged-in. Round-trips with session_cookies."New value: +"Cookies to inject before navigation: `\"name=value\"` strings or\nCDP-style objects `{\"name\",\"value\",\"domain\",...}`. Lets the session\nstart already logged-in. Round-trips with session_cookies."
    • addedInput schema / properties / height
      Added value: +{
+  "description": "Initial viewport height in CSS pixels.",
+  "format": "uint32",
+  "minimum": 0,
+  "type": [
+    "integer",
+    "null"
+  ]
+}
    • addedInput schema / properties / keepalive
      Added value: +{
+  "default": false,
+  "description": "Exempt the session from the idle reaper: it lives until\nsession_close or server exit, so a workflow interrupted by long\nnon-browser steps keeps its login state.",
+  "type": "boolean"
+}
    • addedInput schema / properties / mobile
      Added value: +{
+  "default": false,
+  "description": "Mobile device emulation (coarse pointer, no hover) for the initial\nviewport.",
+  "type": "boolean"
+}
    • addedInput schema / properties / persistent
      Added value: +{
+  "default": false,
+  "description": "Persist the login state (cookies + localStorage/sessionStorage +\nviewport + dialog policy) to the server's local store after every\naction. If the session idles out — or the whole server restarts —\nthe next call with the same session_id revives it logged-in\n(storageState-style recovery, no re-login). Explicit session_close\ndrops the snapshot.",
+  "type": "boolean"
+}
    • addedInput schema / properties / width
      Added value: +{
+  "description": "Initial viewport width in CSS pixels. Pinned for the session's life\n(survives navigation) so element rects and media queries anchor to\nthe same layout across every page of the visit.",
+  "format": "uint32",
+  "minimum": 0,
+  "type": [
+    "integer",
+    "null"
+  ]
+}
  4. First observed

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations provide only a title with no readOnly/destructive hints, so the description carries the full burden. It discloses key behavioral traits: the session is persistent and interactive, idles out after 8 minutes, and with persistent:true the login state survives both idle eviction and server restarts with the same session_id reviving logged-in. It does not mention rate limits, resource cleanup, or explicit side-effects beyond persistence, but covers the most important behavior for an agent deciding to repeat or retain sessions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences and every sentence earns its place: the first defines the tool, the second gives the usage rule, and the third explains the persistence option. It is front-loaded with purpose and usage. Slight redundancy with schema defaults (8 min vs ttl_secs default 480) keeps it from being as tight as the two-sentence high-calibration example, but it remains efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is complex (11 optional parameters, no output schema, no annotations except title), yet the description covers the essential top-level context: what the session is for, when to use it, idle timeout, persistence, and that it returns a session_id. All parameter details are in the fully covered schema, so nothing critical is missing for an agent to invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the input schema already documents all 11 parameters in detail. The description adds minimal parameter-specific value beyond echoing persistent behavior (persistent:true, 8 min idle), which is already expressed in the ttl_secs and persistent parameter descriptions. Baseline 3 is appropriate because the schema carries the parameter semantics completely.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Create a persistent interactive browser session for multi-step interaction - clicking, typing, scrolling, reading state across page transitions.' It then explicitly contrasts with read-only use cases ('rather than read it once'), which distinguishes it from sibling tools like fetch, search, and read-only session tools without needing to open their schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description states precisely when to use the tool: 'Use when the agent must INTERACT with a page (login flows, forms, pagination, click-through) rather than read it once.' It also gives conditional guidance for persistent:true, explaining when the login state survives eviction and server restarts. This provides clear context and an explicit exclusion (not for one-time reads), even without naming a specific alternative tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools