Skip to main content

Install

Python 3.10 or newer is required.

Configure once

Wrap the completed ASGI app, then put your product authentication/tenant middleware outside Epode so it executes first. Identity extractors are synchronous accessors over verified or product-owned state, not authentication hooks:
account_id and user_id must come from verified authentication; first_party_visitor_id must be a stable product-owned pre-login reference. journey_id must come from server/product state that already proves continuity. Never populate any of them from a name, email, prompt, raw header, query/body value, or agent argument.

Server-rendered HTML

The same wrapper injects the machine-readable contract into finite HTML responses on included routes. JSON objects retain their existing shape and add _agentFeedback.

Route patterns and caching

In include/exclude patterns, * matches one path segment and ** matches any depth. cache_mode mirrors the Node SDK: the default "safe" skips responses that declare a shared cache policy, "private" replaces shared caching with private, no-store deliberately, and "request" instruments only requests that opt in with the Agent-Feedback-Request: 1 header. Request mode adds Vary: Agent-Feedback-Request so shared caches keep ordinary and opted-in responses separate. Eligible ordinary 2xx GET and HEAD responses also advertise a same-path-and-query Link for one authenticated Companion refetch; redirects and non-safe methods never advertise it.

Verify

Send a real request to an included route and inspect the response:
For the full automated check, run the integration doctor. It ships inside the Node SDK tarball (it is not on the npm registry), so any stack can run it with a throwaway install:
Then confirm Setup shows the first opportunity. The doctor deliberately creates no report. A generic HTTP client does not automatically prove agent use; the interaction becomes confirmed when its feedback capability returns.

Customer-agent coverage

Your ASGI middleware creates the HTTP/HTML feedback contract; it cannot make an independent customer agent act on it. For reliable Codex and Claude Code handling, customers install Epode Companion once for all Epode-instrumented products they use. This is a user-side plugin, not another Python package, account, or product key. View the runnable ASGI example