Skip to content

Add CopilotKit agent framework guide#1031

Open
jerelvelarde wants to merge 6 commits into
ArcadeAI:mainfrom
jerelvelarde:add-copilotkit-agent-framework-guide
Open

Add CopilotKit agent framework guide#1031
jerelvelarde wants to merge 6 commits into
ArcadeAI:mainfrom
jerelvelarde:add-copilotkit-agent-framework-guide

Conversation

@jerelvelarde

@jerelvelarde jerelvelarde commented Jun 24, 2026 •
edited
Loading

Copy link
Copy Markdown

What this PR does

Adds a CopilotKit guide to the agent-frameworks section, mirroring the existing Mastra and Vercel AI framework pages.

This is the reciprocal of CopilotKit/CopilotKit#5514, where Arcade added a CopilotKit cookbook recipe into CopilotKit's docs — this PR brings the equivalent "use Arcade with CopilotKit" guide into the Arcade docs.

The guide gives a CopilotKit Built-in Agent OAuth-backed Arcade tools (Gmail, Google News) and renders Arcade's one-time authorization step as a generative-UI Connect card in the chat. It covers:

  • wrapping Arcade tools with defineTool
  • the authorize-then-execute pattern (runArcadeTool)
  • mounting the agent on a single-route CopilotRuntime
  • rendering the authorization step as generative UI with useRenderTool

Changes

  • New page: app/en/get-started/agent-frameworks/copilotkit/page.mdx
  • Nav: registered copilotkit in app/en/get-started/agent-frameworks/_meta.tsx
  • Card: added a CopilotKit card to the JavaScript tab in app/_components/agent-framework-tabs.tsx
  • Icon: public/images/icons/copilotkit.svg (official CopilotKit mark)
  • Test: tests/copilotkit-guide.test.ts (contract test, written test-first)

Testing

  • pnpm test — full suite green (57 files, 742 tests), including broken-link-check and internal-link-check with the new page present
  • pnpm exec ultracite check — clean on the changed files
  • New page compiles via @mdx-js/mdx
  • Internal links limited to verified routes (/resources/integrations, /guides/user-facing-agents/secure-auth-production); all CopilotKit links point to https://docs.copilotkit.ai; no absolute docs.arcade.dev links

next build was not run locally (full-site build) — relying on CI. Vale isn't installed in the authoring environment, so please confirm pnpm vale:check in CI/review.

Review

