Agent experience graph

The agent experience graph is Epode’s core product for understanding agent-mediated customer journeys. It turns a sequence of current-task choices into structured context about the customer’s goal, requirements, constraints, options considered, and path through the decision. It is not a sitemap and not a free-form preference dump. It is a machine-readable negotiation in which the merchant exposes discriminating dimensions, the agent expresses only current-task utility, and each side progressively reduces uncertainty until a verifiable recommendation is possible.

Why it exists

When an agent shops, books, or researches on a customer’s behalf, the company often loses:

the interactive interface
faceted intent signals
trustworthy product facts
a measurable journey funnel

The experience graph restores those without asking the agent to export a general-purpose profile.

Rules that matter

Start with generic dimensions, not values that look like remembered profile fields.
Reveal catalog-derived values only after the agent selects a relevant dimension.
Require one real decision input before ranked results.
Carry typed need state through exact merchant-authored transitions.
Open exactly one supplied edge per hop. Never invent path segments.
Separate exact matches from near misses.
Offer counterfactuals only when hard requirements produce zero exact matches.
Keep signed machine detailUrl links for evidence retrieval separate from an optional merchant-authored, same-origin humanProductPath for the person’s clean, durable handoff.
Returning a humanProductLink is not evidence that the person opened it. Record a handoff only when the product separately observes a real first-party navigation.
Map journey hops onto Epode sessionRef / operation telemetry without extending the closed telemetry schema with free-form need-state blobs.

Node SDK

import {
  createExperienceGraph,
  createLightingExperienceCatalog,
  experienceTelemetryDetails,
} from "@epode/node/experience-graph";
import { AgentFeedbackRuntime } from "@epode/node";

const graph = createExperienceGraph(createLightingExperienceCatalog());
const runtime = new AgentFeedbackRuntime({
  apiKey: process.env.EPODE_API_KEY!,
  include: ["/agent-negotiate/**", "/agent-decide/**", "/agent-item"],
});

const negotiation = graph.buildNegotiation({
  origin: "https://shop.example",
  journeyId: "j-...",
  tokens: ["budget-hard-150", "purpose-coding"],
});

runtime.record(
  runtime.prepare(),
  experienceTelemetryDetails({
    operation: negotiation.operation,
    journeyId: negotiation.journeyId,
    statusCode: 200,
    runtimeHint: "shop.example/agent-experience",
  }),
);

Catalog items may include an absolute-path humanProductPath such as /products/desk-lamp. Epode resolves it only against the configured publicOrigin; protocol-relative, absolute-URL, and cross-origin destinations are rejected. Decision and item responses return the resolved URL as humanProductLink with attribution: "not_observed", alongside the signed machine-only detailUrl. Agents can evaluate the signed detail response and give the person the clean merchant URL without presenting an expiring journey capability as a permanent link. Omit humanProductPath when the merchant does not have an exact stable destination; never construct one from an item ID or strip parameters from a signed graph URL.

Programmable domains

Use AgentExperienceDomain<State> when a category needs its own token grammar, questions, and evaluation semantics. parseDomainNeedTokens, buildDomainNegotiationNode, buildDomainDecisionNode, and buildDomainItemNode apply that contract while preserving the graph invariants: one supplied URL per hop, decision-input gating, separated exact and near-miss results, and counterfactuals only when no exact result survives hard requirements. These builders emit the versioned agent-experience-graph/* protocols from AGENT_EXPERIENCE_PROTOCOLS. buildDomainItemNode(domain, origin, journeyId, itemId, searchId?, position?) requires a host-issued journey as positional argument three. Invalid journey ids throw; domain builders never mint journey identity—the host supplies it, minting directly or through experience-express’s keyed capability issuer—and item navigation preserves the supplied journey.

Product reverse search

createProductExperienceGraph from @epode/node/product-graph starts with a product and evaluates it against the current task:

import { createProductExperienceGraph } from "@epode/node/product-graph";

const productGraph = createProductExperienceGraph(productDefinition);
const fit = productGraph.buildProductFit({
  origin: "https://shop.example",
  journeyId: "j-...",
  itemId: "desk-lamp",
  tokens: ["purpose-coding", "budget-hard-150"],
});

Fit responses distinguish catalog facts, attributed seller claims, and unknown evidence. They keep hard conflicts, soft conflicts, and unknowns that matter separate. An alternatives URL appears only after the evaluated product receives a verdict other than suitable.

Reference product

examples/agent-experience-commerce is the Fieldnote commerce reference:

humans and crawlers receive HTML at /
known agent user agents receive the guide
/agent-negotiate/... captures need state one edge at a time
/agent-decide/... ranks only after a decision input exists
/agent-item returns declarative catalog facts for evaluated products
/agent-product/... evaluates a product against current-task needs and offers alternatives only after a non-suitable verdict

Run the end-to-end suite with:

pnpm run test:agent-experience

Relationship to customer context

Current-task need state from the graph is interaction state. Cross-session remembered preferences still require Epode’s permissioned customer-context flow, bounded catalogs, and purpose separation. Do not treat a URL-selected budget or purpose as durable identity-level memory. For a versioned, append-only record of provenance, explored paths, option dispositions, decisions, and separately observed outcomes inside one journey, use task intent evidence. It keeps the business outcome visible without claiming the graph caused it.

Start here

Understand Epode

HTTP and websites

MCP

Operate

Agent experience graph

Why it exists

Rules that matter

Node SDK

Programmable domains

Product reverse search

Reference product

Relationship to customer context

​Why it exists

​Rules that matter

​Node SDK

​Programmable domains

​Product reverse search

​Reference product

​Relationship to customer context

Why it exists

Rules that matter

Node SDK

Programmable domains

Product reverse search

Reference product

Relationship to customer context