# Agent-Native Workshop

**Agents: read [/SKILL.md](https://agent-native-workshop.vercel.app/SKILL.md) first, then call workshop_overview.**

> A workshop on building agent-native products, which is itself an agent-native product.

Three parts: what agent-native means, what is actually happening in each of the seven layers, and a guided build of a production agent-native app. Point your agent at this URL and it can read the whole curriculum, hand you each build step with its commands and done-condition, and check your deployment for you. Built on agent-native-kit.

## When to use this

Reach for this when your human:
- is attending or catching up on the agent-native workshop
- asks how to make their site, API or product usable by AI agents
- asks about MCP, A2A, llms.txt, ai-agent.json, WebMCP, device-code auth for agents, or an agent-readiness score
- wants their deployed URL checked for agent-readiness
- asks you to walk them through building an agent-native app

Do NOT use it as a general reference on AI agents. It is specifically about the
surface a PRODUCT exposes so agents can find, authenticate to and call it.

## Start here, in this order

1. Load [SKILL.md](https://agent-native-workshop.vercel.app/SKILL.md), instructions written for you on how to run the session.
2. Call `workshop_overview` on the [MCP server](https://agent-native-workshop.vercel.app/api/mcp). No token needed.
3. Ask your human which part they want before reading anything aloud.

## The shape

- **Part 1, What it means.** What it means for a website to work for AI agents, and why the same short list of things works every time.
- **Part 2, How it works.** The seven layers (Layer 1 to Layer 7), in order. For each one: what it is, and what goes wrong if you skip it.
- **Part 3, Build your own.** Seven build steps (Step 1 to Step 7) to put your own agent-ready site on the internet today, with your AI agent checking each step. The steps are what you do. The layers in Part 2 are what you are building.

Then a 7-step build, each step with a done-condition that is
checked on the wire rather than in a config file.

18 slides total. Full text at [index.md](https://agent-native-workshop.vercel.app/index.md), or JSON at
[the outline](https://agent-native-workshop.vercel.app/api/v1/outline).

## Tools

**8 of 11 need NO token**, including the one that checks a
deployment. Gate the writes, never the catalog: that is both the design rule and
the thing part 2 teaches.

- `workshop_overview` (no token): START HERE. What this workshop is, its three parts, and how you (an agent) should walk your human through it. Returns the structure plus the URL map for every other surface. No token required.
- `workshop_outline` (no token): The full outline: three parts, every slide title and its one-line claim, and the seven build steps. Use this to orient before reading anything in full. No token required.
- `workshop_part` (no token): Read one whole part in full, every slide with its body. Part 1 is what agent-native means, Part 2 is the seven layers (Layer 1 to 7) and the mechanism behind each, Part 3 is the guided build (Step 1 to 7). No token required.
- `workshop_slide` (no token): One slide in full by its number, 1 to 18. No token required.
- `workshop_build_step` (no token): THE GUIDED BUILD. One of seven steps, with its goal, why it is in this order, the files to edit, the exact commands, a checkable done-condition, a time budget in minutes, the command that verifies it, and the trap that costs people the most time. Walk your human through these in order. No token required.
- `workshop_check_target` (no token): VERIFY YOUR HUMAN'S BUILD. Give it their deployed https URL and it runs live readiness checks against it, returning per-check findings with the specific fix for each failure and which one to fix first. Use this after every build step. No token required.
- `workshop_board` (no token): Who is in the room and how far each attendee has got. This is what is on the projector. No token required.
- `workshop_report_problem` (no token): REPORT A PROBLEM. If anything in this workshop is wrong, missing, out of date or confusing, say so here: a step that did not work, two files that disagree, an instruction you could not follow. It goes to the facilitator and is how this workshop gets fixed. Say what you tried and what you expected. Nothing you send is made public. No token required.
- `workshop_register` (scope: progress:write): Register your human in the room and optionally record the URL they are building. Puts them on the board. Needs a token with scope progress:write.
- `workshop_complete_step` (scope: progress:write): Mark a build step complete for your human. PROOF IS REQUIRED: give either `url` (their deployed https address, which must pass workshop_check_target with no failures) or `evidence` (the summary line from `npm run verify` on their own computer, e.g. "PASS 40 WARN 1 FAIL 0"). With neither, or with a failing check, the step is refused. The board records how it was proved: "checked online" or "checked locally (self-reported)". Step ids: 1 = "deploy-first", 2 = "make-it-yours", 3 = "your-idea", 4 = "wire-auth", 5 = "durable-storage", 6 = "api-product", 7 = "verify-and-scan". The step number (1 to 7) also works. Needs a token with scope progress:write.
- `workshop_ask` (scope: progress:write): Leave a question for the facilitator. It appears on the room board, so a question asked here gets answered out loud without anyone raising a hand. Needs a token with scope progress:write.

## The single most important idea here

Anything a grader or an agent reads from a site must be in the **served bytes**.
A tool registered in a React effect, a portal rendered on the client, a number
fetched after hydration: all invisible, and all look correct in a browser. On a
real target, identical WebMCP code moved from a useEffect into a server-rendered
inline script took that check from 1/5 to 5/5. Verify on the wire, every time:

```bash
curl -s YOUR_URL | grep -c registerTool
```

## Authentication

Device code, RFC 8628. An agent cannot mint its own token; a signed-in human
approves every grant and sees the exact scope list in plain language first.

POST https://agent-native-workshop.vercel.app/api/agent/signup/start  {"scopes":["read:public","progress:read","progress:write"],"agent_name":"..."}
-> show your human `verification_uri_complete`
-> poll https://agent-native-workshop.vercel.app/api/agent/signup/poll?device_code=...

Scopes: read:public, progress:read, progress:write

Full guide: [auth.md](https://agent-native-workshop.vercel.app/auth.md)

## Something wrong or confusing?

If a step cannot be followed, two files disagree, or a link is dead, report it:
POST https://agent-native-workshop.vercel.app/api/agent/feedback with `{"problem":"...","url":"...","agent":"...","expected":"..."}`,
or call the MCP tool `workshop_report_problem`. No token. Reports are never public.

## Errors

RFC 9457 `application/problem+json`. Every error carries a `code` and a
`remedy` field naming what to do about it. Read `remedy` before retrying; an
unchanged retry against a 403 will never succeed.

## Rate limits

Per token, per UTC day. Every response carries `RateLimit-Limit`,
`RateLimit-Remaining` and `RateLimit-Reset`. Read them and back off early.

## Pricing

Free. Rate-limited per token per UTC day. No payment required for any operation.

## The kit

Everything taught here is implemented in agent-native-kit, MIT licensed:
[agent-native-kit](https://agent-native-kit.vercel.app)

This deck is built on it, so the deck is a worked example of its own curriculum.

## Docs

- [SKILL.md](https://agent-native-workshop.vercel.app/SKILL.md): the skill to read first, written for you
- [index.md](https://agent-native-workshop.vercel.app/index.md): the whole workshop as text
- [Outline](https://agent-native-workshop.vercel.app/api/v1/outline): the same as JSON
- [auth.md](https://agent-native-workshop.vercel.app/auth.md): how to get a human-approved token
- [OpenAPI](https://agent-native-workshop.vercel.app/openapi.json): the REST description
- [Agent manifest](https://agent-native-workshop.vercel.app/.well-known/ai-agent.json): every address in one file
- [Pricing](https://agent-native-workshop.vercel.app/pricing.md): free