Configuration Options Reference for Agent Feedback SDK

Every Agent Feedback adapter accepts an AgentFeedbackOptions object when you mount the middleware. The options shape is defined in core.ts and is shared across Express, Fastify, and MCP adapters. Pass the object once at startup — the runtime validates your key format immediately and throws synchronously if the key cannot produce v2 capability tokens.

Complete configuration example

import { agentFeedback } from "@agent-feedback/node/express";

app.use(agentFeedback({
  apiKey: process.env.AGENT_FEEDBACK_KEY,
  include: ["/api/search", "/api/docs/*"],
  exclude: ["/api/internal/*"],
  feedbackMode: "auto",
  customerRef: req => req.user?.accountId,
  sessionRef: req => req.headers["x-session-id"] as string | undefined,
}));

import { agentFeedback } from "@agent-feedback/node/fastify";

await fastify.register(agentFeedback, {
  apiKey: process.env.AGENT_FEEDBACK_KEY,
  include: ["/api/search", "/api/docs/*"],
  exclude: ["/api/internal/*"],
  feedbackMode: "auto",
  customerRef: req => (req.user as { accountId?: string })?.accountId,
  sessionRef: req => req.headers["x-session-id"] as string | undefined,
});

Never commit your API key to source control. Always read it from an environment variable such as process.env.AGENT_FEEDBACK_KEY.

Required options

string

required

Your product key. Keys follow the format af_live_<32hex>_<secret> where the 32-character hex segment is the public key ID and the remainder is the signing secret. The runtime derives an HMAC signing key from the full key value and stores nothing beyond that derivation.

apiKey: process.env.AGENT_FEEDBACK_KEY

If you pass a key that does not match the v2 key format, the middleware throws at startup with the message: “This product key cannot create v2 feedback receipts. Create a new key in Agent Feedback Setup.” Create a new product key in the dashboard rather than modifying an old one.

Endpoint

string

Override the Agent Feedback API base URL. Use this when you route traffic through a proxy or when testing against a staging backend.If omitted, the SDK checks the AGENT_FEEDBACK_URL environment variable, then falls back to the Agent Feedback hosted service.

endpoint: process.env.AGENT_FEEDBACK_URL // or set the env var directly

Route filtering

string[]

An allowlist of URL path patterns to instrument. Supports single-segment wildcards (*) and multi-segment wildcards (**). For example, /docs/* matches /docs/intro but not /docs/guides/setup; /docs/** matches both.When include is omitted, the SDK instruments every route that isn’t excluded. Start with a narrow list targeting your highest-value endpoints and expand once you’ve verified the contract with the doctor tool.

include: ["/api/search", "/api/docs/*", "/api/answers/**"]

string[]

A denylist of URL path patterns to skip. Your entries are merged with the SDK’s built-in exclusions, which always cover:

/health, /healthz
/metrics
/favicon.ico, /robots.txt
/_agent-feedback/*
/api/v2/outcomes

You cannot remove the built-in exclusions; you can only add to them.

exclude: ["/api/internal/*", "/api/admin/**"]

Feedback mode

"auto" | "ask" | "off"

Controls how the feedback instruction is phrased in every eligible response. Defaults to "auto".

Value	Behaviour
`"auto"`	Instructs the agent to submit autonomously before its final response. The `requested` flag in the envelope is `true`.
`"ask"`	Requests feedback but does not command the agent — useful for sensitive product areas where you prefer a softer tone. The `requested` flag is `false`.
`"off"`	Disables the feedback contract entirely. No `_agentFeedback` field is appended and no telemetry is enqueued.

feedbackMode: "auto"

You can also disable instrumentation at the process level by setting AGENT_FEEDBACK_ENABLED=false in the environment without touching your code.

Context extractors

These functions run per-request. If an extractor throws, the SDK logs a warning and continues — the product response is never affected.

(request: Request) => string | undefined | null

Returns an opaque string that identifies the customer account in your system — for example, an account ID or organization slug. This is your reference, not an agent identity; Agent Feedback never uses it to identify agents.The value is recorded in telemetry for your own cross-referencing. It is intentionally excluded from capability tokens so a customer-ref cannot be used to forge or correlate submissions.

customerRef: req => req.user?.accountId

(request: Request) => string | undefined | null

Returns a session continuity string. The SDK accepts only values that come from company-provided headers or MCP proof of continuity — it does not perform time-window grouping or infer sessions from timestamps.

sessionRef: req => req.headers["x-session-id"] as string | undefined

(request: Request) => string | undefined | null

Returns a hint about the agent runtime making the request — for example "claude" or "openai". The value is logged as explicitly unverified and is never presented as confirmed agent identity.

runtimeHint: req => req.headers["x-agent-runtime"] as string | undefined

Observability

Logger

A custom logger with debug and warn methods. The Logger type matches the subset of Console that the SDK uses, so you can pass console directly or any structured logger that implements the same interface.Defaults to console.

import pino from "pino";

const logger = pino();

app.use(agentFeedback({
  apiKey: process.env.AGENT_FEEDBACK_KEY,
  logger: {
    debug: (msg) => logger.debug(msg),
    warn: (msg) => logger.warn(msg),
  },
}));

Telemetry queue tuning

Telemetry is sent on a background queue. Neither option affects product response latency — the response is sent before any network call is made.

number

How often (in milliseconds) the background queue is flushed to the telemetry endpoint. Defaults to 500 ms. The queue also flushes immediately when it accumulates 50 or more events, regardless of the timer.

flushIntervalMs: 2000

number

Maximum number of telemetry events to hold in memory. When the queue reaches this limit, the oldest event is dropped to make room for the new one. Defaults to 1000. Events are never allowed to block or slow the product response.

maxQueueSize: 500

Telemetry delivery failures do not affect your product responses. If the telemetry endpoint is unreachable, the SDK retries up to three times per event, logs a single warning, and then discards the batch rather than accumulating unbounded memory.

Get Started

Core Concepts

SDK Guides

Agent Integration

Configuration & Tools

Configuration Options Reference for Agent Feedback SDK

Complete configuration example

Required options

Endpoint

Route filtering

Feedback mode

Context extractors

Observability

Telemetry queue tuning

​Complete configuration example

​Required options

​Endpoint

​Route filtering

​Feedback mode

​Context extractors

​Observability

​Telemetry queue tuning

Complete configuration example

Required options

Endpoint

Route filtering

Feedback mode

Context extractors

Observability

Telemetry queue tuning