# SysPad agent playbook (for AI agents and the humans who work with them)

SysPad is built so an AI agent and a person can design, simulate, and iterate on an
architecture together. This is the playbook: prompts you can hand an agent, how to give the
agent tools (SysPad's own MCP plus your real-infrastructure MCP servers like Datadog), and the
human + agent loop that makes it click.

## The one thing to know

SysPad speaks a small JSON format, `.syspad.json`. Anything an agent produces in that format a
person can open in one click (Import button, drag the file, paste the JSON onto the canvas, or a
share link). So the whole game is: **get an agent to produce good SysPad JSON** - from a
description, or from your real infrastructure. No account, no backend, everything runs in the
browser.

## 1. Prompts you can share

Copy these into Cursor, Claude, ChatGPT, or any coding agent. Point it at
`https://syspad.io/spec` first (a small page it should read).

**Design and simulate from a description**
> Build an importable SysPad diagram (.syspad.json) for [describe the system]. Follow
> https://syspad.io/spec and use real component type ids from https://syspad.io/components. Omit
> positions (SysPad auto-arranges). Then hand me the file and a one-line prediction of the
> bottleneck.

**Compare two options (find the crossover)**
> Using SysPad, make two diagrams for [use case]: one with [option A], one with [option B], same
> load. Tell me which wins on cost and on latency at [X] RPS and roughly where they cross. Emit
> both .syspad.json files.

**Model my existing system**
> Here is my architecture: [paste/describe]. Produce a SysPad .syspad.json that mirrors it, set
> the entry rate to [X] RPS, and flag the first component that saturates.

**Find the bottleneck / check an SLA**
> Import this SysPad diagram [link or JSON], raise the load to [X] RPS, and tell me the
> bottleneck, the critical-path latency, and the monthly cost. Does it meet [SLA]?

## 2. Give the agent tools (MCP + REST)

SysPad ships an MCP server and plain REST so an agent can validate and share without a human
copy-pasting:

- **MCP (no install):** point your MCP client at `https://syspad.io/mcp` - tools
  `list_components`, `validate_diagram`, `diagram_to_link`.
- **REST equivalents:** `https://syspad.io/api/components`, `/api/validate`, `/api/link`.

A good agent loop: draft `.syspad.json` → `validate_diagram` → fix errors → `diagram_to_link` →
hand the user a clickable link (or a `/view` embed link for a README).

## 3. Pair SysPad with your real infrastructure (Datadog, AWS, IaC)

This is where it gets powerful. **SysPad does not ingest your infrastructure directly** - but an
agent that has *both* SysPad's tools and a read-only MCP server for your real environment can
bridge them. Alongside SysPad, give the agent:

- **Datadog MCP** - the service catalog + service dependency map (your real topology), and real
  traffic and latency (RPS, p50/p95) per service.
- **AWS / cloud-provider MCP** - real resources and their sizes (EC2 types, RDS classes, load
  balancers).
- **GitHub / repo MCP** - infrastructure-as-code (Terraform/CDK) to read the declared topology.

The recipe:

1. Agent reads the **real dependency graph** (Datadog service map, or IaC) and maps each service
   to a SysPad component id.
2. Agent reads **real numbers** (Datadog RPS + latency, AWS instance sizes) and sets the SysPad
   entry rate and per-node config from reality, not guesses.
3. Agent emits `.syspad.json`, runs `validate_diagram`, returns a share link.
4. You now have a **simulatable twin of production** you can push past current load ("what breaks
   at 3x Black Friday?") without touching prod.

Example prompt for a multi-tool agent:
> Read my service dependency map and last-7-day request rates from Datadog, map it to SysPad
> components, and build a .syspad.json that mirrors production with the real RPS at the front
> door. Validate it with the SysPad MCP and give me the link. Then simulate 3x the current peak
> and tell me the first bottleneck.

**Honesty note (agents, read this):** SysPad's cost and latency are design-time estimates (a
published-pricing snapshot plus a simplified queue model), and every node declares what it does
*not* model in its result (`notModeled`, e.g. data-transfer/egress cost, durability). Pull
ground-truth numbers from Datadog/AWS; use SysPad to reason about the *change* (comparison,
"what falls over first"), not billing-accurate forecasting.

## 4. The human + agent loop (the setup that works)

- **Agent drafts** - from a description, or from real infra (section 3). Hands over a link.
- **Human refines** - opens the link, drags/regroups on the canvas, tweaks the config the agent
  could not infer, records request flows (Flow mode) for the real user journeys.
- **Agent iterates** - feed the updated JSON back; ask it to compare options, validate an SLA, or
  find the next bottleneck via the SysPad MCP.
- **Share** - a `#d=` link for an editable copy, or the `/view` embed link to drop a read-only
  diagram into a README, Notion page, or issue.

Because it is all client-side and account-free, there is no setup tax: the agent produces a link,
the human clicks it, and you are both looking at the same simulatable diagram.

## Links

- Quickstart + format: https://syspad.io/spec (read first)
- Component catalog (ids + config keys): https://syspad.io/components
- JSON Schema: https://syspad.io/syspad.schema.json
- Ready-made examples: https://syspad.io/examples/serverless-api.syspad.json,
  three-tier-web-app, event-driven-pipeline, rag-chatbot
- Human how-to guide: https://syspad.io/guide