AsyncNotteClient

Call the Notte API from asyncio code with the async Python client (preview)

AI agent instructions

Read the Notte skill and follow its setup instructions when setting up Notte or building browser automation. This is the shared source for CLI setup, authentication, and the browser-to-code workflow.

Available from notte-sdk 1.10.0. AsyncNotteClient is in preview: its API may still change.

AsyncNotteClient is the asyncio version of NotteClient. Use it when your code already runs in an event loop (an async web server or agent framework, for example), or to run sessions, scrapes and functions concurrently without threads. In synchronous code, keep using NotteClient.

It takes the same constructor arguments as NotteClient and reads NOTTE_API_KEY the same way. Its resources (sessions, functions, files, personas, profiles, vaults and managed_auth), health_check() and scrape() have the same methods as on NotteClient, with the same names, arguments, results and exceptions, as coroutines: add await. client.Session, client.Function, client.Persona, client.Vault and client.FileStorage return async versions of the same objects.

​

Open and close the client

async_client.py

import asyncio

from notte_sdk import AsyncNotteClient


async def main() -> None:
    # `async with` closes the client's connections on exit
    async with AsyncNotteClient() as client:
        await client.health_check()

    # without `async with`, close the client yourself
    client = AsyncNotteClient()
    try:
        await client.health_check()
    finally:
        await client.aclose()


asyncio.run(main())

Connections open on the first request. Close them with async with or await client.aclose(). They cannot be closed when the client is garbage collected, so an unclosed client emits a ResourceWarning instead. After aclose(), the client stays usable: the next request opens new connections.

​

Sessions

async_session.py

import asyncio

from notte_sdk import AsyncNotteClient


async def main() -> None:
    async with AsyncNotteClient() as client:
        # the session is stopped when the block exits, also on errors and cancellation
        async with client.Session() as session:
            _ = await session.execute(type="goto", url="https://example.com")
            markdown = await session.scrape()
            print(markdown)

            # the async Playwright page, connected to the same browser
            page = await session.page
            print(await page.title())


asyncio.run(main())

• async with client.Session() starts the session and stops it when the block exits, also when entering the block fails or the task is cancelled. There is no sync with block.
• await session.page returns the async Playwright page. It needs pip install "notte-sdk[playwright]".
• client.Session(session_id) attaches to an existing session without sending a request. The first method that needs the session’s state reads it.

​

Scrape

async_scrape.py

import asyncio

from notte_sdk import AsyncNotteClient

urls = ["https://example.com", "https://www.notte.cc"]


async def main() -> None:
    async with AsyncNotteClient() as client:
        # each scrape starts and stops its own session. The TaskGroup runs them concurrently and
        # waits for every one, cleanup included, before the client closes.
        async with asyncio.TaskGroup() as group:
            tasks = [group.create_task(client.scrape(url)) for url in urls]
        for url, task in zip(urls, tasks):
            print(url, task.result()[:100])


asyncio.run(main())

await client.scrape(url, ...) takes the same arguments as NotteClient.scrape, including response_format and instructions. It starts a session, scrapes the page and stops the session, also when the scrape fails.

​

Functions

async_function.py

import asyncio

from notte_sdk import AsyncNotteClient


async def main() -> None:
    async with AsyncNotteClient() as client:
        # creating a function sends a request, so await it
        function = await client.Function(path="my_function.py", name="Async example")
        try:
            # loading a function by ID sends no request until you use it
            same_function = client.Function(function_id=function.function_id)
            result = await same_function.run(url="https://example.com")
            print(result.status, result.result)
        finally:
            await function.delete(confirm=True)


asyncio.run(main())

my_function.py is a function file as described in Creating Functions. function.run() takes the same arguments as the sync run().

​

Personas and vaults

The sync Persona and Vault objects call the API in their constructor. An async constructor cannot, so await the object to create it, or to load it when you pass an ID: persona = await client.Persona(persona_id). async with does the same and also deletes it on exit.

async_persona_vault.py

import asyncio

from notte_sdk import AsyncNotteClient


async def main() -> None:
    async with AsyncNotteClient() as client:
        # `async with` creates the persona and deletes it on exit
        async with client.Persona(create_vault=True) as persona:
            print(f"Persona email: {persona.info.email}")
            await persona.add_credentials(url="https://github.com/")
            emails = await persona.emails(only_unread=True, limit=10)
            print(f"Recent emails: {emails}")

        # `await` creates the vault; delete it when you no longer need it
        vault = await client.Vault(name="async-example")
        try:
            password = vault.generate_password()  # no request, so not awaited
            await vault.add_credentials(url="https://example.com", email="[e-mail]", password=password)
            print(await vault.list_credentials())
        finally:
            await vault.delete()


asyncio.run(main())

​

Migrating mixed sync and async code

NotteClient and its session, vault, persona and file-storage objects expose synchronous operations only. Use AsyncNotteClient for async operations, including async Playwright. Replace session.apage with session.page on an async session, and await operations by their regular names: await vault.get_credentials(url), await persona.emails() and await storage.list_uploaded_files().

When attaching a cloud vault or persona to a local browser session, create it with AsyncNotteClient and run the local session on the same event loop.

​

Event loops and files

• A client’s connections belong to the event loop that made its first request. Using the client from another event loop while that loop is still open raises RuntimeError, so create one client per event loop. Once the first loop is closed, the next request opens new connections in the current loop.
• Local files, such as function code, uploads, downloads and cookie files, are read and written off the event loop.

​

What is not async

• Methods that send no request stay plain methods: client.functions.get_curl(), client.functions.decode_message() and vault.generate_password(), for example.
• The deprecated notte 1.9 names, such as client.workflows, client.Workflow and client.functions.run(), exist only on NotteClient. Use the current names.
• NotteClient.Session() supports synchronous operations and sync Playwright. For async with, async operations and async Playwright, use AsyncNotteClient.Session() with await session.page and await session.wait_for_auth().