Node + Express

Customer enrichment (recommended)

When the same application serves an agent experience graph, call mountExperienceGraph(app, options) immediately after express() and before any global app.use(...) middleware. Its fail-closed startup check allows earlier route-specific layers only when they cannot shadow the graph namespace.

npm install @epode/node express

import { epode } from "@epode/node/express";

app.use(express.json());
app.use(issueOrVerifyFirstPartyVisitor);

const customer = epode({
  apiKey: process.env.EPODE_API_KEY,
  include: ["/api/recommendations"],
  purpose: "product_personalization",
  authenticate: authenticateProductRequest,
  identify: req => ({
    accountRef: req.user?.accountId,
    userRef: req.user?.id,
    anonymousRef: req.firstPartyVisitorId,
  }),
  sessionRef: req => req.productJourney?.id,
  runtimeHint: req => req.verifiedAgentRuntime,
});
app.use(customer);

This one middleware instruments eligible JSON and server-rendered HTML responses and mounts the company-owned same-origin consent and answer relay. The customer installs nothing. Epode failures preserve the original response. Use customer.context.get, customer.personalization.decide, and customer.outcomes.track as shown in the quickstart. The same enrichment request records the final HTTP status, product-handler duration, optional product-issued journey, and optional bounded runtime label. Never populate sessionRef or runtimeHint from query parameters, agent input, or other unverified values. The selected response waits at most timeoutMs (250 ms by default) for the enrichment request. A timeout or failure returns the original JSON unchanged. For routes without a stable company identity, use customer.contextFor(request); it validates the agent-returned Epode-Context-Interaction header so context is available only on the immediate retry of the same interaction. authenticate runs only on included business routes. The adapter bypasses it only for the exact POST relay paths, which authenticate with their short-lived aqr1_ capability. Do not mount rejecting global product auth above the Epode middleware.

Server-rendered HTML

Bounded successful HTML strings on included routes receive a non-executable <meta name="epode-customer-context"> marker containing base64url JSON. This preserves the page’s CSP and visible content. Streams, buffers, documents over maxHtmlBytes (512 KiB by default), and pages that already own the marker remain unchanged. Mutated pages become private, no-store; stale length, digest, and ETag headers are removed or regenerated. Run the anonymous-to-known retail example · Run the anonymous advertising example

Legacy structured outcome feedback

Install

npm install https://app.tryintents.com/static/agent-feedback-node-0.5.28.tgz express

Node 20 or newer is required.

Configure once

Run product authentication and authorized tenant selection first, then register Epode before the included route handlers. Identity accessors only read state your product already verified or owns.

import express from "express";
import { agentFeedback } from "@epode/node/express";

const app = express();

app.use(authenticateProductRequest);
app.use(selectAuthorizedTenant);
app.use(agentFeedback({
  apiKey: process.env.AGENT_FEEDBACK_KEY,
  include: ["/search", "/docs/*"],
  accountRef: req => req.user?.accountId,
  userRef: req => req.user?.id,
  anonymousRef: req => req.firstPartyVisitorId,
  customerRef: req => req.user?.accountId, // durable Ask once compatibility
  sessionRef: req => req.agentSession?.id, // optional server-issued journey
}));

app.get("/search", async (req, res) => {
  res.json({ results: await search(req.query.q) });
});

app.listen(Number(process.env.PORT || 3000));

No route wrapper or response call is required. The middleware derives the normalized operation from the Express route.

Cached APIs

The default cacheMode: "safe" does not silently turn a response with public, max-age, s-maxage, immutable, or stale-while-revalidate into a private response. It skips those responses and logs one configuration warning. If ordinary callers share a CDN response but feedback-aware agent callers can opt in, use request mode:

app.use(agentFeedback({
  apiKey: process.env.AGENT_FEEDBACK_KEY,
  include: ["/v1/search"],
  cacheMode: "request",
  accountRef: req => req.user?.accountId,
  userRef: req => req.user?.id,
  anonymousRef: req => req.firstPartyVisitorId,
  customerRef: req => req.user?.accountId,
  sessionRef: req => req.agentSession?.id,
}));