A 7-reviewer code-review pass ran on the diff. Fixes applied (commit Harden the CopilotKit guide after code review):

  • False-success render path: the success card now renders only on the positive authorizationRequired === false discriminant; an unparseable/missing tool result renders an error card instead of a green "sent" card (it previously contradicted the guide's own "failures come back as data" Callout).
  • Restored a "Before you expose this publicly" warning callout (authenticate the runtime, scope every call to a server-verified user, disposable keys + rate limiting + security headers).
  • Tightened the contract test and bumped the Node prerequisite to 20+.

Verified-and-dismissed: Gmail.ListEmails correctly takes n_emails (per the repo's own toolkit-docs-generator/data/toolkits/gmail.json); GuideOverview/DashboardLink are global components in mdx-components.ts. Deferred as matching the upstream Arcade-authored recipe / SDK contract: the success === false check and the runtime auth gate's dev-open default (the restored callout documents the hardening).

Optional follow-up

  • Deep-link the "CopilotKit concepts" bullets to specific docs pages rather than the docs homepage (left as the root URL because specific paths weren't verified).

🤖 Generated with Claude Code

@jerelvelarde @claude
Add CopilotKit agent framework guide
ae3965b 
Add a guide for using Arcade tools with CopilotKit, mirroring the existing
Mastra and Vercel AI framework pages. It covers wrapping Arcade tools with
defineTool, the authorize-then-execute pattern, a single-route CopilotRuntime,
and rendering the authorization step as generative UI with useRenderTool.

- New page: app/en/get-started/agent-frameworks/copilotkit/page.mdx
- Register the page in agent-frameworks/_meta.tsx
- Add a CopilotKit card to the JavaScript tab in agent-framework-tabs.tsx
- Add public/images/icons/copilotkit.svg
- Add tests/copilotkit-guide.test.ts (contract test, written test-first)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@vercel

vercel Bot commented Jun 24, 2026

Copy link
Copy Markdown

@jerelvelarde is attempting to deploy a commit to the Arcade AI Team on Vercel.

A member of the Team first needs to authorize it.

jerelvelarde and others added 4 commits June 24, 2026 07:55
@jerelvelarde @claude
Use the official CopilotKit logo mark
9e9f6f2 
Replace the placeholder icon with CopilotKit's authoritative brand mark
and drop invertInDark on the card, since the mark is full-color (matching
the CrewAI / Google ADK full-color icon pattern rather than the monochrome
invert pattern).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@jerelvelarde @claude
Harden the CopilotKit guide after code review
261d977 
A 7-reviewer pass surfaced a false-success render path and a dropped
security note; fix both and tighten the contract test.

- Render: show the "email sent" card only on the positive success
  discriminant (authorizationRequired === false). An unparseable or
  missing tool result now renders an error card instead of a false
  green "sent" card, in both the inline snippet and the full-file
  listing. This matches the guide's own "failures come back as data"
  Callout, which the render layer previously contradicted.
- Restore a "Before you expose this publicly" warning callout
  (authenticate the runtime, scope every call to a server-verified
  user, disposable keys + rate limiting + security headers) that the
  adaptation had dropped from the upstream recipe.
- Bump the Node prerequisite to 20+ (the CopilotKit v2 / Next.js stack
  needs it; Node 18 is end-of-life).
- Tighten the contract test: assert the _meta key and title together,
  require non-empty frontmatter values, check the SVG closing tag, and
  hoist regexes to module scope. Update the stale header comment.

Deferred as matching the authoritative Arcade-authored recipe / SDK
contract: the success===false failure check and the runtime auth gate's
dev-open default (the restored callout documents the hardening steps).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@jerelvelarde @claude
Fix Nextra compile error: use filename= on code fences
94385eb 
`title=` on code fences (carried over from the upstream Starlight-based
recipe) broke Nextra's rehype pipeline with "Cannot convert undefined or
null to object", returning a 500 for the page. The Arcade docs use
`filename=` for code-block labels (150 existing usages); switch all six
fences to match. Caught by rendering the page in the local dev server —
the unit tests and an mdx-js compile check don't exercise Nextra's loader.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@jerelvelarde @claude
Add page title and a CopilotKit scaffold command
efb0015 
Local preview review surfaced two gaps:
- The page rendered no title. Nextra does not promote the frontmatter
  `title` to an on-page H1 (the Vercel AI guide includes an explicit
  one); add `# Build an AI agent with Arcade and CopilotKit`.
- Step 1 linked to the quickstart but showed no create command, unlike
  the Mastra/Vercel guides. Add `npx copilotkit@latest init` (CopilotKit
  CLI) in the package-manager tabs before the Arcade SDK install.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@jerelvelarde

jerelvelarde commented Jun 24, 2026

Copy link
Copy Markdown
Author

Heads up for review: the <button>-in-<button> hydration errors visible on this page come from a pre-existing bug in the glossary auto-linker (lib/remark-glossary.ts), not this page's MDX — a term-dense page just surfaces it. Fix filed separately in #1032 to keep this PR scoped to docs content.

@jerelvelarde

jerelvelarde commented Jun 24, 2026

Copy link
Copy Markdown
Author

📸 Preview

The new guide rendered locally at /en/get-started/agent-frameworks/copilotkit:

CopilotKit × Arcade guide

Shows the page title, the GuideOverview (outcomes / prerequisites — note Node 20+ / what you'll learn), the CopilotKit concepts list, and step 1 — scaffold with npx copilotkit@latest init, then install the Arcade SDK — plus the new CopilotKit entry in the Agent Frameworks sidebar.

@thierrypdamiba thierrypdamiba self-requested a review June 24, 2026 20:25
@jerelvelarde @claude
docs(copilotkit): fix scaffold path, typed tool result, and provider …
c43db05 
…wiring

Validated the guide by building it as a runnable app — a Next.js demo that
reproduces the three "Complete code" files verbatim. The build surfaced fixes:

- Step 1: replace `copilotkit init` (interactive-only, account-gated, and with
  no Built-in Agent template) with `create-next-app` plus explicit installs,
  the path that actually reproduces the app.
- Install `zod` (both files import it; it otherwise resolves only as a peer
  dependency of the CopilotKit packages).
- `app/page.tsx`: parse into a discriminated-union `ToolResult` instead of
  `any`, so the sample passes `eslint` (no-explicit-any) as well as `tsc`.
- Show the `<CopilotKit>` provider wiring (`app/providers.tsx` and
  `app/layout.tsx`); the provider is a client component the prose only described.
- Note that `BuiltInAgent` model ids are `provider/model` strings.

Extend the contract test to lock in these invariants.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@jerelvelarde jerelvelarde marked this pull request as ready for review June 26, 2026 11:39
@jerelvelarde

jerelvelarde commented Jun 26, 2026

Copy link
Copy Markdown
Author

Flipping this out of draft — ready for review. ✅

Heads-up on the red checks: they're all fork-PR infrastructure limitations, not content problems.

  • Vale Style Review — runs an AI review (scripts/vale-style-review.ts) that needs ANTHROPIC_API_KEY / OPENAI_API_KEY; GitHub withholds repo secrets from fork PRs, so it exits before reviewing (ANTHROPIC_API_KEY or OPENAI_API_KEY is required).
  • Generate LLMSTXT — Input required and not supplied: token (it auto-commits via a token forks don't receive).
  • Vercel — the fork-deploy authorization gate.

Every substantive check is green on the head commit: test (full Vitest suite + internal/broken-link checks), External URL check, Verify Deleted Pages Have Redirects, and validate_schemas. Happy to re-run these from a branch on the main repo if you'd like the secret-gated ones to actually execute.

For extra confidence, the code samples were validated by building them as a runnable Next.js app — tsc, eslint, and next build all pass and the chat UI runs live against the v2 single-route runtime. That pass surfaced the fixes in the latest commit: the real scaffold path (create-next-app rather than copilotkit init, which is interactive-only with no Built-in Agent template), a typed tool result that satisfies no-explicit-any, installing zod, and the <CopilotKit> provider wiring.

cc @thierrypdamiba

🤖 Generated with Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@thierrypdamiba thierrypdamiba Awaiting requested review from thierrypdamiba

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@jerelvelarde