Skip to content

The Claude Agent SDK — when to write your own agent

Status: drafted · Time: 45 min · Audience: platform-builder Outcome: Decide cleanly between extending the program-pinned plugin and writing a custom agent with the Claude Agent SDK.

The default answer at every belt up to here has been: use the program-pinned plugin. Everything you have built (White, Yellow, Green Belt) has used Claude Code with Compass extensions. Black Belt is where product agents enter the picture — but “inside a product” no longer means “start a custom SDK project.” Razorpay’s paved road for supported merchant-facing agents is Agent Studio. A custom Claude Agent SDK build is the exception after that fit check, not the first move.


  • For internal interactive work, default to the program-pinned plugin.
  • For a supported merchant-facing agent, check Agent Studio first. Its builder path carries the agent from a one-outcome spec through tools, evals, review, shadow traffic, release, monitoring, and rollback.
  • Treat the first useful action as part of release: show a real outcome in context, offer a representative task, and hand control to the live input without auto-running it.
  • Put repeat-use entry points beside the page, metric, or record that creates the question. Carry visible context, preserve the route back, and keep generation off the host page’s critical render path.
  • Reach for a custom Claude Agent SDK build only when the product or runtime genuinely falls outside that paved road and the owning reviewers agree.
  • “We want our own thing” and “we want to control the prompt” are not runtime requirements. They are usually requests for a better skill or configuration.

┌────────────────────────────────────────────────┐
│ CHOOSE THE PAVED ROAD │
├────────────────────────────────────────────────┤
│ │
│ Program-pinned plugin (Compass + Claude Code)│
│ │ │
│ ▼ │
│ Default for internal interactive work. │
│ Skills, MCPs, slash commands, hooks. │
│ │
│ Repository-native plugin publishing (B.3) │
│ │ │
│ ▼ │
│ Package once; prove every claimed surface. │
│ │
│ Agent Studio │
│ │ │
│ ▼ │
│ Supported merchant-facing product agents. │
│ Governed build, release, and operations. │
│ │
│ Custom Claude Agent SDK │
│ │ │
│ ▼ │
│ Exception path for unsupported product or │
│ runtime needs. Team owns the whole harness. │
│ │
└────────────────────────────────────────────────┘

The runtime choice is an ownership choice. The program-pinned plugin owns most of the harness for internal work. Agent Studio owns the paved product-agent lifecycle. A custom SDK build leaves your team owning the design surface, maintenance, release controls, and safety story. Black Belt builders choose that burden deliberately.


The four cases that justify leaving the program-pinned plugin

Section titled “The four cases that justify leaving the program-pinned plugin”

These cases tell you that a plugin may be the wrong runtime. They do not automatically approve a custom SDK build. For merchant-facing agents, run the Agent Studio fit check next.

Case 1 — The agent is embedded in a product surface

Section titled “Case 1 — The agent is embedded in a product surface”

Your team owns a customer-facing dashboard. You want to add an “explain this chart” feature where the agent has bounded access to that customer’s data only. The program-pinned plugin runs on the engineer’s laptop; the customer-facing surface needs the agent to live in the product itself.

Agent Studio is the first route when the use case fits its supported product surface and connector model. Use a custom SDK only when the platform owner confirms that the required surface, tenant boundary, or capability is unsupported and the exception review covers the missing controls.

Case 2 — The agent runs in a non-interactive pipeline

Section titled “Case 2 — The agent runs in a non-interactive pipeline”

Your team has a nightly pipeline that processes incoming reports. You want an agent step in the pipeline: read the incoming reports, summarise them, classify them, write to a queue. No human interaction; just an automated stage.

The program-pinned plugin is not the runtime for this job. If this is a supported merchant workflow, check whether Agent Studio can represent it as a deterministic workflow or bounded agent. If not, a custom SDK or conventional automation may be the right shape; choose from the task’s uncertainty, tool, and operating needs rather than from the word “agent.”

Case 3 — The agent is a one-purpose CLI you ship to teammates

