From 64b1eb9ca67e4124e9581a5dfec101468c32798d Mon Sep 17 00:00:00 2001 From: Sam Date: Mon, 27 Oct 2025 12:00:33 +0100 Subject: [PATCH 1/3] docs: add Kernel and Steel integration guides, improve intro content - Add Kernel integration documentation with setup and troubleshooting - Add Steel integration documentation - Enhance what-is-notte with clearer value proposition - Improve quickstart with advanced example --- docs/src/docs.json | 4 +- docs/src/integrations/kernel.mdx | 74 +++++++++++++++++++++++++ docs/src/integrations/steel.mdx | 77 ++++++++++++++++++++++++++ docs/src/intro/quickstart.mdx | 93 +++++++++++++++++++++++++++++++- docs/src/intro/what-is-notte.mdx | 31 +++++++---- 5 files changed, 267 insertions(+), 12 deletions(-) create mode 100644 docs/src/integrations/kernel.mdx create mode 100644 docs/src/integrations/steel.mdx diff --git a/docs/src/docs.json b/docs/src/docs.json index 4e49b27a6..03ee315ce 100644 --- a/docs/src/docs.json +++ b/docs/src/docs.json @@ -62,7 +62,9 @@ "pages": [ "integrations/mcp", "integrations/openai-cua", - "integrations/cursor" + "integrations/cursor", + "integrations/kernel", + "integrations/steel" ] } ] diff --git a/docs/src/integrations/kernel.mdx b/docs/src/integrations/kernel.mdx new file mode 100644 index 000000000..00228d11e --- /dev/null +++ b/docs/src/integrations/kernel.mdx @@ -0,0 +1,74 @@ +--- +title: Kernel +description: Run Notte with Kernel cloud browsers (CDP) +--- + +## Overview + +Point Notte at Kernel's CDP endpoint to run your agents against Kernel's hosted browsers. Notte controls the browser through Chrome DevTools Protocol while your code stays unchanged - simply pass Kernel's `cdp_ws_url` into your Notte Session. + +## Prerequisites + +- **Notte SDK** installed with API key configured ([Get an API key](https://console.notte.cc)) +- **Kernel account** and API key ([Kernel documentation](https://www.onkernel.com/docs)) +- (Optional) Review Kernel's [viewport configuration](https://www.onkernel.com/docs) if you need specific browser dimensions + +## Quick Start + +Use the Kernel SDK to create a browser, extract the CDP WebSocket URL, and pass it to Notte. + +The exact API and attribute names may vary. Please refer to [Kernel's documentation](https://www.onkernel.com/docs) for the most up-to-date information. + +```python +# Install: uv add notte-sdk kernel +from notte_sdk import NotteClient +from kernel import Kernel + +# Create Kernel browser and get CDP URL +kernel_client = Kernel(api_key="YOUR_KERNEL_API_KEY") +kernel_browser = kernel_client.browsers.create() + +# Use Kernel's CDP URL with Notte +notte = NotteClient() +cdp_url = kernel_browser.cdp_ws_url # Verify attribute name in Kernel docs + +with notte.Session(cdp_url=cdp_url) as session: + agent = notte.Agent(session=session, max_steps=5) + agent.run(task="extract pricing plans from https://www.notte.cc/") + +# Optional: Cleanup Kernel session when done +# kernel_client.browsers.delete_by_id(kernel_browser.session_id) +``` + +## Using an Existing Kernel CDP URL + +If you already have a `cdp_ws_url` from Kernel, connect directly: + +```python +from notte_sdk import NotteClient + +cdp_url = "wss://?token=<...>" +notte = NotteClient() + +with notte.Session(cdp_url=cdp_url) as session: + agent = notte.Agent(session=session, max_steps=5) + agent.run(task="open the homepage and screenshot it") +``` + +## Authentication & Configuration + +- **API Key**: Kernel requires an API key to create browsers via SDK. If using a raw CDP URL, include any required token/query parameters in the WebSocket URL. +- **Viewport & Headless**: Browser settings like viewport dimensions and headless mode are controlled on the Kernel side when creating the browser. Configure these parameters during browser creation if they matter for your use case. + +## Troubleshooting + +- **403 / 401 errors**: Invalid or expired Kernel token. Reissue your API key or regenerate the CDP URL +- **WebSocket closed**: Kernel browser terminated or timed out. Create a new browser; ensure cleanup isn't premature +- **No pages available**: Ensure the Kernel session actually launched a page; let Notte navigate first with the Agent +- **Connectivity/firewall**: Allow outbound WSS connections to Kernel's CDP host + +## See Also + +- [CDP Documentation](/features/sessions/cdp) - Local and external CDP patterns +- [Session Replay](/features/sessions/session-replay) - Record and replay browser sessions +- [Proxies](/features/sessions/proxies) - Configure proxy settings for sessions diff --git a/docs/src/integrations/steel.mdx b/docs/src/integrations/steel.mdx new file mode 100644 index 000000000..d22773c3d --- /dev/null +++ b/docs/src/integrations/steel.mdx @@ -0,0 +1,77 @@ +--- +title: Steel +description: Run Notte with Steel cloud browsers (CDP) +--- + +## Overview + +Point Notte at Steel's CDP endpoint to run your agents against Steel's hosted browsers. Notte controls the browser through Chrome DevTools Protocol while your code stays unchanged - simply pass Steel's WebSocket URL into your Notte Session. + +## Prerequisites + +- **Notte SDK** installed with API key configured ([Get an API key](https://console.notte.cc)) +- **Steel account** and API key ([Get Steel API key](https://app.steel.dev/settings/api-keys)) +- (Optional) Note that some Steel endpoints require the API key as a query parameter on the WebSocket URL + +## Quick Start + +Use the Steel SDK to create a browser session, extract the WebSocket URL, and pass it to Notte. + +The exact API and attribute names may vary. Please refer to [Steel's documentation](https://docs.steel.dev/) for the most up-to-date information. + +```python +# Install: uv add notte-sdk steel +import os +from notte_sdk import NotteClient +from steel import Steel + +STEEL_API_KEY = os.getenv("STEEL_API_KEY") + +# 1) Create Steel browser session +client = Steel(api_key=STEEL_API_KEY) # Note: verify parameter name with Steel docs +session = client.sessions.create() + +# Steel returns a websocket URL for CDP control +# Check Steel docs for the exact attribute name and query param format +cdp_url = session.websocket_url # May need: f"{session.websocket_url}?apiKey={STEEL_API_KEY}" + +# 2) Run Notte agent against Steel's CDP browser +notte = NotteClient() +with notte.Session(cdp_url=cdp_url) as s: + agent = notte.Agent(session=s, max_steps=6) + agent.run(task="extract pricing plans from https://www.notte.cc/") +``` + +## Using an Existing Steel CDP URL + +If you already have a WebSocket URL from Steel, connect directly: + +```python +from notte_sdk import NotteClient + +cdp_url = "wss://" # Add auth params as required by Steel +notte = NotteClient() + +with notte.Session(cdp_url=cdp_url) as s: + agent = notte.Agent(session=s, max_steps=5) + agent.run(task="open the homepage and take a full-page screenshot") +``` + +## Authentication & Configuration + +- **API Key**: Steel requires an API key to create browser sessions via SDK. If using a raw WebSocket/CDP URL, include any required query parameters (like `apiKey`) in the URL. +- **Browser Settings**: Viewport dimensions, headless mode, regions, and timeouts are configured when creating the Steel session ([see Steel Sessions docs](https://docs.steel.dev/)). +- **Network Configuration**: If your organization enforces IP allowlists or proxies, configure those on Steel's side during session creation. + +## Troubleshooting + +- **401 / 403 errors**: Invalid or expired Steel token. Regenerate your API key or re-create the session URL +- **WebSocket closed**: Steel session terminated or timed out. Create a new Steel session +- **No targets/pages available**: Ensure the Steel session actually launched a page; let Notte navigate first with the Agent +- **Connectivity/firewall**: Allow outbound WSS connections to Steel's host + +## See Also + +- [CDP Documentation](/features/sessions/cdp) - Local and external CDP patterns +- [Session Replay](/features/sessions/session-replay) - Record and replay browser sessions +- [Proxies](/features/sessions/proxies) - Configure proxy settings for sessions diff --git a/docs/src/intro/quickstart.mdx b/docs/src/intro/quickstart.mdx index b04e4fe05..ea5c3aaba 100644 --- a/docs/src/intro/quickstart.mdx +++ b/docs/src/intro/quickstart.mdx @@ -3,10 +3,10 @@ title: Quickstart agent description: 'Get started in a few seconds' --- -Explore our GitHub repository [https://github.com/nottelabs/notte](https://github.com/nottelabs/notte) and star us 🌟 - In this quickstart guide, we'll create a simple web agent that can browse and interact with websites autonomously. You'll learn how to set up your development environment, create a browser session, and run your first agent task. +Explore our GitHub repository [https://github.com/nottelabs/notte](https://github.com/nottelabs/notte) and star us 🌟 + ## Guide @@ -43,6 +43,95 @@ In this quickstart guide, we'll create a simple web agent that can browse and in ) ``` + + + ```python + """Notte SDK - Coherent Job Application Automation (All Features Demo)""" + import os, json + from notte_sdk import NotteClient + from pathlib import Path + from datetime import timedelta + + client = NotteClient(api_key=os.getenv("NOTTE_API_KEY")) + output = Path("./job_application_output") + output.mkdir(exist_ok=True) + + # Create applicant identity (used throughout application) + persona = client.Persona(create_vault=True) + persona.add_credentials(url="https://jobs.example.com") + + # Prepare resume for upload during application + storage = client.FileStorage() + storage.upload("./my_resume.pdf") + + # Application session with anti-bot protection + with client.Session( + timeout_minutes=15, + proxies=True, # Enable Notte proxies + solve_captchas=True, # Handle job site CAPTCHAs + browser_type="firefox", # Required for solve_captchas=True + headless=False, + use_file_storage=True # Enable file storage for the session + ) as session: + + # Attach storage to session after it starts + storage.set_session_id(session.session_id) + + agent = client.Agent(session=session, reasoning_model="gemini/gemini-2.0-flash-thinking-exp-1219", max_steps=20) + + # Research target company and position + research = agent.run( + task="Research 'Anthropic' on LinkedIn. Find Software Engineer job requirements and culture.", + url="https://www.linkedin.com/jobs" + ) + + # Fill and submit application using persona email and uploaded resume + application = agent.run( + task=f""" + Go to Anthropic careers page, find Software Engineer role, and apply. + Use email: {persona.info.email} + Upload resume from available files. + Fill all required fields and submit application. + """, + url="https://www.anthropic.com/careers" + ) + + # Extract confirmation details + confirmation = session.scrape(instructions="Extract confirmation number and next steps") + + # Save session cookies for returning to check application status later + cookies = session.get_cookies() + with open(output / "session_cookies.json", 'w') as f: + json.dump(cookies, f) + + # Record entire application process + replay = session.replay() + replay.save(str(output / "application_replay.mp4")) + + # Check for confirmation email (sent after application submission) + emails = persona.emails(only_unread=True, limit=10, timedelta=timedelta(minutes=30)) + + # Download confirmation documents (PDFs, receipts downloaded during application) + # Note: session_id needs to be saved before the context manager closes + session_id = session.session_id + for filename in storage.list_downloaded_files(session_id=session_id): + storage.download(session_id=session_id, file_name=filename, local_dir=str(output)) + + # Save comprehensive application summary + with open(output / "application_summary.json", 'w') as f: + json.dump({ + 'persona_email': persona.info.email, + 'research_status': research.status if hasattr(research, 'status') else 'completed', + 'application_status': application.status if hasattr(application, 'status') else 'completed', + 'confirmation': confirmation, + 'emails_received': len(emails) + }, f, indent=2) + + # Keep persona active for follow-up communications + # persona.delete() # Uncomment to cleanup + ``` + + ## Next steps diff --git a/docs/src/intro/what-is-notte.mdx b/docs/src/intro/what-is-notte.mdx index c4074301b..3345fcfd4 100644 --- a/docs/src/intro/what-is-notte.mdx +++ b/docs/src/intro/what-is-notte.mdx @@ -2,10 +2,16 @@ title: What is Notte? --- -Explore our GitHub repository [https://github.com/nottelabs/notte](https://github.com/nottelabs/notte) and star us 🌟 - Notte is the platform for building and deploying reliable [Web AI Agents](/concepts/agents) that can act and scrape on any site. -Notte provides everything you need to automate repetitive workflows at really large scale with a single API. Stealthly cloud browser sessions, proxies, secure credential management, and seamless integrations with AI tools in the ecosystem. +Notte provides everything you need to automate repetitive workflows at large scale with a single API: stealthily cloud browser sessions, proxies, secure credential management, and seamless integrations with AI tools in the ecosystem. + +## Why Notte? + +Traditional frameworks rely on brittle scripts that break when the UI changes, or on agents that waste compute handling predictable steps. Notte enables the combination of both approaches. Deterministic scripts handle stable workflows; agents automatically step in when failures occur. You can run deterministic scripts, fully autonomous agents, or any mix between. This creates a continuum between reliability and adaptability without manual intervention. + +Because full agent tooling is included and infrastructure is managed, you can move from prototype to production without maintaining separate browsers, credentials, or cloud systems. + +Explore our GitHub repository [https://github.com/nottelabs/notte](https://github.com/nottelabs/notte) and star us 🌟 @@ -23,13 +29,20 @@ Notte provides everything you need to automate repetitive workflows at really la A fullstack platform for secure, scalable, and intelligent web automation: -1. **[Create instant Browser sessions](/concepts/sessions)**. Instantly launch and manage headless browsers in the cloud. Integrate with Playwright CDP, manage cookies & files, replay sessions and bypass CAPTCHAs & Bot detection. -1. **[Run automated agents](/concepts/agents)**. LLM-powered agents to automate any web task. -1. **[Take control](/concepts/operations)**: Observe, act and scrape on websites. For scenarios requiring more precise control than autonomous agents, we offer a fully functional web browser interface for LLM agents. -1. **[Host repetitive workflows](/concepts/workflows)**. Create and manage reusable hybrid workflows that combine traditional deterministic steps with LLM-powered agents for reliable and cost-effective automation. -1. **[Secure your credentials](/concepts/vaults)**. We provide a secure vault and credentials management system that allows you to safely share authentication details with AI agents. -1. **[Digital Identities for your agents](/concepts/personas)**. Create and manage digital identities (names, emails, phone numbers) for your agents. Use them for automated onboarding and account creation. +### Web Automation + +- **[Run automated agents](/concepts/agents)**. LLM-powered agents to automate any web task. +- **[Take control](/concepts/operations)**: Observe, act and scrape on websites. For scenarios requiring more precise control than autonomous agents, we offer a fully functional web browser interface for LLM agents. +- **[Host repetitive workflows](/concepts/workflows)**. Create and manage reusable hybrid workflows that combine traditional deterministic steps with LLM-powered agents for reliable and cost-effective automation. + +### Browser infrastructure + +- **[Create instant Browser sessions](/concepts/sessions)**. Instantly launch and manage headless browsers in the cloud. Integrate with Playwright CDP, manage cookies & files, replay sessions and bypass CAPTCHAs & Bot detection. + +### Security & Identity +- **[Secure your credentials](/concepts/vaults)**. We provide a secure vault and credentials management system that allows you to safely share authentication details with AI agents. +- **[Digital Identities for your agents](/concepts/personas)**. Create and manage digital identities (names, emails, phone numbers) for your agents. Use them for automated onboarding and account creation. **Enterprise features:** SOC-2 compliant with comprehensive audit trails - On-prem options - SSO. From fdbd5ca89aeee5627aff0e407c48ddf1d38406d4 Mon Sep 17 00:00:00 2001 From: Sam Date: Tue, 28 Oct 2025 13:51:58 +0100 Subject: [PATCH 2/3] fix: capture session_id before context closes and grammar error --- docs/src/intro/quickstart.mdx | 5 +++-- docs/src/intro/what-is-notte.mdx | 2 +- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/src/intro/quickstart.mdx b/docs/src/intro/quickstart.mdx index ea5c3aaba..2ca0afbaa 100644 --- a/docs/src/intro/quickstart.mdx +++ b/docs/src/intro/quickstart.mdx @@ -108,12 +108,13 @@ In this quickstart guide, we'll create a simple web agent that can browse and in replay = session.replay() replay.save(str(output / "application_replay.mp4")) + # Save session_id while session context is active + session_id = session.session_id + # Check for confirmation email (sent after application submission) emails = persona.emails(only_unread=True, limit=10, timedelta=timedelta(minutes=30)) # Download confirmation documents (PDFs, receipts downloaded during application) - # Note: session_id needs to be saved before the context manager closes - session_id = session.session_id for filename in storage.list_downloaded_files(session_id=session_id): storage.download(session_id=session_id, file_name=filename, local_dir=str(output)) diff --git a/docs/src/intro/what-is-notte.mdx b/docs/src/intro/what-is-notte.mdx index 3345fcfd4..a6fa5926c 100644 --- a/docs/src/intro/what-is-notte.mdx +++ b/docs/src/intro/what-is-notte.mdx @@ -3,7 +3,7 @@ title: What is Notte? --- Notte is the platform for building and deploying reliable [Web AI Agents](/concepts/agents) that can act and scrape on any site. -Notte provides everything you need to automate repetitive workflows at large scale with a single API: stealthily cloud browser sessions, proxies, secure credential management, and seamless integrations with AI tools in the ecosystem. +Notte provides everything you need to automate repetitive workflows at large scale with a single API: stealthy cloud browser sessions, proxies, secure credential management, and seamless integrations with AI tools in the ecosystem. ## Why Notte? From ab3520d67261bcff54ab878bf24d9246717147b7 Mon Sep 17 00:00:00 2001 From: Sam Morris Date: Thu, 29 Jan 2026 19:16:30 +0000 Subject: [PATCH 3/3] Update steel.mdx updated links --- docs/src/integrations/steel.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/src/integrations/steel.mdx b/docs/src/integrations/steel.mdx index d22773c3d..11b63c0b4 100644 --- a/docs/src/integrations/steel.mdx +++ b/docs/src/integrations/steel.mdx @@ -72,6 +72,6 @@ with notte.Session(cdp_url=cdp_url) as s: ## See Also -- [CDP Documentation](/features/sessions/cdp) - Local and external CDP patterns -- [Session Replay](/features/sessions/session-replay) - Record and replay browser sessions -- [Proxies](/features/sessions/proxies) - Configure proxy settings for sessions +- [CDP Documentation](https://docs.notte.cc/features/sessions/external-providers) - Local and external CDP patterns +- [Session Replay](https://docs.notte.cc/features/sessions/recordings) - Record and replay browser sessions +- [Proxies](https://docs.notte.cc/features/sessions/proxies) - Configure proxy settings for sessions