Agent Message Protocol (AMP)

AMP is a protocol for how AI agents express structured output for multi-surface rendering. It decouples message production (agents like Claude, Copilot, or Cursor) from message presentation (Kida templates), so teams control how agent output looks without changing agent behavior.

The problem AMP solves

Without AMP, AI agents dump raw markdown into PR comments. Each surface renders it differently, composition of multiple agent outputs is ad-hoc, and teams have no control over formatting or severity thresholds.

With AMP, agents emit structured JSON. Kida templates render that JSON to the right format for each surface — GitHub PR comments, step summaries, releases, Slack, or terminal. Composition is declarative.

Without AMP:

Agent → raw markdown → paste into PR comment
Agent → different markdown → paste into Slack
Agent → yet another format → paste into terminal

With AMP:

Agent → structured JSON → Kida template → GitHub PR comment (markdown)
                        → Kida template → Slack message (mrkdwn)
                        → Kida template → Terminal output (ANSI)

How it works

AMP has three layers:

1. Produce — An agent outputs JSON conforming to an AMP schema (e.g.,code-review, pr-summary).
2. Validate — The JSON conforms to a published JSON Schema atschemas/amp/v1/.
3. Render — A Kida template consumes the JSON and renders it for a specific surface.

Agents don't need to know about rendering. Templates don't need to know about agents. The schema is the contract.

Quick example

A Claude code review produces this JSON:

{
  "agent": "Claude",
  "model": "claude-sonnet-4-20250514",
  "confidence": 0.87,
  "summary": "Found 2 issues: 1 security warning, 1 bug.",
  "findings": [
    {
      "file": "src/app/db.py",
      "line": 42,
      "severity": "warn",
      "category": "security",
      "title": "SQL injection risk",
      "message": "Query built with f-string interpolation.",
      "suggestion": "Use parameterized queries.",
      "diff": "- query = f\"SELECT * FROM users WHERE id = {user_id}\"\n+ query = \"SELECT * FROM users WHERE id = %s\"\n+ cursor.execute(query, (user_id,))",
      "confidence": 0.94
    }
  ],
  "stats": {
    "files_reviewed": 8,
    "findings_count": 2,
    "by_severity": { "error": 0, "warn": 2, "info": 0, "suggestion": 0 }
  }
}

Render it locally:

kida render templates/code-review-report.md --data review.json --mode markdown

The template produces a formatted PR comment with severity badges, clickable file links, diff suggestions, and collapsible low-confidence findings. See Agent Templates for all built-in templates.

Message types

AMP v1 defines six message types. Each has a JSON Schema and one or more reference templates.

Schemas are published atschemas/amp/v1/<type>.schema.json.

Surfaces

A surface is a rendering target with specific format constraints and capabilities.

Templates can adapt output based on surface capabilities. For example, a code-review template uses<details>blocks on GitHub but flat headings on terminal.

Composition

When multiple agents review the same PR, AMP defines four composition modes for combining their output:

Choose the composition mode in your workflow's render or data-preparation step. In the GitHub Action, thecomment-mode input only controls how the final PR comment is updated (replace or append); it does not select AMP composition modes such as thread or aggregate.

Agent metadata

Every AMP message may include metadata to identify its source:

Templates useconfidence to filter or collapse low-confidence findings. The run_idenables deduplication when the same agent runs multiple times on a PR.

Next steps

• Agent Templates — the built-in templates for each message type, with schema details and customization
• Agent Integration Tutorial — end-to-end setup from agent config to rendered PR comments
• GitHub Action — CI report rendering and thecomment-modeinput