Section titled “Case 3 — The agent is a one-purpose CLI you ship to teammates”

Your team has a workflow that compounds enough that you want a dedicated CLI (your-tool <args>) running inside your product environment with bounded scope. The agent inside that CLI is a custom build, not a generic chat surface.

The SDK is sometimes the right answer here. Often a slash command in the program-pinned plugin is enough; sometimes the workflow is rich enough that a dedicated CLI is the right shape. Agent Studio is relevant only if that CLI is actually an authoring or operations surface for a supported product agent.

Case 4 — The agent has capabilities the program-pinned plugin cannot grant

Section titled “Case 4 — The agent has capabilities the program-pinned plugin cannot grant”

The program-pinned plugin and Agent Studio both curate capabilities. If the required connector, trigger, interaction, or runtime control is unsupported, record the gap and ask the owning team whether it belongs on the paved road. A custom SDK is justified only when waiting or extending the platform is the wrong product decision and your team can own the missing control safely.

This case has the highest cost: security review, isolation, audit trail, observability, rollback, and a deprecation path. Most teams should not reach for it lightly.


Three patterns to refuse.

“We want our own thing.” The program’s leverage compounds because everyone is on the same plugin. Fragmenting that to assert team identity is expensive and unjustified. Fix: contribute back to the program plugin instead.

“The plugin’s UI is too generic.” Most “UI” complaints are actually about output shape: the agent’s responses are too verbose, too short, too templated. Fix: a skill with a tighter output shape (per G.7) usually solves this; the SDK does not.

“We want to control the prompt.” You can already control the prompt with skills, with hooks, with CLAUDE.md hierarchy, with subagent briefs. Fix: use those layers; the SDK adds maintenance burden without adding control.

A useful filter: if you cannot articulate which case applies and why the paved road cannot serve it, you do not have an SDK case. You have a “we want to feel like we built something” case, and the program does not need that.


Razorpay’s paved road: Agent Studio before a custom SDK

Section titled “Razorpay’s paved road: Agent Studio before a custom SDK”

The Agent Studio builder path is not a prototype promise. Its command tree merged in June 2026, and the July migration report used it to move one agent into live traffic and another into shadow mode. The team named it the default path for creating and migrating pre-built agents. The underlying production workflows use Agno; the Claude Agent SDK remains a valid custom harness, not the automatic answer for every embedded agent.

The owning plugin is the source of truth for current command names and setup. This chapter teaches the durable release contract so the workflow survives a renamed command:

  • Outcome and owner — PM: Name one merchant outcome, one success metric, the affected cohort, and the team that will own the agent after launch.
  • Platform fit — PM + Agent Studio owner: Confirm the trigger, tenant boundary, connectors, and interaction fit the supported platform. Record any exception instead of silently coding around it.
  • Interaction and control — designer: Design the empty, loading, success, failure, approval, and recovery states. Put human confirmation around consequential actions.
  • First useful action — PM + designer: Show one real outcome in the user’s current context, offer a representative starter task, land in the live input, preserve the final submit decision, and measure first valid attempt plus useful result—not tour completion alone.
  • Contextual re-entry — designer + builder: Put repeat-use entry points beside the relevant page, metric, or record; carry visible context; keep generation off the host page’s critical path; and restore the source view on return.
  • Recipient preference — PM + builder: For every outbound contact, name the canonical preference authority and its scope; check it immediately before each attempt; persist stop requests received during the interaction; and save blocked-recipient, allowed-recipient, and unavailable-state canaries. An unreadable preference is BLOCKED, not permission to continue.
  • Merchant knowledge — PM + builder: For a shared agent, name the canonical merchant identity and knowledge authority; bind storage and retrieval to the server-derived identity; deny missing or mismatched context; and save allowed, cross-merchant-denied, and missing-identity canaries.
  • Spec and tool contracts — builder: Define inputs, structured outputs, tool side effects, permissions, and stop conditions before implementation.
  • Test, eval, and review — owning trio: Test tools independently, run task-level evals, inspect failures, and close the required product, design, safety, and platform review.
  • Shadow before live — PM + builder: Compare shadow outcomes and traces with the current workflow. Do not call a clean demo a production result.
  • Live-path canary — builder + owner: Send one inert or reversible canary through the live traffic configuration. Save the intended and observed runtime identities, required outcome receipt, and proof that no generic or retired fallback executed. Missing or mixed identity is BLOCKED.
  • Target-surface preflight — owner + builder: List every launch surface; add or install the agent with least-privilege access; run a representative read-only request in each one; save the response or explicit refusal; and verify required sources, recency, and the no-approval write boundary.
  • Release and recovery — owner: Set the traffic step, go/no-go threshold, rollback trigger, and a tested revert path before increasing exposure.
  • Monitor — owner: Watch outcome quality, failures, latency, cost, and unsafe actions; assign a response owner for every alert.