The agent caller sends Agent-Feedback-Request: 1. Only that request receives feedback metadata and becomes private, no-store; the public response keeps its existing cache policy. The SDK also adds Vary: Agent-Feedback-Request, so a CDN cannot replay the ordinary cached body to an opted-in caller. Use cacheMode: "private" only when disabling shared caching on every included response is intentional. Eligible ordinary 2xx GET and HEAD responses also carry a same-path-and-query Link marker, allowing an installed Epode Companion to make one authenticated opt-in refetch without changing the public body. * matches one path segment (/docs/* matches /docs/guide). Use ** for any depth (/docs/** also matches /docs/platform/authentication).

Async jobs

Instrument the result, not every polling response:

app.use(agentFeedback({
  apiKey: process.env.AGENT_FEEDBACK_KEY,
  include: ["/v1/crawls/*"],
  shouldInstrument: (_req, response) =>
    response.body?.status === "completed",
  sessionRef: req => req.authorizedCrawl?.id,
}));

Creation responses, in-progress polls, and failures remain untouched. The terminal result asks for one assessment after the agent can judge the experience. authorizedCrawl.id must be the server-loaded job the authenticated caller is allowed to access—not a raw header, query value, or unverified body field.

Server-rendered HTML

Use the same middleware and include the HTML route:

app.use(agentFeedback({
  apiKey: process.env.AGENT_FEEDBACK_KEY,
  include: ["/agent-docs", "/docs/*"],
}));

Eligible HTML receives an embedded <script id="agent-feedback" type="application/json"> contract. It does not change the visible page.

Verify

npx agent-feedback-doctor https://your-product.example/search?q=epode-test

The doctor checks shape preservation, the scoped capability, trusted submission origin, and the company-side opportunity without creating feedback. In ask modes, it validates consent without claiming approval. Use a real customer-agent task to prove confirmation and reporting.

Serverless and edge-hosted Node

Keep the middleware object outside the request handler when the platform reuses isolates. If the platform provides waitUntil, attach feedback.flush() to that lifecycle hook after the response is committed:

context.waitUntil(feedback.flush());

Do not await telemetry before sending the product response. On platforms with no background lifecycle at all, opportunity telemetry is best effort and may be dropped when an isolate freezes; feedback reports still use their independent signed submission path.

Customer-agent coverage

Your middleware creates the HTTP feedback contract; it cannot make an independent customer agent act on that contract. For reliable Codex and Claude Code handling, customers install Epode Companion once for all Epode-instrumented products. This is a user-side plugin, not another company SDK or product key. Generic agents without the Companion can still use the API normally, but feedback remains best effort.

What is not instrumented

Errors, redirects, health and metrics routes, assets, streams, binary responses, and routes outside include remain untouched. JSON arrays and scalar values use response headers instead of being wrapped. View the runnable Express example View the cached search API example

Start here

Understand Epode

HTTP and websites

MCP

Operate

Node + Express

Customer enrichment (recommended)

Server-rendered HTML

Legacy structured outcome feedback

Install

Configure once

Cached APIs

Async jobs

Server-rendered HTML

Verify

Serverless and edge-hosted Node

Customer-agent coverage

What is not instrumented

​Customer enrichment (recommended)

​Server-rendered HTML

​Legacy structured outcome feedback

​Install

​Configure once

​Cached APIs

​Async jobs

​Server-rendered HTML

​Verify

​Serverless and edge-hosted Node

​Customer-agent coverage

​What is not instrumented

Customer enrichment (recommended)

Server-rendered HTML

Legacy structured outcome feedback

Install

Configure once

Cached APIs

Async jobs

Server-rendered HTML

Verify

Serverless and edge-hosted Node

Customer-agent coverage

What is not instrumented