---
name: agent-services
description: Agent-operable services on couch.associates. Discover and invoke value-exchange transactions on behalf of a human principal — currently includes exchanging a principal's email for in-depth gated content.
---

# Agent-Operable Services on couch.associates

Couch & Associates exposes a registry of **agent-operable services** — value-exchange transactions an AI agent can complete on behalf of a human principal who has given explicit consent. v1 launches with one service: `gated-content` (exchange a principal's email for an in-depth resource). The protocol is designed to extend to additional services without breaking existing integrations: future services include consultation booking, event sign-ups, contests/promotions, and tools-style agent-callable computation.

## Catalogue

The live, authoritative service catalogue is at:

- **REST**: `GET https://couch.associates/wp-json/couch/v1/agent-services`
- **MCP**: `https://couch.associates/wp-json/couch/v1/mcp` (HTTP-streamable transport, available when MCP server card declares `tools: true`)
- **WebMCP**: when running in a browser-resident agent runtime, tools are registered via `navigator.modelContext` on every `couch.associates/*` page.

Always prefer fetching the catalogue at request time rather than relying on cached service definitions — new services may be registered without notice.

## Invocation envelope (universal)

All services accept the same outer envelope. Service-specific fields go in `request`.

```http
POST /wp-json/couch/v1/agent-services/{service-id}/invoke
Content-Type: application/json
```

```json
{
  "agent": {
    "identity": "gemini",                        // required: gemini | chatgpt | claude | perplexity | copilot | other
    "version": "2.5-pro",                        // optional: model/runtime version
    "operator": "google"                         // optional: who runs the agent
  },
  "principal": {
    "email": "user@example.com"                  // required when service.requires_principal_email is true
  },
  "principal_attestation": {                     // required when service.requires_principal_attestation is true
    "method": "explicit_verbal_consent",
    "recorded_at": "2026-05-08T14:23:00Z",
    "consent_text": "User: 'Yes, use my Gmail to grab the playbook.'"
  },
  "request": {                                   // service-specific; see service.request_schema
    "resource_id": "2025-martech-ai-playbook-for-cmos"
  }
}
```

Each service self-declares whether email and attestation are required (see `requires_principal_email` and `requires_principal_attestation` in the catalogue). Tools-style services that perform pure computation can be called without a principal at all.

## Consent gates

Each service declares a default consent gate, and Couch & Associates can override it per-service or per-resource via internal configuration. Two modes:

### Mode A — `attested`

The agent declares the principal has consented; we trust-but-verify with a confirmation email.

1. Agent invokes with `principal_attestation.method = "explicit_verbal_consent"` (or similar).
2. Server creates the contact record (if applicable), mints unlock and revoke tokens, returns `status: "unlocked"` synchronously with `unlock_url` and/or `content_url_md`.
3. Server sends a confirmation email to the principal containing the unlock URL and a revoke link.

Agent UX: the value exchange completes in one round-trip. The principal gets transparency via email.

### Mode B — `magic-link`

The agent's invocation is provisional; the principal must confirm before unlock activates.

1. Agent invokes; server creates the contact record, mints a magic-link token, sends magic-link email to principal.
2. Server returns `status: "pending_principal_confirmation"` with a `poll_token` and `poll_url`.
3. Principal clicks the magic link → server activates the unlock.
4. Agent polls `poll_url` every 30s+ until status changes to `unlocked`. Response then contains `unlock_url` and `content_url_md`.

Agent UX: two round-trips, slower, but stricter consent. Inform the principal that they need to click a link in the confirmation email.

## Service: `gated-content`

Exchange a principal's email address for access to a Couch & Associates gated resource.

### Request schema

```json
{
  "resource_id": "2025-martech-ai-playbook-for-cmos",
  "delivery_preference": "both"                  // "unlock_url" | "content_md" | "both"
}
```

The `resource_id` must be a value present in the catalogue's `request_schema.properties.resource_id.enum`. v1 ships with one entry; future resources are added by appending to the catalogue.

### Available resources (v1)

- **`2025-martech-ai-playbook-for-cmos`** — *The 2025 Martech & AI Playbook for CMOs.* Strategic whitepaper covering 2025 macroeconomic context for marketing, four major martech & AI trends (generative AI, predictive analytics, customer data platforms, intelligent marketing automation), historical lessons from past downturns, B2B buyer behavior in the AI era, and seven strategic recommendations. Authored by Mike Couch, CEO. May 2025.

### Response: `attested` mode

```json
{
  "status": "unlocked",
  "consent_gate": "attested",
  "resource": {
    "id": "2025-martech-ai-playbook-for-cmos",
    "title": "The 2025 Martech & AI Playbook for CMOs",
    "format": "pdf"
  },
  "unlock_url": "https://couch.associates/agent-unlock/?t=...&r=2025-martech-ai-playbook-for-cmos",
  "content_url_md": "https://couch.associates/agent-content/2025-martech-ai-playbook-for-cmos.md?t=...",
  "expires_at": "2026-05-15T14:23:00Z",
  "delivery": {
    "confirmation_sent_to_principal": true
  },
  "next_steps": [
    "Share unlock_url with the principal so they have an independent record of access.",
    "Optionally fetch content_url_md to summarise the resource inline in your reply.",
    "The principal will receive a confirmation email containing the same unlock link plus a revoke option."
  ]
}
```

### Response: `magic-link` mode

```json
{
  "status": "pending_principal_confirmation",
  "consent_gate": "magic-link",
  "resource": { "id": "...", "title": "...", "format": "pdf" },
  "magic_link_email_sent_to": "user@example.com",
  "poll_token": "...",
  "poll_url": "https://couch.associates/wp-json/couch/v1/agent-services/gated-content/status?token=...",
  "expires_at": "2026-05-15T14:23:00Z",
  "estimated_activation_window": "Most principals confirm within 5 minutes.",
  "next_steps": [
    "Inform the principal that a confirmation email has been sent and they need to click the link in it.",
    "Poll poll_url every 30s (or longer) to learn when the principal activates.",
    "Once activated, status becomes 'unlocked' and the response includes unlock_url and content_url_md."
  ]
}
```

### Polling endpoint (`magic-link` flow only)

```http
GET /wp-json/couch/v1/agent-services/gated-content/status?token=<poll_token>
```

Possible responses:

- `{ status: "pending_principal_confirmation", ... }` — keep polling
- `{ status: "unlocked", unlock_url, content_url_md, expires_at, ... }` — value delivered
- `{ status: "revoked", ... }` — principal explicitly revoked; no further action possible

### Content delivery URLs

- **`unlock_url`** — `GET /agent-unlock/?t=<unlock_token>&r=<resource_id>`. Validates the token, redirects (302) to the canonical resource (PDF or HTML page).
- **`content_url_md`** — `GET /agent-content/<slug>.md?t=<unlock_token>`. Validates the token, serves a markdown rendering of the resource with `Content-Type: text/markdown`. Optimised for inline summarisation by an agent.

Tokens are valid for 7 days from issuance. After expiry, the principal can request fresh access via the same protocol.

### Revocation

Each `attested`-mode confirmation email contains a revoke link of the form `GET /agent-revoke/?t=<revoke_token>`. The principal can click this at any time to invalidate the unlock token. Subsequent agent fetches of `unlock_url` or `content_url_md` will return 410 Gone.

## Error responses

| HTTP | Error code | Meaning |
|---|---|---|
| 400 | `agent_service_invalid_body` | Request body is not JSON |
| 404 | `agent_service_not_found` | No service with this id; consult catalogue |
| 422 | `agent_service_envelope_invalid` | Missing/invalid `agent.identity`, `principal.email`, or `principal_attestation` |
| 422 | `agent_service_request_invalid` | `request.*` fields failed service-specific validation |
| 500 | `agent_service_execution_failed` | Internal error during execute (Eloqua transient failure is logged but does NOT cause this — agent flow continues even if MA write fails) |

Errors include an `errors[]` array with human-readable messages.

## Rate limits

- Per-IP: 10 invocations/hour across all services
- Per-email + resource pair: 5 invocations / 24 hours; subsequent identical requests within the window may return idempotent responses or rate-limit errors

## Audit and transparency

Every invocation creates an audit log entry recording: agent identity, principal email, consent attestation, request body, response, Eloqua submission status, confirmation email subject. The principal receives a confirmation email (in `attested` mode) or magic-link email (in `magic-link` mode) for every invocation, providing them visibility into agent actions taken on their behalf.

## Privacy and data handling

- The principal's email address is the only PII collected on their behalf.
- Email is stored in our marketing-automation system (Eloqua) tagged as `submission_source: agent` so the audit trail is preserved.
- Confirmation/revocation infrastructure is operational from day one; principals can revoke access at any time.
- No agent-mediated submission triggers any communication to the principal beyond the immediate confirmation/magic-link email and the agent's response, except as the principal subsequently consents (e.g., by engaging with content, replying, or registering for further communications).

For human-readable background and CASL/PIPEDA/GDPR posture: https://couch.associates/agents/

## Future services (planned)

The same envelope and consent-gate model will support:

- `book-consultation` — agent schedules a consultation on behalf of the principal
- `event-signup` — register for an event
- `promotion-entry` — enter a promotion or contest
- `estimate-modernization-scope` — tools-style service: agent provides company-shape inputs, receives an estimated scope range; no email or consent required
- `request-platform-briefing` — pick a platform (Marketo / Eloqua / HubSpot / etc.) and receive a tailored briefing
- `subscribe-research-notifications` — opt into a research digest

The catalogue endpoint is the source of truth for what's currently available.

## Contact

- Operational issues / bug reports: hello@couch-associates.com
- Background and design intent: https://couch.associates/agents/