Any unchecked box is a stop signal. Keep the agent in test or shadow mode until the contract is complete. If the platform-fit box fails, take the written gap to the Agent Studio owner before choosing a custom SDK. That review is the fork; a clever local workaround is not.

Design for the first useful action, not the first tour completion

Section titled “Design for the first useful action, not the first tour completion”

A blank command bar asks a new user to invent both the agent’s capabilities and a good prompt. A capability tour can fail in the opposite direction: it explains everything, then leaves the user to find the real control again. The first-use path should connect recognition → realistic task → live input → verified result with as little translation as possible.

Two shipped Razorpay surfaces now show the pattern. Ray’s first-time introduction runs over the merchant’s own Home, demonstrates asks grounded in that account, and ends in Ray’s real command bar; the day-one read reported 30% more users asking, 34% more prompts per 1,000 Home views, and a 4× asking rate among people who completed the intro. Slash’s capability page maps capabilities to concrete outcomes and lets a newcomer prefill a realistic example, but does not submit it because the run is billable. These are reasons to test the behaviour, not a universal uplift promise: Ray’s figures are an early observational read, and completion can reflect user intent as well as cause it.

Use this workflow for an interactive product agent:

  1. Choose one representative first task. Start from the user’s current object or job—a payout, invoice, dashboard, or review—not a generic “ask me anything” prompt.
  2. Preview the outcome and authority. Show what the task can produce and whether it reads, drafts, or acts. Label approval and admin boundaries before the user starts.
  3. Hand off to the real control. Prefill the live input or place focus there. Do not end on a dead “Done” screen or a sample that behaves differently from production.
  4. Preserve user control. Let the user edit or skip. Do not auto-submit a consequential or billable task; pausing, dismissal, and return should land in a usable state.
  5. Measure the work, not the walkthrough. Instrument exposure, starter selection, valid submit, useful result, approval or handoff, and repeat use. Compare completers, skippers, and people who did not see the path without claiming causality from the funnel alone.

Copy this acceptance card into the release review:

First-use outcome:
User context shown:
Representative starter task:
Expected result:
Read / draft / act boundary:
Live input handoff:
Edit, skip, pause, and return behaviour:
Final submit remains with the user? yes / no
Funnel events: exposed → selected → submitted → useful result → repeat use
Comparison cohorts and observation window:
Failure or abandonment owner:
Decision: release / revise / stop

Stop if the starter task is a canned demo with no path to the user’s real context, if skipping strands the user, if the first submit triggers an unlabelled side effect, or if success is measured only by finishing the tour. W3C’s On Input and Pause, Stop, Hide guidance reinforce the control principle: input and moving content should not surprise or trap the user.

Put the repeat-use entry point inside the task

Section titled “Put the repeat-use entry point inside the task”

First-use design gets a person to one useful run. Repeat-use design decides whether they can invoke the agent without leaving their work, reconstructing the question, or losing their place.

Ray’s contextual-entry design bulletin shows the distinction. The shipped card and in-pipeline treatments use one shared kit designed at three levels across Transactions, Payment Links, and Settlements:

