The Open Framework for Building Agents
feat(docs): add extension category, and include agent-browser as first example (#975)
Colton Padden842e5160eccc
diff --git a/apps/docs/app/[lang]/integrations/[slug]/page.tsx b/apps/docs/app/[lang]/integrations/[slug]/page.tsxindex 308225a1d..558395154 100644--- a/apps/docs/app/[lang]/integrations/[slug]/page.tsx+++ b/apps/docs/app/[lang]/integrations/[slug]/page.tsx@@ -22,6 +22,7 @@ import { SetupTabs } from "../components/setup-tabs";const typeLabel = {channel: "Channel",connection: "Connection",+ extension: "Extension",} as const;const languages = Object.keys(translations);diff --git a/apps/docs/app/[lang]/integrations/components/gallery.tsx b/apps/docs/app/[lang]/integrations/components/gallery.tsxindex b1b98db6d..3daba36e6 100644--- a/apps/docs/app/[lang]/integrations/components/gallery.tsx+++ b/apps/docs/app/[lang]/integrations/components/gallery.tsx@@ -14,6 +14,7 @@ const FILTERS: { value: Filter; label: string }[] = [{ value: "all", label: "All" },{ value: "channel", label: "Channels" },{ value: "connection", label: "Connections" },+ { value: "extension", label: "Extensions" },];const TYPE_DESCRIPTIONS: Record<IntegrationType, string> = {@@ -21,6 +22,7 @@ const TYPE_DESCRIPTIONS: Record<IntegrationType, string> = {"Channels are the surfaces where users talk to your agent: Slack, Discord, web chat, and more.",connection:"Connections are the tools your agent calls during a run: services reached over MCP or OpenAPI.",+ extension: "Extensions are packages that add reusable tools, skills, connections, and hooks.",};interface GalleryProps {diff --git a/apps/docs/app/[lang]/integrations/components/integration-card.tsx b/apps/docs/app/[lang]/integrations/components/integration-card.tsxindex e6318cb3b..7e7e6535e 100644--- a/apps/docs/app/[lang]/integrations/components/integration-card.tsx+++ b/apps/docs/app/[lang]/integrations/components/integration-card.tsx@@ -5,6 +5,7 @@ import { logos } from "@/lib/integrations/logos";const typeLabel: Record<Integration["type"], string> = {channel: "Channel",connection: "Connection",+ extension: "Extension",};interface IntegrationCardProps {diff --git a/apps/docs/app/[lang]/integrations/page.tsx b/apps/docs/app/[lang]/integrations/page.tsxindex 9f5078597..830729b72 100644--- a/apps/docs/app/[lang]/integrations/page.tsx+++ b/apps/docs/app/[lang]/integrations/page.tsx@@ -5,7 +5,7 @@ import { Gallery } from "./components/gallery";const title = "Integrations";const description =- "Browse every third-party service eve connects to: messaging channels, MCP connections, and OpenAPI connections, each with install, quick start, and configuration steps.";+ "Browse the channels, connections, and extensions available to an eve agent, each with install, quick start, and configuration steps.";export const metadata: Metadata = {title,@@ -21,8 +21,8 @@ const IntegrationsPage = () => (Integrations</h1><p className="mt-5 max-w-2xl text-gray-900 text-lg">- Connect eve to the services your agent needs, including messaging channels and tool- connections over MCP or OpenAPI.+ Add the channels where people reach your agent, connections to external services, and+ extensions that package reusable capabilities.</p></section><Gallery integrations={integrations} />diff --git a/apps/docs/lib/integrations/data.ts b/apps/docs/lib/integrations/data.tsindex 963ee4a52..374bdc5c4 100644--- a/apps/docs/lib/integrations/data.ts+++ b/apps/docs/lib/integrations/data.ts@@ -4,6 +4,7 @@ import {channelEntries,connectionEntries,connectionProtocols as protocolsForIdentity,+ extensionEntries,} from "@vercel/eve-catalog";import type { LogoKey } from "./logos";@@ -16,7 +17,7 @@ import type { LogoKey } from "./logos";* keyed by slug.*/-export type IntegrationType = "channel" | "connection";+export type IntegrationType = "channel" | "connection" | "extension";/** Wire protocol and transport identity types are owned by the shared catalog. */export type { ConnectionProtocol, McpTransport, OpenApiTransport } from "@vercel/eve-catalog";@@ -67,8 +68,8 @@ export interface Integration {/** Searchable keywords beyond the name. */keywords?: string[];/**- * Channels author their setup as markdown. Connections leave these unset- * and supply a `connection` spec, from which content is generated.+ * Channels and extensions author their setup as markdown. Connections leave+ * these unset and supply a `connection` spec, from which content is generated.*/install?: string;quickStart?: string;@@ -93,6 +94,13 @@ interface ChannelPresentation extends Presentation {configure: string;}+/** Extension overlay with hand-authored package setup. */+interface ExtensionPresentation extends Presentation {+ install: string;+ quickStart: string;+ configure: string;+}+/** Connection overlay: presentation plus Connect auth/config details. */interface ConnectionPresentation extends Presentation {authModes: AuthMode[];@@ -474,6 +482,57 @@ Credentials come from the \`createMessengerAdapter\` config or the adapter's env},};+const extensionPresentations: Record<string, ExtensionPresentation> = {+ "agent-browser": {+ logo: "agent-browser",+ docsHref:+ "https://github.com/vercel-labs/agent-browser/tree/main/packages/%40agent-browser/eve",+ keywords: [+ "browser",+ "browser automation",+ "web automation",+ "cli",+ "chrome",+ "playwright",+ "puppeteer",+ "kernel",+ "browserbase",+ "browser use",+ ],+ install: `Install the agent-browser extension for eve:++\`\`\`bash+npm install @agent-browser/eve+\`\`\`++The extension installs agent-browser automatically on first use and runs it inside the agent's sandbox. It requires a sandbox backend with real process execution, such as Vercel Sandbox, Docker, or microsandbox.`,+ quickStart: `Mount the extension under \`agent/extensions/\`:++\`\`\`ts title="agent/extensions/browser.ts"+import browser from "@agent-browser/eve";++export default browser({});+\`\`\`++The filename supplies the \`browser\` namespace. The extension adds tools such as \`browser__navigate\`, \`browser__snapshot\`, \`browser__click\`, \`browser__fill\`, \`browser__find\`, and \`browser__screenshot\`. agent-browser keeps the underlying browser process and session state in the eve sandbox.`,+ configure: `Restrict browser access to the sites the agent needs with the extension's domain allow-list:++\`\`\`ts title="agent/extensions/browser.ts"+import browser from "@agent-browser/eve";++export default browser({+ allowedDomains: ["example.com", "*.example.com"],+ contentBoundaries: true,+ maxOutputChars: 50_000,+});+\`\`\`++Also configure the [sandbox network policy](/docs/sandbox#network-policy) for defense in depth. Treat saved browser state, cookies, screenshots, downloads, and recordings as sensitive data. Do not place passwords or session tokens in prompts. Use the extension's per-tool overrides to gate or disable actions your agent should not take unattended.++The extension also supports inline screenshots, session naming, proxies, and production pre-installation. See the [agent-browser eve extension documentation](https://github.com/vercel-labs/agent-browser/tree/main/packages/%40agent-browser/eve) for the complete options and example app.`,+ },+};+/*** Connection presentation overlay, keyed by catalog slug. Transport (`mcp`,* `openapi`) and the model-facing description come from `@vercel/eve-catalog`;@@ -763,6 +822,27 @@ function buildConnection(entry: IntegrationEntry): Integration {};}+function buildExtension(entry: IntegrationEntry): Integration {+ const presentation = extensionPresentations[entry.slug];+ if (presentation === undefined) {+ throw new Error(+ `Extension "${entry.slug}" is in the catalog gallery but has no docs presentation.`,+ );+ }+ return {+ slug: entry.slug,+ name: entry.name,+ type: "extension",+ tagline: entry.tagline,+ logo: presentation.logo,+ docsHref: presentation.docsHref,+ keywords: presentation.keywords,+ install: presentation.install,+ quickStart: presentation.quickStart,+ configure: presentation.configure,+ };+}+const channels: Integration[] = channelEntries().filter((entry) => entry.surfaces.gallery).map(buildChannel);@@ -771,6 +851,10 @@ const connections: Integration[] = connectionEntries().filter((entry) => entry.surfaces.gallery).map(buildConnection);+const extensions: Integration[] = extensionEntries()+ .filter((entry) => entry.surfaces.gallery)+ .map(buildExtension);+/** Display label for each connection protocol. */export const protocolLabel: Record<ConnectionProtocol, string> = {mcp: "MCP",@@ -790,7 +874,7 @@ export const authModeLabel: Record<AuthMode, string> = {jwtBearer: "JWT bearer",};-export const integrations: Integration[] = [...channels, ...connections];+export const integrations: Integration[] = [...channels, ...extensions, ...connections];export const getIntegration = (slug: string): Integration | undefined =>integrations.find((integration) => integration.slug === slug);diff --git a/apps/docs/lib/integrations/logos.tsx b/apps/docs/lib/integrations/logos.tsxindex f597c12b6..70e4df9a8 100644--- a/apps/docs/lib/integrations/logos.tsx+++ b/apps/docs/lib/integrations/logos.tsx@@ -299,6 +299,21 @@ export const messengerLogo = (props: LogoProps) => <SiMessenger color="default"export const xLogo = (props: LogoProps) => <SiX {...props} />;+export const agentBrowserLogo = (props: LogoProps) => (+ <svg fill="none" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg" {...props}>+ <rect height="16" rx="2" stroke="currentColor" strokeWidth="1.5" width="20" x="2" y="4" />+ <path d="M2 8h20" stroke="currentColor" strokeWidth="1.5" />+ <path+ d="m8 12 2 2-2 2m4 0h4"+ stroke="currentColor"+ strokeLinecap="round"+ strokeLinejoin="round"+ strokeWidth="1.5"+ />+ <circle cx="5" cy="6" fill="currentColor" r=".75" />+ </svg>+);+export const logos = {eve: eveLogo,web: webLogo,@@ -350,6 +365,7 @@ export const logos = {whatsapp: whatsappLogo,messenger: messengerLogo,x: xLogo,+ "agent-browser": agentBrowserLogo,} as const;export type LogoKey = keyof typeof logos;diff --git a/packages/eve-catalog/package.json b/packages/eve-catalog/package.jsonindex a48e3c44f..ac1437fbf 100644--- a/packages/eve-catalog/package.json+++ b/packages/eve-catalog/package.json@@ -2,7 +2,7 @@"name": "@vercel/eve-catalog","version": "0.0.1","private": true,- "description": "Single source of truth for eve integration identity (channels and connections).",+ "description": "Single source of truth for eve integration identity (channels, connections, and extensions).","license": "Apache-2.0","type": "module","sideEffects": false,diff --git a/packages/eve-catalog/src/index.test.ts b/packages/eve-catalog/src/index.test.tsindex 9b1bd43d8..de0d772a9 100644--- a/packages/eve-catalog/src/index.test.ts+++ b/packages/eve-catalog/src/index.test.ts@@ -5,6 +5,7 @@ import {channelEntries,connectionEntries,connectionProtocols,+ extensionEntries,getIntegrationEntry,} from "./index.js";@@ -14,8 +15,10 @@ describe("integration catalog", () => {expect(new Set(slugs).size).toBe(slugs.length);});- it("partitions cleanly into channels and connections", () => {- expect(channelEntries().length + connectionEntries().length).toBe(INTEGRATIONS.length);+ it("partitions cleanly into channels, connections, and extensions", () => {+ expect(channelEntries().length + connectionEntries().length + extensionEntries().length).toBe(+ INTEGRATIONS.length,+ );});it("gives every connection a transport and description", () => {@@ -32,6 +35,12 @@ describe("integration catalog", () => {}});+ it("keeps extensions free of connection identity", () => {+ for (const entry of extensionEntries()) {+ expect(entry.connection).toBeUndefined();+ }+ });+it("looks up entries by slug", () => {expect(getIntegrationEntry("linear")?.name).toBe("Linear");expect(getIntegrationEntry("nope")).toBeUndefined();diff --git a/packages/eve-catalog/src/index.ts b/packages/eve-catalog/src/index.tsindex 403ed6c03..703032217 100644--- a/packages/eve-catalog/src/index.ts+++ b/packages/eve-catalog/src/index.ts@@ -1,7 +1,7 @@/*** Shared identity for eve integrations. This package is the single source of- * truth for *which* integrations exist (channels and connections) and how a- * connection is wired (transport + model-facing description).+ * truth for *which* integrations exist (channels, connections, and extensions)+ * and how a connection is wired (transport + model-facing description).** Surface-specific concerns live with their consumer, keyed by {@link* IntegrationEntry.slug}: the scaffolder (eve) overlays the@@ -18,7 +18,7 @@*//** Surface an integration targets. Extend as new kinds are catalogued. */-export type IntegrationKind = "channel" | "connection";+export type IntegrationKind = "channel" | "connection" | "extension";/** Wire protocol a connection speaks at runtime. */export type ConnectionProtocol = "mcp" | "openapi";@@ -171,6 +171,13 @@ export const INTEGRATIONS: readonly IntegrationEntry[] = [tagline: "Facebook Messenger bots with templates, buttons, and reactions via the Chat SDK.",surfaces: { scaffoldable: false, gallery: true },},+ {+ slug: "agent-browser",+ name: "agent-browser",+ kind: "extension",+ tagline: "Add browser automation tools backed by agent-browser to an eve agent.",+ surfaces: { scaffoldable: false, gallery: true },+ },{slug: "linear",name: "Linear",@@ -606,3 +613,8 @@ export function connectionEntries(): IntegrationEntry[] {export function channelEntries(): IntegrationEntry[] {return integrationsByKind("channel");}++/** All extension entries, in catalog order. */+export function extensionEntries(): IntegrationEntry[] {+ return integrationsByKind("extension");+}