Flesh out the ADP admin quickstart#32
Merged
Merged
Conversation
Replace the byoc-quickstart.adoc stub with a single, opinionated, end-to-end path that gets an admin from "fresh ADP environment" to "first working agent call" in about 20 minutes: 1. Get an Anthropic API key (console.anthropic.com signup and billing) 2. Store the key in ADP's secret store 3. Configure the LLM provider in ADP and run Test Connection 4. Create an MCP server backed by the public Swagger PetStore OpenAPI spec 5. Build a pet-store-assistant agent that combines the provider and MCP 6. Test the agent in the Inspector with three example prompts 7. Verify the calls landed in the governance dashboard and Transcripts The quickstart links out to the existing deep dives (configure-provider, gateway-quickstart, openapi MCP, system-prompts, transcripts) for detail so this page stays short and reads sequentially. Also delete the redundant first-agent.adoc stub and its nav entry; the new quickstart covers the "build your first agent" path. Three TODO comments left in the page for engineering to confirm before publishing: current Anthropic model IDs in the catalog, and whether the Create LLM Provider form supports inline secret creation on adp-production (which would let us collapse steps 2 and 3). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
✅ Deploy Preview for redpanda-agentic-data-plane ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
…aude.com
Two follow-up fixes from PR review:
1. Strip every concrete time reference from the quickstart. Time
estimates ("about 20 minutes", "less than a minute", "a few
seconds") date quickly and set up readers for a bad experience
if reality runs faster or slower than the page promises.
2. Update the Anthropic key creation steps to match the current
platform.claude.com UI. The previous page told readers to go to
console.anthropic.com and navigate Settings > Billing and
Settings > API Keys, both of which no longer exist. New flow:
- URL: platform.claude.com (was console.anthropic.com).
- Sidebar: Manage > API keys (was Settings > API Keys).
- Workspace caveat: skip the Claude Code workspace, which has a
separate "install Claude Code" flow that doesn't apply here.
- Create button: + Create key (was Create Key).
- Drop the hardcoded Environment: Production form field, which
may not exist on the new form; leave the docs writer to
verify the live create dialog.
Billing instructions hedged to "Add a payment method if you
haven't already" since the platform.claude.com sidebar shown in
the screenshot doesn't expose a Billing entry. A specific click
path can be added once eng confirms where billing now lives.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Walked through the platform.claude.com Create API key dialog live. It's simpler than the previous wording implied: the dialog has one text field (Name your key), the workspace is preselected (and not editable from the dialog), and the primary button is Add. Replace the multi-bullet step with one sentence that names the dialog and the button so the reader can recognize the surface and finish in a single click. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Walked through the ADP Secrets Store page live. The sidebar entry is Secrets Store (not Secrets) and the primary button is Create Secret (capital S in Secret). Update three spots in the quickstart to match: the section heading, the navigate step, and the cleanup step. Also soften the inline-creation TIP since the original referenced a specific button label that may not exist. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Walked through the form. Three corrections: - Field label is ID (not Name), with the help text constraint spelled out (uppercase letters, numbers, underscores, slashes, hyphens only). - Scopes is a required field. Call out that AI Gateway must be in the selection so the LLM provider in the next step can read the secret. Leave other default scopes alone. - Submit button is Create Secret (matches the trigger button), not the generic Create. Also add an IMPORTANT callout that the secret value is encrypted and unrecoverable after save, mirroring the form's own help text. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Walked through the form. Three corrections plus one resolved TODO:
- Section is API key reference (not API key), with Existing / New
tabs. Inline secret creation IS supported via the New tab, which
closes the standalone secrets-flow TODO.
- Toggle label is Authorization passthrough (not Auth passthrough).
- Base URL prefills with the standard Anthropic endpoint, so the
instruction is now "leave the default in place" rather than
"leave blank."
Also tightened the Models step: the form's own intro language
("Models you select here become the catalog... you can change
later") matches what readers see, so the page now mirrors it
instead of restating in different words.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Walked through the provider detail page on adp-production. The Overview tab has Connection details (Type, Status, Proxy URL, Base URL, API key ref) and a Models list, but no Test Connection widget. The Connect tab's "Verify the connection" copy is geared at running Claude Code or one of the language client snippets; there is no in-UI button that pings the upstream. Update the verification step to match what's actually visible: - Required: confirm the Status badge in the Connection card shows Active. The agent built later in the quickstart is the end-to-end exercise of the provider. - Optional TIP: smoke-test by opening the Connect tab, picking the curl client (>_ icon), copying the snippet, and running it from a terminal. A 200 response confirms the wiring. Also close the model-ID TODO since the Overview screenshot confirms both claude-haiku-4-5 and claude-sonnet-4-6 exist in the live catalog. Left a lighter comment in the frontmatter noting they should be re-verified at PR time. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Walked through the form. Several corrections: - The post-picker page is titled "Configure OpenAPI MCP Server". Name that surface so readers recognize it. - Name field is plain "Name" with the lowercase/hyphens/numbers constraint spelled out in help text (not "Identity" group). - No "Spec source: URL" radio exists. The form has a "Spec" URL field and a "Spec Content" textarea side by side; you fill in one or the other. - Field is "Base URL" (override behavior is in help text, not the label). Renamed accordingly. - Code Mode toggle is new info. Add a one-line note that the quickstart can leave it at its default. - Filter section (Include/Exclude Tags + Include Operations) is for advanced filtering. Tell readers to skip it. - Authentication section wasn't visible in the form crop; hedge the auth instruction with "if the form prompts." Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Two corrections from the bottom of the Configure OpenAPI MCP Server form: - Submit button is labeled Submit (not Create). - Auth dropdown is required (red asterisk). The field is labeled Auth and the public-access option is No Auth (not Authentication / None). Drop the "if the form prompts" hedge. Also enrich the Filter skip to enumerate what the section actually contains (tag, operation, path, HTTP-method filters) so readers understand what they're skipping. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The OpenAPI MCP server lowercases tool names when generating them from the spec's operationId values, so the live tools are findpetsbystatus, getpetbyid, findpetsbytags, addpet — not the camelCase versions the OpenAPI spec uses. Sweep all 12 references across the MCP step, the agent system prompt, the agent tool-list, and the test-prompt expectations. Also rework the optional Inspector sanity check. The Inspector tool cards in adp-production aren't interactive parameter forms; you can't pick a tool and run it from there with a status=available argument. What you CAN do is: - Read the STATUS field (Connected, green dot) at the top of the MCP Inspector card. - Click Ping or Refresh to exercise the server. - Count tools in the Tools card. The new step uses those affordances. The real tool exercise comes in the next section when the agent calls findpetsbystatus from a prompt. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Walked through the form on adp-production. Several corrections: - List-page button is Create AI Agent (not Create Agent). - Field is Agent Name (not Display name). - Field is Resources (not Resource tier). - There is NO AI Gateway dropdown in the form. The LLM Provider Configuration card has Provider and Model only. Drop the gateway-selection step and the cross-link to the AI Gateway quickstart as a hard prereq. - MCP Tools is a server-level checkbox list, not an Add MCP Server button with individual-tool checkboxes. Each row shows "Tools discovered on first use" which means the agent gets every tool the server exposes at runtime; you cannot pre-filter to read tools from the form. Update the step and tighten the system prompt with a "stick to read operations" rule to compensate. - Max Iterations is a slider that defaults to a reasonable value. Tell readers to leave the default; the quickstart prompts don't need many iterations. - Subagents (Optional) and Service Account cards exist further down; tell readers to leave them at defaults. Also fold the service-account explanation into the create step so the section ends cleanly with a single status-check sentence rather than a trailing standalone tip. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The agent detail page has its own Transcripts tab alongside Configuration, Integrations, A2A, and Inspector. A reader who just finished testing the agent in the Inspector tab can switch to Transcripts on the same page rather than navigating to the sidebar's cross-agent Transcripts view. Mention both paths so the reader picks the one closest to where they already are. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Walked through running prompts in the agent's Inspector tab. Three updates: 1. The Inspector is a chat UI, not a function-call form. Lead the Test section with a one-paragraph description of what readers will see (Task/TaskStatusUpdate/tool-call cards and the final Artifact response) so the first interaction isn't a surprise. Send is a paper-plane icon at the bottom-right of the input; no Enter shortcut. 2. Add a NOTE in the MCP step that PetStore is a public demo Swagger hosts and is occasionally unavailable. If the agent later returns an HTTP 500 from PetStore, that's the upstream, not ADP. 3. Add a follow-up troubleshooting paragraph after the test prompts pointing at the same 500 scenario. The system prompt's "if a tool fails, say so and stop" rule produces a clean apology message; readers should know this is the agent behaving correctly, not a configuration bug. The retry advice is one line and out of the reader's way. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
User observed that "What pets are available right now?" (findpetsbystatus on status=available) failed twice in a row against the public PetStore demo, while "Tell me about pet ID 1" (getpetbyid) worked on the first try. PetStore's findpetsbystatus endpoint has a known flakiness pattern; getpetbyid is reliable. A quickstart whose first prompt fails twice is a bad first impression even if the rest works. Swap the order so getpetbyid runs as the first smoke test, then findpetsbystatus as the second test. The reader sees a clean success before encountering any upstream-side flakiness. Annotate each prompt with a one-clause note on PetStore endpoint reliability so the reader knows what to expect. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The Governance dashboard, KPI cards, and Track-spend next-step reference UI that's not yet in adp-production (no Governance entry in the sidebar). Wrap the affected content in ifdef::env-adp-governance[] blocks so it's preserved in source but doesn't render until the flag is defined. Replace the now-empty Verify step with "Verify the agent in Transcripts" using what's actually available today: the per-agent Transcripts tab and the cross-agent Transcripts view in the sidebar. Both surfaces are real and link to observability:transcripts.adoc. Three blocks conditionalized: - Verify spend in the governance dashboard section (was: Verify in the governance dashboard). - Track spend across teams bullet in Next steps. - "see the calls in the governance dashboard" phrasing in the What you'll build paragraph. When the governance UI ships, set env-adp-governance: true in antora.yml under asciidoc.attributes (or define it as a page attribute) to surface everything again. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Walked through Transcripts in adp-production and the page hangs when trying to find a specific run. Until the Transcripts UI is stable, wrap the "Verify the agent in Transcripts" section in ifdef::env-adp-transcripts[] so it doesn't render. Both admin verify sections are now gated by their own attribute, so they can be flipped on independently when each surface ships: - env-adp-transcripts: true for the Transcripts verify section - env-adp-governance: true for the Governance dashboard verify section The intro "After the agent works, you can walk through one execution turn-by-turn in the Transcripts view." stays in place per direction; only the section itself is gated. With both flags off, the visible flow is Test → Clean up. The Inspector test step is itself the verification: the reader saw the agent respond with tool calls and an Artifact. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The Clean up section at the end of the page already covers deletion in concrete steps; the standalone "All three resources are deletable at the end of the quickstart" sentence in the intro adds noise without information. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The TIP pointed at a curl client in the LLM provider's Connect tab Code Examples grid, but that affordance is patchy across surfaces (the MCP server's Connection tab has python/node/java/go but no CLI/curl option) and may not survive UI changes. The Status: Active check on the Connection card already gives pre-agent verification, and the agent test in step 6 is the real end-to-end smoke test: a single prompt exercises the provider, the MCP server, and the agent. Removing the TIP keeps the quickstart on the shortest reliable path and avoids one more surface to keep in sync with UI changes. Also drop the "or the smoke-test request returns an authentication error" clause from the troubleshooting paragraph since the smoke-test step is gone. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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
1 participant
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.
Summary
Replaces the
byoc-quickstart.adocstub with a single, opinionated, end-to-end path that gets an admin from "fresh ADP environment" to "first working agent call" in about 20 minutes.The new page walks through seven sequential steps:
pet-store-assistantagent that combines the provider and MCPPlus Clean up (delete in reverse order, revoke the upstream Anthropic key) and three focused Next steps (add more providers, swap PetStore for a real upstream, track spend).
Also deletes the redundant
first-agent.adocstub (4-lineTODO: Add content) and its nav entry. The new quickstart covers that path.Design choices
https://petstore3.swagger.io/api/v3/openapi.json) because the OpenAPI managed MCP server takes a spec URL, the spec is public/unauthenticated, and the resulting tools are easy to reason about.configure-provider.adoc,gateway-quickstart.adoc,openapi.adoc,system-prompts.adoc,transcripts.adoc) so this page stays short and the existing references remain the source of truth.Standards compliance
quickstart. Tutorial-template structure.platform_engineer(per the new persona vocabulary merged in Convert :personas: metadata to product-design-approved ADP vocabulary #31).etc./via/ passiveis provided.glossterm:macros added on first body mention oftranscript,MCP server,MCP tool,AI agent,governance dashboard.Open questions for engineering
Three
// TODOcomments left in the page for the docs writer to resolve before publishing:claude-haiku-4-5andclaude-sonnet-4-6perconfigure-provider.adoc:95-109; model identifiers shift quarterly.adp-productiontoday. If yes, the standalone "Store the key in ADP's secret store" step can collapse into the provider step.petstore3.swagger.iofrom ADP's egress.Preview pages
Test plan
npm run buildsucceeds with only pre-existing warnings (CSV data, attribute-validation, unlisted-pages); no new warnings from this changefirst-agentreferences remain in the repo after deletiondocs-team-standards:reviewskill returned a clean review with two soft style suggestions (resolved) and the three engineering follow-ups noted aboveadp-productionand time it; aim for ~20 minutes; flag any UI labels that have drifted🤖 Generated with Claude Code