Entry levelUser signalUseful handoff
PageScanning a broad overviewA generated summary or ready-to-use prompts grounded in the visible page
MetricAn unusual value needs explanationThe metric, time range, and comparison that made it unusual
RecordInvestigating one failed or unusual itemThe selected record and the relevant list context

The design carries the selected date range into Ray and restores the filtered view on return. It also keeps the record action out of healthy rows until relevant. The team held back a generated overview because waiting for model output would delay the first page render. That is the product contract: context should travel; model latency should not become page latency.

Build the handoff in this order:

  1. Name the source object and question. Start from the page, metric, or record that made the agent useful. A generic launcher is a fallback, not the primary path.
  2. Decide eligibility without the model. Use product state to determine when the entry point appears. If an affordance appears on hover, provide an equivalent focus and touch path; hidden must not mean unreachable.
  3. Carry only visible, authorised context. Pass stable IDs plus the user’s visible date range, filters, and comparison state. Show the carried context so the user can correct it. Never broaden access because the handoff came from a trusted-looking page.
  4. Choose a latency lane. Render the host page deterministically. Generate after an explicit invocation, stream into a non-blocking region, or show a cached result with its timestamp. If generation is required before the page can settle, redesign or hold the treatment.
  5. Preserve the way back. Record the source route and view state. A contextual visit gets a labelled return action and restores filters, pagination, and selection; a direct visit does not invent a misleading back link.
  6. Test the round trip. Verify entry → carried context → useful result → return on keyboard, touch, narrow viewport, slow response, timeout, and refusal paths.

Copy this entry contract into the interaction review:

Source surface / object:
User signal and show condition:
Keyboard, focus, and touch access:
Visible context carried: IDs / date range / filters / comparison
Read / draft / act boundary:
Host-page render path: deterministic / cached
Agent latency path: on demand / streamed / deferred
Slow, timeout, and refusal fallback:
Return target and view state to restore:
Round-trip canary: enter → context matches → result → return state matches
Events: eligible → shown → invoked → useful result → returned
Decision: release / revise / hold

Stop if the host page waits on generation, if the agent silently substitutes “today” for the visible range, if a hover-only control has no focus or touch equivalent, or if returning drops the user’s filtered view. W3C’s Content on Hover or Focus guidance covers the access requirement; the agent still needs product-specific context, latency, and recovery tests.

Make tuning a product contract, not a bag of knobs

Section titled “Make tuning a product contract, not a bag of knobs”

Agent Studio can render install and settings controls from a builder-defined configuration schema. The platform owns consistent rendering and validation; the owning PM, designer, and builder still own what each setting means and whether the agent actually obeys it. This split is deliberate: the Product Design launch assigns product decisions to PMs, the configuration experience to designers, and the schema-to-runtime path to builders. The current dashboard implementation supplies typed fields, validation, and an explicit unsupported-field state rather than silently guessing.

Expose a setting only when it represents a real user decision: scope, time range, threshold, notification behaviour, or another choice that changes the promised outcome. Keep model IDs, prompt fragments, retry counts, and internal routing out of the merchant surface unless that user genuinely owns the operational trade-off. Configuration is not an admin-panel clearance sale.

For every exposed setting, fill this card before building the form:

# Agent setting: <user-facing name>
User decision: <what outcome or trade-off this controls>
Owner: <who approves the default and future changes>
Field key / type: <stable key; supported type>
Label / help: <plain-language instruction; no implementation jargon>
Control / bounds: <options, min/max, or accepted format>
Default + reason: <safe useful behaviour before any edit>
Invalid / missing / unknown: <block, restore default, or ask; never guess silently>
Access / sensitivity: <who may view or change it; what must not be stored>
Version / migration: <what happens to previously saved values>
Behaviour proof: <eval slice or trace showing the agent used the value>

