> ## Documentation Index
> Fetch the complete documentation index at: https://docs.epode.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent experience graph

> Merchant-authored need negotiation for customer agents.

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

1. Start with generic dimensions, not values that look like remembered profile fields.
2. Reveal catalog-derived values only after the agent selects a relevant dimension.
3. Require one real decision input before ranked results.
4. Carry typed need state through exact merchant-authored transitions.
5. Open exactly one supplied edge per hop. Never invent path segments.
6. Separate exact matches from near misses.
7. Offer counterfactuals only when hard requirements produce zero exact matches.
8. Keep signed machine `detailUrl` links for evidence retrieval separate from an optional
   merchant-authored, same-origin `humanProductPath` for the person's clean, durable handoff.
9. 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.
10. Map journey hops onto Epode `sessionRef` / `operation` telemetry without extending the closed
    telemetry schema with free-form need-state blobs.

## Node SDK

```ts theme={null}
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:

```ts theme={null}
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:

```bash theme={null}
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](/concepts/task-intent-evidence).
It keeps the business outcome visible without claiming the graph caused it.