create_browser_session

Instructions

Implementation Reference

• servers/agentql/server.py:1295-1337 (handler)

  The async handler function for the 'create_browser_session' tool, decorated with @mcp.tool(). It validates inputs using Pydantic models, calls the AgentQL API endpoint POST /v1/tetra/sessions, and returns the response. Accepts parameters: browser_ua_preset, browser_profile, shutdown_mode, inactivity_timeout_seconds, proxy, sub_user_id.

  @mcp.tool()
  async def create_browser_session(
      browser_ua_preset: Literal["windows", "macos", "linux"] | None = Field(None, description="The operating system user agent preset the browser will identify as, affecting how websites perceive the client environment."),
      browser_profile: Literal["light", "stealth", "tf-browser"] | None = Field(None, description="The browser profile determining capability and detection resistance: 'light' prioritizes speed with minimal overhead, 'stealth' enables full anti-detection features, and 'tf-browser' uses a custom TF Browser configuration."),
      shutdown_mode: Literal["on_disconnect", "on_inactivity_timeout"] | None = Field(None, description="Controls session teardown behavior on disconnect: 'on_disconnect' immediately stops the session when all connections close, while 'on_inactivity_timeout' keeps the session alive to allow reconnection until the inactivity timeout elapses."),
      inactivity_timeout_seconds: int | None = Field(None, description="How long the session remains alive without active connections before being shut down, applicable when shutdown_mode is 'on_inactivity_timeout'. Accepts values between 5 seconds and 86400 seconds (24 hours).", ge=5, le=86400),
      proxy: _models.TetraProxy | _models.CustomProxy | None = Field(None, description="Proxy server configuration to route browser traffic through for this session, such as host, port, protocol, and credentials."),
      sub_user_id: str | None = Field(None, description="An optional identifier used to associate this session with a specific sub-user within your account, useful for tracking and auditing sessions across multiple users."),
  ) -> dict[str, Any] | ToolResult:
      """Creates a new Tetra browser session with configurable user agent, profile, proxy, and lifecycle settings. Returns session details needed to connect and interact with the browser."""
  
      # Construct request model with validation
      try:
          _request = _models.CreateSessionV1TetraSessionsPostRequest(
              body=_models.CreateSessionV1TetraSessionsPostRequestBody(browser_ua_preset=browser_ua_preset, browser_profile=browser_profile, shutdown_mode=shutdown_mode, inactivity_timeout_seconds=inactivity_timeout_seconds, proxy=proxy, sub_user_id=sub_user_id)
          )
      except pydantic.ValidationError as _validation_err:
          logging.error(f"Parameter validation failed for create_browser_session: {_validation_err}")
          raise ValueError(f"Invalid parameters: {_validation_err.errors()}") from _validation_err
  
      # Extract parameters for API call
      _http_path = "/v1/tetra/sessions"
      _http_body = _request.body.model_dump(by_alias=True, exclude_none=True) if _request.body else None
      _http_headers = {}
  
      # Inject per-operation authentication
      _auth = await _get_auth_for_operation("create_browser_session")
      _http_headers.update(_auth.get("headers", {}))
  
      _request_id = str(uuid.uuid4())
      _log_tool_invocation("create_browser_session", "POST", _http_path, _request_id)
  
      # Execute request (returns normalized dict and status code)
      _response_data, _ = await _execute_tool_request(
          tool_name="create_browser_session",
          method="POST",
          path=_http_path,
          request_id=_request_id,
          body=_http_body,
          headers=_http_headers,
      )
  
      return _response_data

• servers/agentql/_models.py:48-58 (schema)

  Pydantic request models for the create_browser_session operation: CreateSessionV1TetraSessionsPostRequestBody (with fields browser_ua_preset, browser_profile, shutdown_mode, inactivity_timeout_seconds, proxy, sub_user_id) and CreateSessionV1TetraSessionsPostRequest wrapper.

  # Operation: create_browser_session
  class CreateSessionV1TetraSessionsPostRequestBody(StrictModel):
      browser_ua_preset: Literal["windows", "macos", "linux"] | None = Field(default=None, description="The operating system user agent preset the browser will identify as, affecting how websites perceive the client environment.")
      browser_profile: Literal["light", "stealth", "tf-browser"] | None = Field(default=None, description="The browser profile determining capability and detection resistance: 'light' prioritizes speed with minimal overhead, 'stealth' enables full anti-detection features, and 'tf-browser' uses a custom TF Browser configuration.")
      shutdown_mode: Literal["on_disconnect", "on_inactivity_timeout"] | None = Field(default=None, description="Controls session teardown behavior on disconnect: 'on_disconnect' immediately stops the session when all connections close, while 'on_inactivity_timeout' keeps the session alive to allow reconnection until the inactivity timeout elapses.")
      inactivity_timeout_seconds: int | None = Field(default=None, description="How long the session remains alive without active connections before being shut down, applicable when shutdown_mode is 'on_inactivity_timeout'. Accepts values between 5 seconds and 86400 seconds (24 hours).", ge=5, le=86400)
      proxy: TetraProxy | CustomProxy | None = Field(default=None, description="Proxy server configuration to route browser traffic through for this session, such as host, port, protocol, and credentials.")
      sub_user_id: str | None = Field(default=None, description="An optional identifier used to associate this session with a specific sub-user within your account, useful for tracking and auditing sessions across multiple users.")
  class CreateSessionV1TetraSessionsPostRequest(StrictModel):
      """Creates a new Tetra browser session with configurable user agent, profile, proxy, and lifecycle settings. Returns session details needed to connect and interact with the browser."""
      body: CreateSessionV1TetraSessionsPostRequestBody | None = None

• servers/agentql/server.py:1295-1296 (registration)

  The @mcp.tool() decorator registers 'create_browser_session' as an MCP tool on the FastMCP server instance.

  @mcp.tool()
  async def create_browser_session(

• servers/agentql/_auth.py:109-114 (helper)

  OPERATION_AUTH_MAP entry mapping 'create_browser_session' to require APIKeyHeader authentication.

  OPERATION_AUTH_MAP: dict[str, list[list[str]]] = {
      "query_webpage_data": [["APIKeyHeader"]],
      "get_usage": [["APIKeyHeader"]],
      "create_browser_session": [["APIKeyHeader"]],
      "list_session_usage": [["APIKeyHeader"]]
  }