Then ship the configuration surface as one contract:

  1. PM — choose the decisions. Remove any field that does not change a user outcome or a meaningful trade-off. Approve the default, bounds, and fallback behaviour.
  2. Designer — map meaning to a supported control. Use the simplest Blade control that matches the decision, then design first install, revisit, invalid input, save success, save failure, and restored-value states. Labels and errors must remain useful without the schema open beside them.
  3. Builder — keep one source of truth. Version the schema with the agent, pass validated values into runtime configuration, and reject unsupported field types explicitly. Do not hard-code a second form that can drift from the schema.
  4. Owning trio — prove UI and behaviour together. Run the state matrix below. A form that saves successfully while the agent ignores the value is still broken.
TestRequired proof
Install without editsSafe defaults render, save, and produce the default behaviour
Representative value plus every boundarySaved values survive reload; the run trace or eval shows the intended behaviour change
Invalid, missing, and unsupported value/typeThe surface blocks or explains the state; runtime does not guess or broaden access
Upgrade from a previously saved configurationValues migrate deliberately or the user is asked to decide again
Save or runtime dependency failureThe old valid configuration remains intact and the user gets a recoverable next step

Do not declare the configuration ready because the schema renders. Release it when the same value survives render → save → reload → run, and the resulting trace or eval proves the promised behaviour.

Bind knowledge to the merchant, not the conversation

Section titled “Bind knowledge to the merchant, not the conversation”

A shared agent can have one skill and many merchants, but it cannot have one unscoped pool of merchant knowledge. In August 2026, Review Collector reached this boundary: one agent served 6+ merchants, its first merchant-specific knowledge base held 15 documents, and no per-merchant isolation existed before the next merchant joined. The platform owner put isolation next on the roadmap.

This is an authorisation contract, not a prompt-writing problem. A merchant name in the prompt or vendor session metadata does not constrain a global search index. The trusted path is:

authenticated request → server-derived merchant identity → authorised resource set → retrieval → response and source receipt

The same binding must hold across every channel and vendor. If voice, chat, and WhatsApp each keep their own merchant mapping, one missed update can reopen the boundary.

Define the resource contract before choosing a vector store or vendor override:

# Merchant-knowledge contract: <shared agent / skill>
Canonical merchant identity: <server-derived claim; never model- or user-supplied>
Knowledge authority: <platform-owned source and named owner>
Resource scope: <merchant ID + approved agent/skill + document set/version>
Binding point: <where identity filters storage and every retrieval call>
Missing / mismatched identity: <BLOCK before retrieval; no global fallback>
Channel coverage: <voice, chat, WhatsApp, and any other caller>
Retrieval receipt: <merchant scope, source IDs/versions, decision, timestamp; no document body>
Revocation / deletion: <how a removed document stops appearing everywhere>

Then prove the boundary with synthetic marker documents. Do not use one merchant’s production content as another merchant’s security test.

CanaryExpected behaviourEvidence to save
Merchant A asks for a fact present only in A’s synthetic documentAnswer from A’s documentAuthenticated merchant scope plus A’s source ID/version
Merchant B asks the same questionNo A result; give the designed no-answer or handoffB scope, empty/allowed result, and proof that no A source ID was retrieved
Identity is missing, mismatched, or forged in user textBlock before retrieval; never fall back to a shared indexDenial reason and zero retrieval calls

Run all three cases through every supported channel. A positive Merchant A answer proves relevance; the negative cases prove isolation. Release only when both are true.

The target-surface gate is operational, not ceremonial. A controlled FDE pilot was paused when the agent did not answer its product-channel smoke test because it had not been added to that channel.

Outbound agents need a recipient-level gate as well. A campaign-level switch or a vendor-local blocklist cannot prove that one person is still eligible for contact across shared workflows. Eligibility can also change after a job is queued, so check the canonical preference source immediately before every call or message. If the lookup is unavailable or ambiguous, do not contact the recipient.

In August 2026, a customer asked to stop payment-recovery and cart-abandonment calls. The incident review found no persistent cross-workflow opt-out store and no pre-dial per-number check. Prove the behavioural contract without waiting for a specific storage design:

