Add framework-first v3 docs#1462
Conversation
|
The latest Agentuity deployment details.
|
|
Important Review skippedToo many files! This PR contains 298 files, which is 148 over the limit of 150. To get a review, narrow the scope: ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: ⛔ Files ignored due to path filters (2)
📒 Files selected for processing (298)
You can disable this status message by setting the Use the checkbox below for a quick retry:
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
📦 Canary Packages Publishedversion: PackagesInstallAdd to your {
"dependencies": {
"@agentuity/vector": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-vector-3.0.5-f7da553.tgz",
"@agentuity/hono": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-hono-3.0.5-f7da553.tgz",
"@agentuity/drizzle": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-drizzle-3.0.5-f7da553.tgz",
"@agentuity/email": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-email-3.0.5-f7da553.tgz",
"@agentuity/migrate": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-migrate-3.0.5-f7da553.tgz",
"@agentuity/opencode": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-opencode-3.0.5-f7da553.tgz",
"@agentuity/db": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-db-3.0.5-f7da553.tgz",
"@agentuity/storage": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-storage-3.0.5-f7da553.tgz",
"@agentuity/aigateway": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-aigateway-3.0.5-f7da553.tgz",
"@agentuity/webhook": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-webhook-3.0.5-f7da553.tgz",
"create-agentuity": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/create-agentuity-3.0.5-f7da553.tgz",
"@agentuity/schedule": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-schedule-3.0.5-f7da553.tgz",
"@agentuity/cli": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-cli-3.0.5-f7da553.tgz",
"@agentuity/vite": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-vite-3.0.5-f7da553.tgz",
"@agentuity/pi": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-pi-3.0.5-f7da553.tgz",
"@agentuity/queue": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-queue-3.0.5-f7da553.tgz",
"@agentuity/task": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-task-3.0.5-f7da553.tgz",
"@agentuity/coder": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-coder-3.0.5-f7da553.tgz",
"@agentuity/stream": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-stream-3.0.5-f7da553.tgz",
"@agentuity/adapter": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-adapter-3.0.5-f7da553.tgz",
"@agentuity/server": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-server-3.0.5-f7da553.tgz",
"@agentuity/coder-tui": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-coder-tui-3.0.5-f7da553.tgz",
"@agentuity/sandbox": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-sandbox-3.0.5-f7da553.tgz",
"@agentuity/analytics": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-analytics-3.0.5-f7da553.tgz",
"@agentuity/keyvalue": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-keyvalue-3.0.5-f7da553.tgz",
"@agentuity/local": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-local-3.0.5-f7da553.tgz",
"@agentuity/claude-code": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-claude-code-3.0.5-f7da553.tgz",
"@agentuity/core": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-core-3.0.5-f7da553.tgz",
"@agentuity/schema": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-schema-3.0.5-f7da553.tgz",
"@agentuity/runtime": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-runtime-3.0.5-f7da553.tgz",
"@agentuity/postgres": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-postgres-3.0.5-f7da553.tgz",
"@agentuity/telemetry": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-telemetry-3.0.5-f7da553.tgz"
}
}Or install directly: bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-vector-3.0.5-f7da553.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-hono-3.0.5-f7da553.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-drizzle-3.0.5-f7da553.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-email-3.0.5-f7da553.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-migrate-3.0.5-f7da553.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-opencode-3.0.5-f7da553.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-db-3.0.5-f7da553.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-storage-3.0.5-f7da553.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-aigateway-3.0.5-f7da553.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-webhook-3.0.5-f7da553.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/create-agentuity-3.0.5-f7da553.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-schedule-3.0.5-f7da553.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-cli-3.0.5-f7da553.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-vite-3.0.5-f7da553.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-pi-3.0.5-f7da553.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-queue-3.0.5-f7da553.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-task-3.0.5-f7da553.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-coder-3.0.5-f7da553.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-stream-3.0.5-f7da553.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-adapter-3.0.5-f7da553.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-server-3.0.5-f7da553.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-coder-tui-3.0.5-f7da553.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-sandbox-3.0.5-f7da553.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-analytics-3.0.5-f7da553.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-keyvalue-3.0.5-f7da553.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-local-3.0.5-f7da553.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-claude-code-3.0.5-f7da553.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-core-3.0.5-f7da553.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-schema-3.0.5-f7da553.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-runtime-3.0.5-f7da553.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-postgres-3.0.5-f7da553.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/3.0.5-f7da553/agentuity-telemetry-3.0.5-f7da553.tgz |
This comment has been minimized.
This comment has been minimized.
- Reorganize docs around frameworks, build, and services - Add migration, deploy, and getting-started guidance - Align setup and storage docs with the current v3 CLI - Regenerate routes, nav data, schemas, and API references
parteeksingh24
force-pushed
the
docs/v3-docs
branch
from
4a18f63 to
4b49611
Compare
This comment has been minimized.
This comment has been minimized.
- refresh v3 docs from the section-by-section audit - replace stale beta install and create examples with next - reframe chat and handler demos around conversation and Hono routes - update migration, deploy, and service guidance to match current SDK
parteeksingh24
force-pushed
the
docs/v3-docs
branch
from
7c993c8 to
80f019e
Compare
- Drop `Community` from nav and docs home - Delete the `/community` page and orphaned assets - Leave cross-version fallback redirects for later
- split Build into Apps and APIs plus Agents - move agent docs under `/build/agents` - add Apps and APIs starter pages - refresh Home for the v3 docs IA - retune Explorer names, groups, and explanations - make Explorer sandbox output marker-based - pass org context into standalone service clients - add redirects for moved Build pages - type `@agentuity/hono` middleware for Hono apps
- Add cookbook patterns for evals, logs, and traces - Cover `OpenAI Evals` and `Braintrust` examples - Add `Pino`, `LogTape`, `OpenTelemetry`, and `Langfuse` guides - Clarify framework import flows for existing apps - Document local `@agentuity/cli` install and undo paths - Tighten framework build and deploy checks - Refresh get-started, service, reference, and migration docs - Regenerate docs nav, routes, and cookbook listings
- improve Explorer nav, redirects, and generated docs - clarify v3 app-owned service and framework workflows - add Coder, Sandbox, and service journey guidance - add Workflows API refs and queue state fixes - document app config versus Agentuity credentials
- move Ask AI out of v2-shaped demo agents - add tests for v3 docs assistant retrieval - fix docs dev proxy for legacy `/apis` redirects - clarify TanStack Start deploy and public dev setup - correct deploy docs and generated Gateway reference
- Add docs version picker and v2 docs entry point - Rework section indexes and Get Started ordering - Normalize ToC heading casing across docs - Clarify migration, launch metadata, and framework choice - Tighten service, reference, framework, and cookbook paths - Regenerate docs nav, routes, and generated outputs
- Update `robots.txt` sitemap URL - Generate sitemap entries from `agentuity.dev`
- Let `DocsChunkMetadata` satisfy vector metadata constraints - Restore `bun run typecheck` for the docs app
- Return `200` for Agentuity probe paths before SSR - Keep docs routes on the existing TanStack server
- Run MDX in Vite's `pre` phase before React - Cache hashed client assets from the Bun launcher - Validate model and query payloads without raw casts - Close full WebRTC rooms after sending `room-full`
|
The Prerequisites section presents Bun as a blanket requirement:
This is only true because of a bug in the create wrapper, not by design. As written, a Node/pnpm/yarn user reads "Bun is required" and reasonably assumes they're blocked from using Agentuity at all, which is false for everything except the one-time scaffold. I've filed the underlying wrapper bug: #1522. Once that lands, this section should:
|
|
Every Create example leads with Running
Worth noting too: if you run Please update the Create section to lead with the zero-arg interactive command, list the prompt walkthrough above, and present |
|
Docs default to Bun throughout; we want Node as the recommended default The quickstart explicitly hardcodes Bun as the package manager: bun create agentuity@next \
--name my-app \
--framework nextjs \
--package-manager bun # <- forces bunFor reference, the CLI itself does not hardcode bun — The bun-first convention is pervasive: ~90 content files use
The broader Recommendation:
Note this is partly blocked by #1522: until the create wrapper stops forcing |
|
Docs app bug: sidebar navigation doesn't reliably reset scroll to top Navigating between pages via the sidebar can leave you partway down the new page instead of at the top. The scroll-reset intent is already in React.useLayoutEffect(() => {
if (!location.hash) {
mainRef.current?.scrollTo(0, 0);
}
}, [location.pathname, location.hash]);
// ...
<main ref={mainRef} className="flex-1 overflow-y-auto">But it only works when
Filed as #1523 with repro and suggested fix (reset the real scroll container — |
|
Framework AI examples should lead with The Next.js "Provider SDK Env Wiring Example" centers the raw OpenAI SDK: bun add openai zodimport OpenAI from 'openai';
const openai = new OpenAI();
const completion = await openai.chat.completions.create({ model, messages });This isn't Next-specific — the same
The problem: the framework happy-path example teaches a dedicated single-provider SDK as the default way to call a model. We want these to lead with Recommendation:
Out of scope / leave as-is where the provider is the point: |
|
Follow-up to the AI-gateway comment: also drop the model-specific env vars from the deployed env tables Each framework page has a "Deployed environment variables" table whose model rows only exist to support the OpenAI-SDK example. When those examples move to
Rows to remove from the deployed list once the example uses the gateway:
The gateway path authenticates with the project's Keep provider env vars documented only where a page intentionally keeps a provider SDK (e.g. |
|
Build → Agents: AI SDK / single-provider SDKs should default to Same theme as the framework pages. The Build → Agents section is mixed —
We want the gateway to be the default path here too, with the value made explicit: one Agentuity project credential reaches the whole catalog (OpenAI, Anthropic, Google Gemini, Groq, xAI, DeepSeek, Mistral, Perplexity, OSS, Poolside), versus a dedicated SDK that only ever reaches one provider. Accurate guidance based on the gateway API (
Recommendation:
This also lets the per-provider model env ( |
|
This page should not mention or reference the deprecated
Also clean up the remaining reference on this page so nothing points back at the removed section:
The page already documents the supported path (standard Drizzle Related (same deprecated package, flagging for consistency — not asking to fix here unless you want to): |
|
Follow-up on the To be clear on why this section should go entirely, not just be softened: So this isn't "deprecated but keep it around for Bun users" — the docs should stop presenting it as a supported option at all, because the platform-level fix removed the need for it. That's the framing for the removal here and for the sibling references on |
|
Before the migration steps begin (above "Before You Start", near the top of the page), add a prominent banner that sets expectations about which path we actually recommend. Right now the page jumps straight into the dry-run command, and the "you'll get Hono + Vite" detail is buried in a tip further down under "Choose the Final App Shape". The banner should say, clearly and up front:
Suggested as a |
|
Drop the The docs pin every Agentuity package to the Scope (so this is a clean find-replace at launch, not a scramble):
Important: this is gated on the v3 release actually being promoted to |
- Make `npm create` and `npx agentuity` the default path - Keep Bun as a supported package-manager option - Remove Bun-only wording from framework and service docs - Add the TanStack Start server-route version gotcha - Align the TanStack Start fixture package versions
# Conflicts: # packages/create-agentuity/README.md
- Frame v2 migration as a framework port, not a Hono lock-in - Document v3 local CLI delegation and v2 deploy handoff - Point framework examples at `AIGatewayClient` defaults - Replace deprecated DB helpers with `pg` and Drizzle paths - Cover zero-arg create flow, rollback, and `.agentuity/`
- Split MDX pages into route-level chunks - Generate frontmatter metadata for layout lookups - Route docs links through TanStack `Link` - Preserve MDX hash links with router `hash` - Keep v2 docs links in a new tab - Remove hydration flashes from docs controls - Stream Explorer sandbox output from protocol frames - Ignore sandbox logger noise outside output frames - Return JSON errors for demo API failures - Validate route wrappers and frontmatter metadata - Update `sdk-explorer-v3` snapshot wiring
parteeksingh24
changed the title
v3 docs- Group Cookbook patterns without changing recipe URLs - Align nested sidebar rows with v2 docs behavior - Emit API reference routes in the current `MDXPage` shape - Keep route wrappers stable before `validate-routes` runs
- Rebuild snapshots when Explorer scripts or SDK clients change - Route Explorer docs links through TanStack `Link` - Keep external `docsUrl` values as new-tab fallback links - Run database demo with `pg` and `drizzle-orm` - Drop deprecated `@agentuity/drizzle` from docs deps - Verify `sdk-explorer-v3:latest` emits structured frames
- Split Ask AI content behind a lazy search chunk - Generate route paths for MDX link decisions - Cover route, query, hash, and external MDX links
- Use `AIGatewayClient` for Explorer model calls - Add Gateway streaming helpers for stream demos - Move docs sync into `services/docs-sync` - Let Agentuity Vector own docs-sync embeddings - Declare `@agentuity/aigateway` in docs - Align docs workspace on Zod 4 - Keep SDK Explorer snapshot private to the docs org - Polish WebRTC tiles and search shortcut behavior
- Document shared-host and bucket-scoped `AWS_ENDPOINT`
2 participants
Note: this branch was rebuilt on top of
mainafter an unintended sync withorigin/v3pulled beta-line changes into the PR history.Summary
Link, including hash links and footer/sidebar navigationsdk-explorer-v3snapshotApproach Notes
This PR keeps the docs deployed through Agentuity, but changes the docs app build and runtime path to TanStack Start:
bun run buildruns the TanStack Start Vite buildbun run startservesdist/server.jsagentuity deploy --dir .remains the deployment entry pointThe old runtime/Hono redirect layer still exists for Agentuity app wiring, but the built docs server now owns the redirect behavior used by local and packaged Start output.
Review Notes
docs/src/web/routes/_docs/**changes are generated route wrappers.frontmatter-data.tsis generated from MDX frontmatter so layout/footer metadata no longer requires eager-loading every MDX page.mdx-page.tsx,mdx-components.tsx,router.tsx,app-sidebar.tsx,docs-version-picker.tsx, andvalidate-routes.ts.route.ts,output-forwarder.ts,sandbox-output-protocol.ts,sandbox-output-writer.ts,useSandboxRunner.ts, and thedocs/src/run/**scripts.Verification
cd docs && bun run scripts/validate-routes.ts --checkcd docs && bun test src/api/test/sandbox-output-forwarder.test.ts src/web/hooks/useSandboxRunner.test.tscd docs && bun test src/web/components/docs/mdx-components.test.tsxcd docs && bun run typecheckcd docs && bun run buildgit diff --check && git diff --cached --checkhttp://localhost:3000/frameworks/nextjs,/build/agents, and/services/ai-gatewayreturned200/agents/ai-gateway,/demo/ai-gateway,/frontend/rpc-client, and/reference/sdk-reference/storagereturned3018,918,829 Bto1,588,489 B; click-to-heading dropped from219.1 msto71.4 ms