feat(agent-studio): add Agent Studio frontend chat skill - #32
Open
leonardocuco wants to merge 13 commits into
Open
feat(agent-studio): add Agent Studio frontend chat skill#32leonardocuco wants to merge 13 commits into
leonardocuco wants to merge 13 commits into
Conversation
Adds an `agent-studio` skill for building agentic chat experiences on a website with Agent Studio and the react-instantsearch Chat widget: widget setup and custom transport, client-side tools, Algolia Insights (business) events, secure user authentication, memory/personalization, context injection, prompt starters, and CSS customization. Registered in .claude-plugin/marketplace.json and the README skills table. Passes scripts/validate_skills.py (52 passed, 0 failed). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…search The chat agent runs its searches server-side; the algolia_search tool result streamed to the client carries the queryID (searches run with clickAnalytics enabled and the alg#agent-studio tag). Document reading that queryID from the tool result and sending click-after-search and conversion-after-search Insights events, so the agent's click-through, conversion, and revenue analytics are attributed to its searches. Adds a chat-attribution section to references/insights-events.md, a SKILL.md bullet and pointer, and an eval. Validator: 52 passed, 0 failed. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
connection-setup.md already documents enabling the Productivity MCP server (as a prerequisite and as Method 2 Step 1), but the always-loaded SKILL.md "Connection setup" section jumped straight to mcp-connect. Name the one-time dashboard toggle there so the assistant surfaces it without opening the reference. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The non-interactive `algobot profiles add` examples showed only --name and --env, which creates an unauthenticated profile, so commands fail. Surfaced while dogfooding the build-an-agent flow. Updated SKILL.md and references/commands.md to pass --app-id and --api-key (Admin key), with --default-agent-id pending when no agent exists yet, and to read the key from an environment variable. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The search tool config gained `mode` (static/dynamic) and `allowUnlistedIndices` with the dynamic-index change (#1262). The config-as-code guide only showed the minimal static form. Documented the `mode` field, per-request `algolia.indices` override (subset by default, 422 on net-new names unless allowUnlistedIndices), and the per-index enhancedDescription / searchParameters / searchControls fields. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Update the agent-creation examples (SKILL.md and config-as-code.md) from gpt-4o to gpt-5.6-luna, the cost-efficient GPT-5.6 tier, and note it as the recommended default when using an OpenAI provider. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Change the recommended agent-creation model from gpt-5.6-luna to gpt-5.6-terra (the balanced cost/quality GPT-5.6 tier) in SKILL.md and config-as-code.md. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…ext.js note - Correct the search tool name to algolia_search_index at the source (SKILL.md, references/insights-events.md, evals/evals.json) and reframe attribution to iterate streamed tool result parts keyed on queryID+hits, noting the tool name is configurable (never hardcode it). - Add a "Framework notes" section: the examples target a client-rendered React app (Vite/CRA); for Next.js App Router use "use client", NEXT_PUBLIC_* env vars, and <InstantSearchNext>. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
A runnable reference app (examples/coding-with-ai-nextjs) that embeds Algolia search + an Agent Studio chat agent on a Next.js App Router site: InstantSearchNext provider, the <Chat> widget with an authenticated transport (compatibilityMode=ai-sdk-5), a token-mint Route Handler (HS256 JWT, kid+sub), a client-side add_to_cart tool via the layoutComponent pattern, and business-event attribution. Attribution reads the queryID from each hit (item.__queryID) in the itemComponent — clicks via the built-in sendEvent, add-to-cart looks up the recorded queryID for a conversion-after-search — rather than a footer component or a hardcoded tool name. Passes `npm run typecheck`. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…ttern Verifying the reference app showed the previous guidance (read the assistant message parts in a footer component) is not wired-able: the library's assistantMessageFooterComponent receives no message. Rewrite the attribution guidance to the library-correct pattern: the queryID is on each hit (item.__queryID) in the itemComponent — clicks via the built-in sendEvent, add-to-cart conversions via a recorded objectID-> queryID map. Point to examples/coding-with-ai-nextjs. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
leonardocuco
marked this pull request as ready for review
July 28, 2026 13:13
Resolve marketplace.json conflict: both sides appended a plugin entry. Keep the new `agent-studio` entry and main's `algolia-implementation` suite, with the suite last so its "the official skills above" wording still holds — matching the README ordering. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
leonardocuco
changed the title
There was a problem hiding this comment.
Pull request overview
Promotes a new public agent-studio skill (previously local-only) that documents how to embed Algolia Agent Studio chat via the react-instantsearch Chat widget, including auth, memory, client-side tools, context injection, Insights events, and UI customization. Adds a Next.js App Router reference app to demonstrate the recommended integration patterns end-to-end.
Changes:
- Added the new
skills/agent-studioskill with a main guide, detailed reference docs, and evals. - Added
examples/coding-with-ai-nextjsas a “correct-by-construction” Next.js App Router reference implementation. - Updated marketplace/README registration plus small docs tweaks in existing skills (
algolia-mcp,algobot-cli).
Reviewed changes
Copilot reviewed 35 out of 37 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| skills/algolia-mcp/SKILL.md | Clarifies required dashboard toggle before MCP connection setup. |
| skills/algobot-cli/SKILL.md | Expands non-interactive profile setup guidance; updates example model default. |
| skills/algobot-cli/references/config-as-code.md | Updates example model; documents static vs dynamic indices for search tool config. |
| skills/algobot-cli/references/commands.md | Documents additional required flags for profiles add. |
| skills/agent-studio/SKILL.md | Adds the new top-level Agent Studio integration guide and references. |
| skills/agent-studio/references/prompt-starters.md | Provides a full prompt-starters component example + streamed-response parsing. |
| skills/agent-studio/references/memory.md | Documents memory enablement and a “memory channel” request pattern. |
| skills/agent-studio/references/insights-events.md | Documents Insights event payloads and attribution approach for chat. |
| skills/agent-studio/references/css-overrides-example.md | Provides a full CSS override example for rebranding the chat widget. |
| skills/agent-studio/references/context-injection.md | Implements context injection + DOM stripping patterns and provider wiring. |
| skills/agent-studio/references/components-and-css.md | Documents Chat component customization points and CSS tokens/classes. |
| skills/agent-studio/references/client-side-tools.md | Documents layoutComponent tool pattern and tool schema examples. |
| skills/agent-studio/references/authentication.md | Documents server-minted JWT secure user token + client caching. |
| skills/agent-studio/references/agent-prompt-example.md | Provides a reusable Agent Studio system prompt template. |
| skills/agent-studio/evals/evals.json | Adds eval prompts/expectations for the new skill. |
| README.md | Registers agent-studio in the skills table. |
| examples/coding-with-ai-nextjs/tsconfig.json | Adds TS config for the new Next.js reference app. |
| examples/coding-with-ai-nextjs/README.md | Documents setup, env vars, dashboard config, and file tour for the example app. |
| examples/coding-with-ai-nextjs/package.json | Adds dependencies/scripts for the Next.js reference app. |
| examples/coding-with-ai-nextjs/package-lock.json | Locks dependencies for the Next.js reference app. |
| examples/coding-with-ai-nextjs/next.config.mjs | Adds minimal Next.js config. |
| examples/coding-with-ai-nextjs/next-env.d.ts | Adds Next.js TS type references. |
| examples/coding-with-ai-nextjs/app/providers.tsx | Adds InstantSearchNext provider wiring for App Router. |
| examples/coding-with-ai-nextjs/app/page.tsx | Composes the search UI and floating chat widget. |
| examples/coding-with-ai-nextjs/app/lib/insights.ts | Implements Insights attribution (queryID from hit) and conversion tracking. |
| examples/coding-with-ai-nextjs/app/lib/cart.ts | Adds a minimal in-memory cart for the add-to-cart tool demo. |
| examples/coding-with-ai-nextjs/app/lib/algolia.ts | Centralizes Algolia config and shared lite search client + hit type. |
| examples/coding-with-ai-nextjs/app/lib/algolia-token.ts | Fetches/caches the secure user token from the app route. |
| examples/coding-with-ai-nextjs/app/layout.tsx | Adds App Router root layout + global CSS import. |
| examples/coding-with-ai-nextjs/app/globals.css | Adds InstantSearch + chat base CSS and minimal page styling. |
| examples/coding-with-ai-nextjs/app/components/Search.tsx | Adds a basic SearchBox + Hits grid. |
| examples/coding-with-ai-nextjs/app/components/ChatWidget.tsx | Adds Chat transport, tool registration, and itemComponent attribution wiring. |
| examples/coding-with-ai-nextjs/app/components/AddToCartTool.tsx | Implements add_to_cart client-side tool handler using layoutComponent. |
| examples/coding-with-ai-nextjs/app/api/auth/algolia-token/route.ts | Implements server-side JWT minting endpoint for secure user token. |
| examples/coding-with-ai-nextjs/.gitignore | Adds ignores for Next build output and env files. |
| examples/coding-with-ai-nextjs/.env.example | Documents required NEXT_PUBLIC and server-only env vars. |
| .claude-plugin/marketplace.json | Registers the new agent-studio skill in the marketplace manifest. |
Files not reviewed (1)
- examples/coding-with-ai-nextjs/package-lock.json: Generated file
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+294
to
+297
| Track user behavior to power Algolia analytics and AI Personalization. Send | ||
| events with the lite client's `pushEvents` method. | ||
|
|
||
| - Setup: `algoliasearch(appId, apiKey)` from `algoliasearch/lite`. |
Comment on lines
+46
to
+54
| "expected_output": "Read the queryID from the streamed search tool result (iterate the tool result parts, keying off parts that carry both queryID and hits rather than a hardcoded tool name) and include it in click-after-search and conversion-after-search Insights events.", | ||
| "files": [], | ||
| "expectations": [ | ||
| "Explains that the chat agent searches server-side and the queryID is returned in the streamed search tool result (iterate the tool result parts, keying off queryID + hits rather than a hardcoded tool name), not from a client-side search", | ||
| "Builds a mapping from objectID to { queryID, position } from the streamed search tool results", | ||
| "Sends click events with the queryID and 1-based positions (click-after-search) for products the agent surfaced", | ||
| "Sends addToCart or purchase conversion events with the same queryID (conversion-after-search) rather than plain conversions", | ||
| "Notes that without the queryID the events are not attributed to the agent's searches, losing click-through, conversion, and revenue analytics" | ||
| ] |
Comment on lines
+38
to
+52
| const input = message.input as { productId?: string; quantity?: number | null } | undefined; | ||
| const productId = input?.productId; | ||
| const quantity = input?.quantity ?? 1; | ||
|
|
||
| if (!productId) { | ||
| // Always call addToolResult, even on failure, so the agent can continue. | ||
| addToolResult({ output: { error: "Missing productId" } }); | ||
| return; | ||
| } | ||
|
|
||
| const line = addToCart(productId, quantity); | ||
| // Conversion-after-search: attributed to the agent's search when we have a | ||
| // queryID for this product (see lib/insights.ts). | ||
| trackChatAddToCart(productId, quantity); | ||
|
|
Comment on lines
+44
to
+46
| "id": 4, | ||
| "prompt": "Make sure clicks and add-to-cart from my Agent Studio chat are attributed to the agent's searches in Algolia analytics.", | ||
| "expected_output": "Read the queryID from the streamed search tool result (iterate the tool result parts, keying off parts that carry both queryID and hits rather than a hardcoded tool name) and include it in click-after-search and conversion-after-search Insights events.", |
Comment on lines
+3
to
+11
| Track user behavior to power Algolia analytics and AI Personalization. Events | ||
| are sent with the lite client's `pushEvents` method. | ||
|
|
||
| ## Setup | ||
|
|
||
| ```typescript | ||
| import { liteClient as algoliasearch } from "algoliasearch/lite"; | ||
| const client = algoliasearch(appId, apiKey); | ||
| ``` |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Lab Week draft — promote the
agent-studiofrontend chat skillStatus: draft / WIP. Opening for early feedback during Lab Week.
Adds a new
agent-studioskill so customers can build an Agent Studio chat experience on their own website from their AI coding assistant. It was previously a local-only skill; this promotes it into the public repo alongside the other six skills.What's included
skills/agent-studio/SKILL.md— lean guide (355 lines) covering widget setup and custom transport, client-side tools (thelayoutComponentpattern), Algolia Insights (business) events, secure user authentication, memory, context injection, prompt starters, and CSS.skills/agent-studio/references/*— detailed code kept out ofSKILL.mdto stay under the 500-line spec limit:client-side-tools.md,insights-events.md,authentication.md,components-and-css.md,memory.md,context-injection.md,prompt-starters.md,agent-prompt-example.md,css-overrides-example.md.skills/agent-studio/evals/evals.json— 3 evals..claude-plugin/marketplace.jsonand the README skills table.Verified
python3 scripts/validate_skills.py→ 52 passed, 0 failed.Verification checklist (before marking ready)
/plugin install agent-studiomarketplace flow.react-instantsearchChat API.Paired with the docs section in
algolia/docs-new(branchlabweek/coding-with-ai).🤖 Generated with Claude Code