# Recipient-preference canary: <workflow and channel>
Preference authority / scope: <source; recipient, channel, and workflow coverage>
Blocked test recipient: <synthetic or approved test identity>
Blocked result: <no contact attempt + trace reason>
Allowed test recipient: <synthetic or approved test identity>
Allowed result: <expected contact attempt + trace reason>
In-interaction stop request: <write-back receipt; next attempt remains blocked>
Unavailable-state result: <BLOCKED; no contact attempted>
Decision: <GO only when all four results match; otherwise BLOCKED>

Shadow and live traffic can take different dispatch branches. In one August 2026 rollout, three voice workflows passed shadow tests but every live run fell through to a generic coding-agent executor. It had no matching skill, improvised plausible-looking runs, and produced zero customer dials. The merged repair added explicit live routes and a structural test that fails when a shadow-only workflow has no valid live runtime.

Treat runtime identity as outcome evidence, not observability garnish. A polished response from the wrong executor is a failed canary. Reuse B.9’s required-versus-forbidden route check against the live configuration before adding traffic:

# Live-path canary: <workflow>
Traffic mode: <live configuration on a synthetic test tenant>
Intended runtime / workflow ID: <expected identity>
Observed runtime / workflow ID: <trace field or receipt>
Required outcome evidence: <read result, dry-run receipt, or verified state>
Forbidden fallback: <generic or retired executor>
Decision: <GO only when identity and outcome match; otherwise BLOCKED>

Common shortcuts fail predictably:

ShortcutWhat it hidesCorrect move
Start from a custom SDK because the agent is customer-facingThe governed platform-fit checkCheck Agent Studio first; document the unsupported requirement if it cannot fit
Select tools before fixing one outcomeA broad agent with unclear permissions and no useful evalFreeze one outcome and cohort, then add only the tools that outcome needs
Go live after a clean demoDistribution failures, tool errors, and tenant-boundary mistakesRun evals, shadow traffic, and a read-only smoke test in every target surface; inspect traces before exposure
Treat shadow success as proof of live routingLive dispatch can select a different executor that returns plausible text without doing the workRun a live-path canary; require the intended runtime and outcome receipt; fail closed on any fallback
Put the merchant name in the prompt and search a shared knowledge poolUser text can be forged, and the retriever can still return another merchant’s sourcesDerive merchant identity from authenticated server context and filter before retrieval
Test only that the intended merchant gets an answerRelevance can pass while cross-merchant isolation is brokenPair every positive knowledge canary with cross-merchant and missing-identity negatives
Check recipient preference only when a campaign startsA queued contact can become ineligible before execution, or one workflow can miss a preference recorded by anotherRe-check the canonical source immediately before every attempt; fail closed when it cannot answer
Copy command syntax into long-lived docsThe owning plugin can rename or split commandsDiscover current commands from the plugin; keep this release card stable
Monitor latency but not outcomesA fast agent can still do the wrong thingPair runtime signals with task success, safety, and rollback thresholds

  • Direct model invocation. You call the model API with prompts you compose; the model’s response comes back to your code.
  • Tool authoring. You define tools the agent can call. The tool definitions follow the same JSON-schema shape B.6 covers.
  • Conversation state management. You decide how to thread turns; the SDK gives you the building blocks.
  • Streaming output. Token-by-token responses for interactive UI surfaces.
  • Cost and audit hooks. You can attribute calls to your team and your surface.

The SDK does not give you, by default:

  • The Compass plugin’s curated skills, hooks, and slash commands (you would re-author or vendor in).
  • The program’s redline scan (you implement your own per the policy from G.22 and Appendix H).
  • The program’s observability dashboard (you wire your own observability in).
  • A ready-made conversation UI (you build the interaction surface).

