The Open Framework for Building Agents
docs: add a use cases page (#5204)
Shar3c03b204d0fa
diff --git a/apps/docs/components/geistdocs/mdx-components.tsx b/apps/docs/components/geistdocs/mdx-components.tsxindex 5ed5bcbfc..453b00abf 100644--- a/apps/docs/components/geistdocs/mdx-components.tsx+++ b/apps/docs/components/geistdocs/mdx-components.tsx@@ -6,6 +6,14 @@ import type { MDXComponents } from "mdx/types";import Link from "next/link";import { AgentRuntimeDiagram } from "./agent-runtime-diagram";import { EveCodeBenchmark } from "./eve-code-benchmark";+import {+ Capabilities,+ Capability,+ TemplateCard,+ TemplateCards,+ UseCaseSummaries,+ UseCaseSummary,+} from "./use-cases";const localComponents: MDXComponents = {a: ({ href, ...props }) =>@@ -24,9 +32,15 @@ const localComponents: MDXComponents = {Flag,Folder,AgentRuntimeDiagram,+ Capabilities,+ Capability,EveCodeBenchmark,Step,Steps,+ TemplateCard,+ TemplateCards,+ UseCaseSummaries,+ UseCaseSummary,};export const getMDXComponents = (components?: MDXComponents): MDXComponents =>diff --git a/apps/docs/components/geistdocs/use-cases.tsx b/apps/docs/components/geistdocs/use-cases.tsxnew file mode 100644index 000000000..13aa428db--- /dev/null+++ b/apps/docs/components/geistdocs/use-cases.tsx@@ -0,0 +1,225 @@+import { SiImessage } from "@icons-pack/react-simple-icons";+import {+ IconArchive,+ IconArrowUpRightSmall,+ IconBox,+ IconCheck,+ IconChevronRightSmall,+ IconClock,+ IconLinked,+ IconLogs,+ IconMessage,+ IconSandbox,+ IconShieldCheck,+ IconSparkles,+ IconToggleOn,+ IconUser,+ IconWorkflow,+ IconWrench,+} from "@vercel/geistdocs/assets/icons";+import Link from "next/link";+import type { JSX, ReactNode } from "react";+import { integrationIcons } from "@/app/[lang]/templates/integration-icons";+import { templatePath } from "@/lib/geistdocs/canonical";+import { logos } from "@/lib/integrations/logos";+import { templateManifest } from "@/lib/templates/manifest";++const capabilityIcons = {+ approval: <IconUser size={16} />,+ channels: <IconMessage size={16} />,+ connections: <IconLinked size={16} />,+ durability: <IconWorkflow size={16} />,+ dynamic: <IconToggleOn size={16} />,+ evals: <IconCheck size={16} />,+ identity: <IconShieldCheck size={16} />,+ memory: <IconArchive size={16} />,+ models: <IconSparkles size={16} />,+ observability: <IconLogs size={16} />,+ sandbox: <IconSandbox size={16} />,+ schedules: <IconClock size={16} />,+ tenancy: <IconBox size={16} />,+ tools: <IconWrench size={16} />,+} satisfies Record<string, ReactNode>;++const iconClassName = "size-4 shrink-0";++const channels = {+ discord: {+ label: "Discord",+ logo: logos.discord({ "aria-hidden": true, className: iconClassName }),+ },+ github: {+ label: "GitHub",+ logo: logos.github({ "aria-hidden": true, className: iconClassName }),+ },+ imessage: { label: "iMessage", logo: <SiImessage aria-hidden className={iconClassName} /> },+ linear: {+ label: "Linear",+ logo: logos.linear({ "aria-hidden": true, className: iconClassName }),+ },+ slack: { label: "Slack", logo: logos.slack({ "aria-hidden": true, className: iconClassName }) },+ teams: {+ label: "Microsoft Teams",+ logo: logos.teams({ "aria-hidden": true, className: iconClassName }),+ },+ telegram: {+ label: "Telegram",+ logo: logos.telegram({ "aria-hidden": true, className: iconClassName }),+ },+ web: { label: "Web", logo: logos.web({ "aria-hidden": true, className: iconClassName }) },+ whatsapp: {+ label: "WhatsApp",+ logo: logos.whatsapp({ "aria-hidden": true, className: iconClassName }),+ },+} satisfies Record<string, { label: string; logo: ReactNode }>;++const cardClassName =+ "group flex h-full min-w-0 flex-col rounded-xl border border-gray-alpha-400 bg-background-100 p-4 no-underline transition-colors hover:border-gray-alpha-600 sm:p-5";++export function UseCaseSummaries({ children }: { children: ReactNode }): JSX.Element {+ return <div className="not-prose my-8 grid min-w-0 gap-4 sm:grid-cols-2">{children}</div>;+}++/** Links to a use case section and lists the channels it usually runs in. */+export function UseCaseSummary({+ audience,+ title,+ href,+ channels: channelIds,+ children,+}: {+ audience: string;+ title: string;+ href: string;+ channels: (keyof typeof channels)[];+ children: ReactNode;+}): JSX.Element {+ return (+ <a className={`${cardClassName} gap-5`} href={href}>+ <div className="flex flex-col gap-1">+ <span className="text-copy-13 text-gray-900">{audience}</span>+ <span className="flex items-center justify-between gap-2 text-gray-1000 text-heading-20">+ {title}+ <IconChevronRightSmall+ className="shrink-0 text-gray-700 transition-transform group-hover:translate-x-0.5 group-hover:text-gray-1000"+ size={16}+ />+ </span>+ <div className="text-copy-14 text-gray-900">{children}</div>+ </div>+ <ul aria-label="Common channels" className="mt-auto flex list-none flex-wrap gap-2 p-0">+ {channelIds.map((id) => (+ <li+ className="flex items-center gap-1.5 rounded-full px-2.5 py-1 text-copy-13 text-gray-1000 material-small"+ key={id}+ >+ <span className="flex text-gray-900 grayscale">{channels[id].logo}</span>+ {channels[id].label}+ </li>+ ))}+ </ul>+ </a>+ );+}++export function TemplateCards({ children }: { children: ReactNode }): JSX.Element {+ return (+ <div className="not-prose my-6 grid min-w-0 gap-4 sm:grid-cols-2 lg:grid-cols-3">+ {children}+ </div>+ );+}++/** Opens a template from the gallery, showing its integrations. */+export function TemplateCard({+ title,+ template: slug,+ label,+ children,+}: {+ title: string;+ template: string;+ /** Shorter link label for templates whose gallery title is long. */+ label?: string;+ children: ReactNode;+}): JSX.Element {+ const template = templateManifest.find((entry) => entry.slug === slug);+ if (!template) throw new Error(`Unknown template "${slug}" in a TemplateCard.`);+ return (+ <Link className={`${cardClassName} gap-2`} href={templatePath(slug)} prefetch={true}>+ <span className="flex items-start justify-between gap-2 text-gray-1000 text-heading-16">+ {title}+ <IconArrowUpRightSmall+ className="mt-0.5 shrink-0 text-gray-700 transition-transform group-hover:-translate-y-0.5 group-hover:translate-x-0.5 group-hover:text-gray-1000"+ size={16}+ />+ </span>+ <div className="text-copy-14 text-gray-900">{children}</div>+ <span className="mt-auto flex flex-col gap-2 pt-3">+ <span className="flex items-center gap-1.5 text-gray-900 grayscale">+ {template.integrations.map((integration) => {+ // Linq delivers iMessage, and readers recognize the iMessage mark.+ if (integration === "Linq") {+ return (+ <SiImessage+ aria-label="iMessage"+ className="size-3.5"+ key={integration}+ role="img"+ />+ );+ }+ const Icon = integrationIcons[integration];+ return (+ <Icon aria-label={integration} className="size-3.5" key={integration} role="img" />+ );+ })}+ </span>+ <span className="text-copy-13 text-gray-900">{label ?? template.title} template</span>+ </span>+ </Link>+ );+}++export function Capabilities({ children }: { children: ReactNode }): JSX.Element {+ return (+ <ul className="not-prose my-6 min-w-0 list-none border-gray-alpha-400 border-y p-0">+ {children}+ </ul>+ );+}++/** One capability row: what the use case needs, how eve covers it, and the docs page. */+export function Capability({+ icon,+ title,+ href,+ link,+ children,+}: {+ icon: keyof typeof capabilityIcons;+ title: string;+ href: string;+ link: string;+ children: ReactNode;+}): JSX.Element {+ return (+ <li className="flex min-w-0 gap-4 border-gray-alpha-400 border-b py-5 last:border-b-0">+ <span className="flex size-8 shrink-0 items-center justify-center rounded-md text-gray-1000 material-small">+ {capabilityIcons[icon]}+ </span>+ <div className="flex min-w-0 flex-col gap-1.5 pt-1">+ <span className="text-gray-1000 text-heading-16">{title}</span>+ <div className="max-w-[60ch] text-copy-14 text-gray-900">{children}</div>+ <Link+ className="mt-1 flex w-fit items-center gap-0.5 font-medium text-copy-14 text-gray-1000 no-underline hover:underline"+ href={href}+ prefetch={true}+ >+ {link}+ <IconChevronRightSmall className="text-gray-900" size={16} />+ </Link>+ </div>+ </li>+ );+}diff --git a/apps/docs/lib/geistdocs/remark-component-markdown.test.ts b/apps/docs/lib/geistdocs/remark-component-markdown.test.tsindex 94d64df21..82e4bf400 100644--- a/apps/docs/lib/geistdocs/remark-component-markdown.test.ts+++ b/apps/docs/lib/geistdocs/remark-component-markdown.test.ts@@ -3,13 +3,17 @@ import { toMarkdown, type Options } from "mdast-util-to-markdown";import { describe, expect, it } from "vitest";import config from "../../source.config";+async function configuredProcessor() {+ const options =+ typeof config.mdxOptions === "function" ? await config.mdxOptions() : config.mdxOptions;+ const plugins = options?.remarkPlugins;+ if (!Array.isArray(plugins)) throw new Error("Expected configured remark plugins");+ return createProcessor({ remarkPlugins: plugins });+}+describe("component Markdown export", () => {it("expands the runtime diagram without changing HTML or component examples", async () => {- const options =- typeof config.mdxOptions === "function" ? await config.mdxOptions() : config.mdxOptions;- const plugins = options?.remarkPlugins;- if (!Array.isArray(plugins)) throw new Error("Expected configured remark plugins");- const processor = createProcessor({ remarkPlugins: plugins });+ const processor = await configuredProcessor();const source = ["## Agent loop and sandbox","",@@ -66,4 +70,42 @@ describe("component Markdown export", () => {expect.objectContaining({ type: "mdxJsxFlowElement", name: "AgentRuntimeDiagram" }),);});++ it("renders use case cards as Markdown lists with their titles and links", async () => {+ const processor = await configuredProcessor();+ const source = [+ "<UseCaseSummaries>",+ ' <UseCaseSummary audience="For your team" title="Business agents" href="#business-agents" channels={["slack"]}>',+ " Automate a company function.",+ " </UseCaseSummary>",+ "</UseCaseSummaries>",+ "",+ "<TemplateCards>",+ ' <TemplateCard title="iMessage agent" template="openinstinct-eve-template" label="iMessage">',+ " A multi-tenant iMessage service.",+ " </TemplateCard>",+ "</TemplateCards>",+ "",+ "<Capabilities>",+ ' <Capability icon="channels" title="Meet employees where they work" href="/docs/channels/overview" link="Channels">',+ " One agent serves Slack and",+ " your own web apps.",+ " </Capability>",+ "</Capabilities>",+ ].join("\n");+ const markdown = toMarkdown(processor.parse(source), {+ extensions: (processor.data() as { toMarkdownExtensions?: Options[] }).toMarkdownExtensions,+ });++ expect(markdown).toContain(+ "- **[Business agents](#business-agents)** (For your team): Automate a company function.",+ );+ expect(markdown).toContain(+ "- **iMessage agent**: A multi-tenant iMessage service. See the [iMessage template](/templates/openinstinct-eve-template).",+ );+ expect(markdown).toContain(+ "- **Meet employees where they work**: One agent serves Slack and your own web apps. See [Channels](/docs/channels/overview).",+ );+ expect(markdown).not.toMatch(/<(UseCase|Template|Capabilit)/);+ });});diff --git a/apps/docs/lib/geistdocs/remark-component-markdown.ts b/apps/docs/lib/geistdocs/remark-component-markdown.tsindex 0008b2b22..e5187d383 100644--- a/apps/docs/lib/geistdocs/remark-component-markdown.ts+++ b/apps/docs/lib/geistdocs/remark-component-markdown.ts@@ -2,7 +2,42 @@ import { mdxJsxToMarkdown, type MdxJsxFlowElement } from "mdast-util-mdx-jsx";import type { Options } from "mdast-util-to-markdown";import { renderBenchmarkMarkdown } from "../evals/eve-code-format";import { eveCodeBenchmark } from "../evals/eve-code-results";+import { templateManifest } from "../templates/manifest";import { renderAgentRuntimeDiagramMarkdown } from "./agent-runtime-diagram";+import { templatePath } from "./canonical";++type CardProps = Partial<Record<string, string>>;++// Card components keep their copy in MDX props and children; render each as one list item.+const cardMarkdown = new Map<string, (props: CardProps, text: string) => string>([+ [+ "UseCaseSummary",+ (props, text) => `- **[${props.title}](${props.href})** (${props.audience}): ${text}`,+ ],+ [+ "TemplateCard",+ (props, text) => {+ const template = templateManifest.find((entry) => entry.slug === props.template);+ if (!template) throw new Error(`Unknown template "${props.template}" in a TemplateCard.`);+ const label = `${props.label ?? template.title} template`;+ return `- **${props.title}**: ${text} See the [${label}](${templatePath(template.slug)}).`;+ },+ ],+ [+ "Capability",+ (props, text) => `- **${props.title}**: ${text} See [${props.link}](${props.href}).`,+ ],+]);+const cardLists = new Set(["UseCaseSummaries", "TemplateCards", "Capabilities"]);++const stringProps = (node: MdxJsxFlowElement): CardProps =>+ Object.fromEntries(+ node.attributes.flatMap((attribute) =>+ attribute.type === "mdxJsxAttribute" && typeof attribute.value === "string"+ ? [[attribute.name, attribute.value]]+ : [],+ ),+ );// Customize serialization only: the MDX tree must keep the visual component for HTML.export function remarkComponentMarkdown(this: { data(): unknown }): void {@@ -22,6 +57,14 @@ export function remarkComponentMarkdown(this: { data(): unknown }): void {}return renderBenchmarkMarkdown(eveCodeBenchmark.datasets[dataset.value], dataset.value);}+ if (node.name && cardLists.has(node.name)) {+ return node.children.map((child) => state.handle(child, node, state, info)).join("\n");+ }+ const card = node.name ? cardMarkdown.get(node.name) : undefined;+ if (card) {+ const text = state.containerFlow(node, info).replace(/\s+/g, " ").trim();+ return card(stringProps(node), text);+ }return fallback(node, parent, state, info);},},diff --git a/docs/meta.json b/docs/meta.jsonindex 44e421fa0..787010386 100644--- a/docs/meta.json+++ b/docs/meta.json@@ -2,6 +2,7 @@"pages": ["---Introduction---","getting-started",+ "use-cases","tutorial","concepts","---Build---",diff --git a/docs/use-cases.mdx b/docs/use-cases.mdxnew file mode 100644index 000000000..acc741b6e--- /dev/null+++ b/docs/use-cases.mdx@@ -0,0 +1,250 @@+---+title: "Use Cases"+description: "The two most common use cases for eve are business agents that work for your own company and agents you ship to customers as a product."+---++eve gives you everything you need for production agents. The two most common use cases for eve are business agents that work for your own company and agents you ship to customers as a product.++<UseCaseSummaries>+ <UseCaseSummary+ audience="For your team"+ title="Business agents"+ href="#business-agents"+ channels={["slack", "teams", "github", "linear", "web"]}+ >+ Automate a company function, like analytics, a software factory, marketing, or finance.+ </UseCaseSummary>+ <UseCaseSummary+ audience="For your customers"+ title="Agent as a Service (AaaS)"+ href="#agent-as-a-service-aaas"+ channels={["imessage", "whatsapp", "telegram", "discord", "web"]}+ >+ Build multi-tenant agentic applications that scale as you grow.+ </UseCaseSummary>+</UseCaseSummaries>++## Business agents++A business agent takes on work for teams inside your company. The most common are software factories that plan, build, and review code alongside engineers, and company brains that answer employees' questions from internal data. Employees reach the agent in Slack, Microsoft Teams, or GitHub, and it acts on the company's own systems and data.++<TemplateCards>+ <TemplateCard title="Software factory" template="eve-software-factory-template">+ Agents plan features, open pull requests, review code, and respond to incidents alongside an+ engineering team.+ </TemplateCard>+ <TemplateCard title="Company brain" template="eve-company-brain-template">+ One agent holds the company's skills, tools, and approved connections, reachable where employees+ work, with each employee's own identity and connections.+ </TemplateCard>+ <TemplateCard+ title="Marketing team"+ template="marketing-team-eve-template"+ label="Marketing team"+ >+ A lead agent routes work to specialists for positioning, long-form content, social, SEO, and+ email, then publishes through Notion, Typefully, and Resend.+ </TemplateCard>+</TemplateCards>++### How eve supports business agents++An eve agent lives in [your repository](/docs/concepts/project-structure), so it is reviewed, deployed, and governed like the rest of your stack.++<Capabilities>+ <Capability+ icon="channels"+ title="Meet employees where they work"+ href="/docs/channels/overview"+ link="Channels"+ >+ One agent serves Slack, Microsoft Teams, GitHub, Linear, and your own web apps, with a session+ for every conversation.+ </Capability>+ <Capability+ icon="observability"+ title="Govern and audit every run"+ href="/docs/observability/instrumentation"+ link="Observability"+ >+ OpenTelemetry traces and Agent Runs record every session, model call, and tool call, so you can+ see what an agent did and why.+ </Capability>+ <Capability+ icon="identity"+ title="Use your identity provider"+ href="/docs/guides/auth-and-route-protection"+ link="Identity and access"+ >+ Verify callers with any OIDC issuer, JWTs, or your own authenticator. Each connection then acts+ as the agent itself or on behalf of the signed-in user.+ </Capability>+ <Capability+ icon="models"+ title="Switch models without a code rewrite"+ href="/docs/agent-config"+ link="Models"+ >+ Changing models is a one-line edit in agent.ts, and requests can fall back to another provider+ on failure.+ </Capability>+ <Capability+ icon="connections"+ title="Connect to approved services"+ href="/docs/connections"+ link="Connections"+ >+ Expose the MCP and OpenAPI services your IT team approves. Credentials stay in the runtime, and+ the model never sees them.+ </Capability>+ <Capability+ icon="evals"+ title="Evaluate agent responses"+ href="/docs/evals/overview"+ link="Evals"+ >+ Evals are automated tests that run the agent through real turns and score the result with code+ checks or a model judge, so you catch regressions when a prompt, tool, or model changes.+ </Capability>+ <Capability+ icon="tools"+ title="Put deterministic steps in the loop"+ href="/docs/tools/workflows"+ link="Workflow tools"+ >+ Tools are typed TypeScript functions the model chooses when to call. When a process must run the+ same way every time, use a workflow tool instead. Its code fixes the order of steps, calls+ subagents exactly where you say, and waits durably for approvals or webhooks between steps.+ </Capability>+ <Capability+ icon="sandbox"+ title="Run commands in sandboxed compute"+ href="/docs/sandbox"+ link="Sandbox"+ >+ Each session gets an isolated filesystem and shell for scripts, repositories, and generated+ files.+ </Capability>+ <Capability+ icon="approval"+ title="Keep a human in the loop"+ href="/docs/human-in-the-loop"+ link="Human-in-the-loop"+ >+ Sessions pause while an approval is pending and resume durably when it resolves. A decision+ model can auto-approve routine tool calls.+ </Capability>+</Capabilities>++## Agent as a Service (AaaS)++In AaaS, the agent is the product. One multi-tenant deployment serves many customers, and each of them trusts it with their work over long stretches of time. It has to serve every user durably and keep each tenant's data and identity separate from the next.++<TemplateCards>+ <TemplateCard title="Web chat" template="eve-chat-template">+ A Next.js chat app with sign-in, persisted conversations, and long-term memory for each user.+ </TemplateCard>+ <TemplateCard title="iMessage agent" template="openinstinct-eve-template" label="iMessage">+ A multi-tenant iMessage service with user accounts, scoped memory, an encrypted vault, and cloud+ browser automation.+ </TemplateCard>+ <TemplateCard title="Voice agent" template="eve-voice-template">+ Users talk to the agent in the browser while it runs tools, asks for approvals, and keeps+ durable state.+ </TemplateCard>+</TemplateCards>++### How eve supports AaaS++Each end user gets their own [sessions](/docs/concepts/sessions-runs-and-streaming) and connections, running on the same agent project you deploy once.++<Capabilities>+ <Capability+ icon="tenancy"+ title="Isolate every tenant"+ href="/docs/patterns/multi-tenant-auth"+ link="Multi-tenancy"+ >+ Bind memory, connection credentials, and approval policy to the authenticated tenant and user,+ so one customer's data and access never reach another.+ </Capability>+ <Capability+ icon="dynamic"+ title="Customize the agent per tenant"+ href="/docs/guides/dynamic-capabilities"+ link="Dynamic capabilities"+ >+ Resolve the model, tools, connections, skills, and instructions at runtime from the caller,+ their tenant, or a feature flag, all from one deployment.+ </Capability>+ <Capability+ icon="schedules"+ title="Run work on fixed and dynamic schedules"+ href="/docs/schedules"+ link="Schedules"+ >+ Fixed cron schedules power digests and monitors with no user present. Experimental dynamic+ schedules let users and agents create their own recurring or one-time runs at runtime.+ </Capability>+ <Capability+ icon="observability"+ title="Trace latency and every tool call"+ href="/docs/observability/agent-runs"+ link="Observability"+ >+ Traces and Agent Runs show per-turn latency and the tool calls behind each response.+ </Capability>+ <Capability+ icon="models"+ title="Route each request to the right model"+ href="/docs/guides/decide"+ link="Model selection"+ >+ Pick models per user, tenant, or feature, or let a decision model choose from your allowlist+ automatically, to balance cost, latency, and quality.+ </Capability>+ <Capability+ icon="durability"+ title="Keep long-running sessions durable"+ href="/docs/concepts/execution-model-and-durability"+ link="Durable sessions"+ >+ Each user's session checkpoints every step, parks while it waits, and resumes on the next+ message, even days later.+ </Capability>+ <Capability+ icon="memory"+ title="Keep long-term memory for each user"+ href="/docs/memory"+ link="Memory"+ >+ Each user gets their own long-term memory of preferences and facts. It carries across sessions,+ stays isolated from other users, and lives in the provider you choose.+ </Capability>+ <Capability+ icon="identity"+ title="Act on behalf of each user"+ href="/docs/connections"+ link="User-scoped connections"+ >+ Connections authenticate to services like GitHub and Linear with each user's own grant, so tools+ call them without managing tokens.+ </Capability>+ <Capability+ icon="sandbox"+ title="Run untrusted input in isolation"+ href="/docs/sandbox"+ link="Sandbox and subagents"+ >+ Each session processes user data in its own sandbox. Subagents take work that needs its own+ prompt, tools, or sandbox.+ </Capability>+</Capabilities>++## Start building++Create an agent and open the terminal UI.++```bash+npx eve@latest init my-agent+```