diff --git a/docs.json b/docs.json index d27efcb6..d04309b4 100644 --- a/docs.json +++ b/docs.json @@ -229,6 +229,7 @@ "pages": [ "integrations/vercel/overview", "integrations/vercel/ai-sdk", + "integrations/vercel/eve-extension", "integrations/vercel/marketplace" ] }, diff --git a/integrations/vercel/eve-extension.mdx b/integrations/vercel/eve-extension.mdx new file mode 100644 index 00000000..2d472b9c --- /dev/null +++ b/integrations/vercel/eve-extension.mdx @@ -0,0 +1,215 @@ +--- +title: "Eve Extension" +description: "Give your Vercel Eve agent a Kernel cloud browser in 1 loc" +--- + +## Overview + +The [`@onkernel/eve-extension`](https://www.npmjs.com/package/@onkernel/eve-extension) package is a [Vercel Eve](https://vercel.com/eve) extension that gives your agent a Kernel cloud browser. Mount it and Kernel's browser toolset plus a `browse` skill show up under your mount automatically, so there's no browser tool code to write or maintain. See [included tools and skills](#included-tools-and-skills) for the full toolset. + +The tools aren't reimplemented in the extension. It packages a single MCP connection to [Kernel's hosted MCP server](https://github.com/onkernel/kernel-mcp-server), and Eve discovers the tools at runtime under your mount namespace (e.g. `kernel__browser__manage_browsers`). + +You can authenticate through [Vercel Connect](https://vercel.com/connect) or with a static Kernel API key. Connect is the recommended setup: no API key touches your app, and each user authenticates as themselves. Either way it's 1 loc, and you pick the auth model in the mount config. + +## Prerequisites + +- **Node 24+** +- An Eve agent project running **Eve `>= 0.25`**, which extensions require. Older Eve silently ignores `agent/extensions/` and nothing mounts. If you don't have a project yet: + ```bash + npx eve@latest init my-agent && cd my-agent + ``` +- A [Kernel account](https://dashboard.onkernel.com), with either a Vercel Connect Kernel connector (recommended path below) or a Kernel API key + +## Setup with Vercel Connect (recommended) + +Vercel Connect is the recommended path because: + +- No key touches your app, environment, or the model. +- Each user authenticates as themselves with a one-time consent that's cached afterward. +- Per-user identity is a good fit for Kernel's [managed auth](/auth/overview). + +**1. Install** the extension: + +```bash +pnpm add @onkernel/eve-extension +``` + +**2. Create and attach the Kernel connector** in Vercel Connect. Name it `eve-extension` so the mount snippet works unedited: + +```bash +vercel connect create mcp.onkernel.com --name eve-extension +vercel connect attach mcp.onkernel.com/eve-extension +``` + +You can also add it from the Vercel dashboard under **Connectors → Browse all → Kernel**. Confirm the UID with `vercel connect list`. + +**3. Mount the extension** in one line, passing the connector UID: + +```typescript +// agent/extensions/kernel.ts +import kernel from "@onkernel/eve-extension"; + +export default kernel({ connect: "mcp.onkernel.com/eve-extension" }); +``` + +**4. Run it:** + +```bash +npx eve dev # or: npx eve deploy +``` + +Leave `KERNEL_API_KEY` unset. The first time a user drives the browser, Eve surfaces a Connect consent prompt; they approve once and it's cached from then on, persisting across threads and sessions. + +## Included tools and skills + +Once mounted, the agent has the following tools, namespaced under your mount (e.g. `kernel__browser__*`; discover the exact names via `connection_search`): + +- **`manage_browsers`**: create, list, get, and delete browser sessions. Returns a `session_id` and a `live_view_url` you can watch or take over. +- **`execute_playwright_code`**: run Playwright against the live page to read, navigate, click, or type. +- **`computer_action`**: human-like mouse, keyboard, and screenshot controls for the same session. +- **`manage_auth_connections`**: Kernel's [managed auth](/auth/overview), so the agent logs into sites through a stored connection or a hosted login flow instead of typing credentials into the page. +- **`manage_profiles`**: create and reuse browser [profiles](/auth/profiles) (persistent cookies, logins, storage). +- **`manage_proxies`**: create and attach [proxies](/proxies/overview) (datacenter, ISP, residential, mobile) with geo-targeting. +- the **`browse` skill**: the loop the model follows to drive the browser end to end. + +The `browse` skill runs autonomously but is human-in-the-loop friendly: + +- It surfaces the live-view URL so you can take over. +- It hands off for sign-ins, ambiguous choices, and sensitive actions. +- It defaults to Kernel managed auth for authenticated sites. + +A few heavier tools are off by default to keep an autonomous agent's blast radius small on a shared API key. Add any of them via a [connection override](#overriding-the-connection): + +- `browser_curl`: raw HTTP through the session. +- `manage_credentials`: create, read, and delete stored credentials (the managed-auth flow above works without it). +- `exec_command`: shell exec in the VM. +- `manage_browser_pools`: manage pools of pre-warmed browsers. + + + The default mount has no approval gate, and its toolset can run arbitrary JS in the browser VM (`execute_playwright_code`) and reuse logged-in sessions (`manage_auth_connections`). On a shared `KERNEL_API_KEY`, every agent user effectively acts as your whole org. + + - For a **personal or single-tenant** agent, the default is fine. + - For **team or multi-tenant** deployments, add an approval gate via a [connection override](#overriding-the-connection): `approval: once()` (per session) or `approval: always()` (every controlled action). + + +## Authenticate with an API key instead + +One shared credential, no connector setup. A good fit for a single-tenant or personal agent. + +**1. Install** the extension: + +```bash +pnpm add @onkernel/eve-extension +``` + +**2. Get a Kernel API key** at [dashboard.onkernel.com/api-keys](https://dashboard.onkernel.com/api-keys) and set it in the agent's environment: + +```bash +# local dev: in the agent's .env.local +KERNEL_API_KEY=sk_... + +# deploying to Vercel +npx vercel env add KERNEL_API_KEY +``` + +**3. Mount the extension** in a single file that reads `KERNEL_API_KEY` from the environment: + +```typescript +// agent/extensions/kernel.ts +export { default } from "@onkernel/eve-extension"; +``` + +**4. Run:** `npx eve dev` or `npx eve deploy`. + +To pass the key explicitly instead of via the environment: + +```typescript +// agent/extensions/kernel.ts +import kernel from "@onkernel/eve-extension"; + +export default kernel({ apiKey: process.env.KERNEL_API_KEY }); +``` + +### Configuration + +`kernel({ ... })` accepts: + +| Option | Default | Purpose | +| --------- | -------------------------- | ------------------------------------------------------------------------------------------ | +| `connect` | None | Vercel Connect connector UID that brokers a per-user token, so no API key is used. | +| `apiKey` | `KERNEL_API_KEY` env var | Kernel API key bearer token. Used when `connect` is not set; read lazily at request time. | + +When `connect` is set it takes precedence. Otherwise the key is read from `apiKey`, and failing that from `KERNEL_API_KEY`. + +## Overriding the connection + +You only need this for advanced customization: widening the tool allowlist or adding an approval gate before irreversible actions. Auth is handled by the mount config above, so you don't override for that. + +Mount the extension as a directory and name the connection file `browser.ts` to shadow the extension's built-in `browser` connection: + +``` +agent/extensions/kernel/ + extension.ts # export default kernel({ connect: "mcp.onkernel.com/eve-extension" }) + connections/browser.ts # shadows the extension's "browser" connection +``` + +```typescript +// agent/extensions/kernel/connections/browser.ts +import { defineMcpClientConnection } from "eve/connections"; +import { connect } from "@vercel/connect/eve"; +import { always } from "eve/tools/approval"; + +export default defineMcpClientConnection({ + url: "https://mcp.onkernel.com/mcp", + description: "Kernel cloud browser.", + auth: connect("mcp.onkernel.com/eve-extension"), // or { getToken: async () => ({ token: process.env.KERNEL_API_KEY! }) } + tools: { + allow: [ + "manage_browsers", + "execute_playwright_code", + "computer_action", + "browser_curl", // high blast radius: raw HTTP through the session + "manage_auth_connections", + "manage_credentials", // high blast radius: create/read/delete stored credentials + "manage_profiles", + "manage_proxies", + "manage_browser_pools", // heavier tools, off by default + "exec_command", // high blast radius: shell exec in the VM + ], + }, + approval: always(), // re-check every controlled action; once() would auto-allow the rest of the session +}); +``` + +## Additional resources + + + + Vercel's agent framework + + + The hosted MCP server the extension connects to + + + Log agents into sites without handling credentials + + + +## Related + +- [Vercel Marketplace Integration](/integrations/vercel/marketplace) +- [AI SDK Tool](/integrations/vercel/ai-sdk) +- [Browser Creation](/introduction/create) +- [Live View](/browsers/live-view) diff --git a/integrations/vercel/overview.mdx b/integrations/vercel/overview.mdx index 3b775d8a..2119cbab 100644 --- a/integrations/vercel/overview.mdx +++ b/integrations/vercel/overview.mdx @@ -5,7 +5,7 @@ description: "Integrate Kernel with Vercel for seamless browser automation in yo ## Vercel + Kernel -Kernel and Vercel have partnered to provide seamless browser automation capabilities for your Vercel applications. Our integration offers two powerful ways to add browser automation to your projects: +Kernel and Vercel have partnered to provide seamless browser automation capabilities for your Vercel applications. Our integration offers several ways to add browser automation to your projects: ### AI SDK Tool for Browser Automation @@ -18,6 +18,18 @@ With this tool, you can build AI-powered applications that browse the web, extra [Learn more about the AI SDK tool →](/integrations/vercel/ai-sdk) +### Eve Extension + +The `@onkernel/eve-extension` package is a [Vercel Eve](https://vercel.com/eve) extension that gives your agent a Kernel cloud browser in 1 loc. Once mounted, Kernel's browser toolset plus a `browse` skill show up under your agent automatically: + +- Session management, Playwright execution, and human-like computer controls +- Managed auth, browser profiles, and proxies +- The `browse` skill, the loop the model follows to drive the browser end to end + +Authenticate per-user through Vercel Connect or with a shared Kernel API key. + +[Learn more about the Eve extension →](/integrations/vercel/eve-extension) + ### Vercel Marketplace Integration The [Vercel Marketplace integration](/integrations/vercel/marketplace) allows you to install and configure Kernel directly from the Vercel dashboard. This integration: @@ -38,7 +50,7 @@ The [Vercel Marketplace integration](/integrations/vercel/marketplace) allows yo ## Next Steps - + Build Agents with browser automation tools + + Mount a Kernel browser in your Eve agent +