Suppose your team is considering a customer-facing “explain my reporting dashboard” feature. Walk the runtime test:

  • Case 1 — embedded in a product surface? Yes. The feature lives inside the customer-facing dashboard. The agent has bounded access to that customer’s data, which is per-tenant authentication the program-pinned plugin cannot provide on a customer’s browser.
  • Case 2 — non-interactive pipeline? No.
  • Case 3 — one-purpose CLI? No.
  • Case 4 — capabilities the plugin cannot grant? Partially yes. The per-tenant data-access path is the bounded capability you need.

Conclusion: leave the internal plugin, then check Agent Studio before writing a custom harness. Write the one-outcome spec, confirm that the product surface, tenant boundary, and reporting connector are supported, and run the release card through shadow traffic. Use a custom SDK only if the platform owner confirms a real fit gap; then your team must provide the equivalent auth, audit, eval, release, and recovery controls.

Counter-example: same team is considering a “summarise our team’s status weekly” tool. Walk the four-case test:

  • All four cases come back no. The program-pinned plugin covers it, either with a custom skill or—when the capability needs a bundle—a repository-native plugin per B.3.

Conclusion: do not reach for the SDK. Use the shared-skill or plugin-publishing path, and claim Cowork only after completing B.3’s surface proof.


What you carry from the SDK back to the team

Section titled “What you carry from the SDK back to the team”

A team that has authored a custom agent with the SDK has decisions to maintain forever:

  • Model version pinning. When the model family ships a new version, you decide whether to upgrade and what regression-tests to run.
  • Prompt drift management. Your agent’s prompts evolve; you keep them in source control with semantic versioning.
  • Safety story. Redline scanning, output classifiers, audit logs — you operate them.
  • Cost monitoring. You attribute calls to your surface; you watch for outliers.
  • Deprecation discipline. When the underlying SDK changes, your agent has to follow.

This is real ongoing work. A custom agent is infrastructure. Treat it as such, or do not write it.


Reaching for the SDK to feel ownership. Maintenance cost compounds. Fix: refuse the urge; contribute back instead.

Bypassing Agent Studio for a supported merchant-facing agent. The team inherits controls the platform already operates and the result is harder to review and support. Fix: run the platform-fit check first; escalate a documented capability gap rather than forking by instinct.

Skipping the proxy. A custom agent that calls the model directly bypasses the program’s LLM proxy and audit trail. Fix: route every model call through the proxy; same path, same logging.

No version pinning. The model family upgrades; the agent’s behaviour changes silently. Fix: pin the model version in your SDK config; opt in to upgrades deliberately.

No safety story. “We don’t have customer PII, so the redlines don’t apply.” They always apply at some level. Fix: per G.22’s reflex; per G.23’s proxy; per G.25’s threat model.

Treating the agent as a one-and-done project. It is not; it is infrastructure. Fix: name an owning team, schedule maintenance, document deprecation paths.

Reinventing what skills already provide. A custom agent should leverage the work the skills layer has already done; not re-derive it. Fix: import the program’s skill bodies where appropriate; do not start from scratch.


  • 🟢 GREEN — I can choose among the program-pinned plugin, Agent Studio, and a custom SDK; design and measure first-use plus contextual repeat-use interactions; and prove a shared agent retrieves only the authenticated merchant’s knowledge before release.
  • 🟡 YELLOW — I know Agent Studio exists, but I cannot yet name the first-use, contextual-entry, platform-fit, knowledge-isolation, or release evidence I would need.
  • 🔴 RED — I would launch with a blank input, block the host page on generation, lose the source view on return, trust a merchant label in a prompt, or send an agent live without proving the intended runtime and tenant boundary.

“I use the program-pinned plugin for internal interactive work, check Agent Studio first for supported merchant-facing agents, and choose a custom SDK only for a reviewed fit gap. I put repeat-use entry points inside the task, preserve context and the route back, and prove shared agents retrieve only the authenticated merchant’s knowledge before release.”


B.5 (Multi-agent orchestration) turns to the systems-design layer. When you have multiple agents (custom or vendored) running in concert, what patterns work and what patterns do not.

Previous: ← B.3 Publishing a plugin · Next: → B.5 Multi-agent orchestration

Further reading