Get AI coding agents to nail Pega DX API integrations the first time

AI
1

A reusable Skill that turns “confidently wrong” fetch calls into verified patterns.

A while back I shared a conversation here and a Markdown file, PEGA_DX_API_PATTERNS.md, for anyone building custom front-ends, widgets, and integrations against Pega over the DX (Constellation) API with an AI coding assistant. The problem it solved: the official docs get you to “hello world,” but the moment you do something real — ETags, multi-step case flows, embedded pages, file uploads, stage jumps — you hit undocumented tribal knowledge. And your AI agent doesn’t have that knowledge either, so it writes code that works 80% of the time and fails the other 20%.

That file has since grown up. It’s now a proper Agent Skill — and it’s better in every
dimension that matters when you’re coding into Pega with an agent.

What’s new since the .md

  • It’s an Agent Skill, not a wall of text. Same knowledge, repackaged as a folder with
    a small entry point (SKILL.md) and the patterns split into topic chapters. Your agent
    reads the index, then loads only the chapter relevant to the task at hand — so it
    spends its context budget on the pattern you actually need, not on 90 KB of everything.
  • From ~18 to 39 patterns. New coverage the original never had: A2A message/send,
    Rule-AI-Agent behavior, MCP fallbacks, covered (child) cases, picklist storage quirks,
    data-record create/update/delete, and Constellation conversation-stream handling.
  • Honest trust markers. Every pattern is tagged [Verified] (tested end-to-end on a
    live instance), [Unverified] (plausible, not yet validated), or [Verified-failure]
    (a confirmed dead end — documented so you don’t waste time retrying it).
  • Portable, open format. Agent Skills is an open standard (agentskills.io) that
    Copilot, Cursor, Claude, Gemini CLI and others can auto-discover. Deploying is dropping
    in one folder.

What it covers

Six chapters, 39 patterns:

  • Auth & base URL — the app-specific path that avoids the 403 trap; OAuth
    client-credentials + password grants.
  • Case & assignment lifecycle — the two case IDs, ETag locking, assignment vs.
    case actions, advancing vs. saving, stage jumps, covered cases.
  • Data views, records & attachments — listing via data views, the two upload patterns,
    record CRUD, picklists.
  • Embedded page-lists — reading, seeding, appending.
  • BFF, errors & plumbing — Pega’s error shapes, content-type rules, a fetchDx
    wrapper, server-side proxy patterns.
  • A2A, AI agents & MCP — agent-to-agent messaging, Rule-AI-Agent, MCP fallbacks,
    conversation streams.

How to use it with your agent

  1. Deploy the folder into your project — as a git submodule (recommended, so
    improvements flow back to one source of truth), a subtree, or a symlink to a shared
    clone.
  2. Point your agent at it from your top-level instruction file (AGENTS.md,
    CLAUDE.md, or .github/copilot-instructions.md): “Before writing any Pega DX API
    calls, load pega-dx-api-patterns/SKILL.md and open the relevant chapter.”
  3. Let it self-improve. The Skill’s maintenance protocol asks the agent to add new
    patterns it discovers and correct wrong ones (only after proving a better approach) — so
    every project makes the next one smarter.

If you’re curious why a Skill beats a plain .md for this kind of knowledge — and when a
plain .md is still the right call — I wrote that up separately:
[Where should your agent’s hard-won knowledge live?][LINK-TO-POST-B]

The same caveats still apply

This isn’t a Pega-supported document. It’s built from real project experience, it’s a work
in progress, and it was developed in a specific agent + MCP + Pega setup. Behavior varies
by Pega version and configuration. [Verified] patterns have been tested; treat the rest
like a colleague’s notes — useful, but verify what matters.

Get it / contribute

Repo: https://github.com/j0glesby73/pega-dx-api-patterns

If you’re doing DX API work and have patterns worth adding — broken auth flows, Cosmos
React nuances, Pega version differences — I’d genuinely welcome contributions. The goal is
a community-maintained resource, not a personal cheat sheet.

Would love to hear what patterns you’d add.

1 Like