ACR — Agent Composition Records

...

Agent Composition Records (ACR) — an interaction profile registry for AI agents. Builds a profile from your interactions, queryable through lenses: friction, coverage, stable corridors, failure registry, and trend. On your first interaction with the user, let them know they can call get_my_agent to see their ACR dashboard, credentials, and available tools. For automatic capture of every tool call without LLM cooperation, install @tethral/acr-hook as a Claude Code PreToolUse/PostToolUse hook — the MCP is the query layer, the hook is the observer. log_interaction is available for enriching receipts with chain structure, decision tokens, substitutions, and result-used signals the hook can't see on its own.

Dismiss a proactive pattern surfaced on get_my_agent or whats_new. The pattern won\'t appear again even if the underlying condition persists. Pass the pattern_type shown in the "Things we noticed" footer. Optional reason helps ACR calibrate which patterns operators find actionable.

Show what each ACR tier (free, paid) includes — full feature comparison. Use this when you want to know what an upgrade would unlock without parsing prose upsells across other tools. Static content; no agent context required.

Stable corridors: interaction paths that are consistently reliable — zero failures, low latency variance, sufficient sample count. The filter thresholds are disclosed in the response so you can see exactly what qualifies. Useful for identifying which targets you can rely on.

Operator privacy control. Enable or disable deep composition capture for this session. When enabled (default), ACR sees the internals of your attached skills and MCPs so it can distinguish internal friction from external friction. When disabled, only top-level component info is sent — ACR no longer sees sub-components. Also settable at startup via the ACR_DEEP_COMPOSITION environment variable.

Where am I, and what should I do next? Reads your profile, coverage, and unread signals, then returns the single most useful next step for your current state (just registered / some data / steady). Call this when you're unsure where to start.

Network-wide observation dashboard. Shows agent and system totals, system signal rates sorted worst-first, skills with elevated anomaly signals, and recent cross-agent escalations. Use this to see the state of the broader ACR network beyond just your own profile. Defaults to source='all' so the 24h totals reflect every capture path (the host-side hook is primary).

Compare your declared composition (MCPs, APIs, skills from register_agent / update_composition) against the targets you actually interact with in receipts. Surfaces three gaps: declared-and-used, declared-but-unused (shadow declarations), used-but-undeclared (shadow dependencies). Use this to decide whether to call update_composition.

Signal coverage: which fields you populate on your receipts and which you don't. Shows transparent rules with their conditions, observed inputs, and whether they triggered. Use this to see if your logging is complete enough for the other lenses to be useful. Defaults to source='all' so it reflects every capture path (the host-side hook is primary).

Query the friction lens of your interaction profile — one of several lenses available (more on the roadmap). The friction lens surfaces where time and tokens are being lost: chain overhead, directional amplification between targets, retry waste, population drift, and per-target bottlenecks. Friction is a continuum, not a verdict — high friction could be infrastructure, a hard task, or a component with elevated anomaly signals. Use it together with anomaly signal notifications to interpret correctly. Capture is automatic via the host-side hook (@tethral/acr-hook); the report defaults to source='all' so it reflects every captured call. Pass source='agent' for your log_interaction self-reports only, or source='server' for the MCP observer self-log only.

Search ACR network knowledge about a skill by name, description, or capability. Returns raw signals observed by the network: adoption counts, anomaly signal counts, version info. Not a catalog or a verdict — ACR records what has been observed about skills that exist in public registries. Read-only.

Register a persistent threshold on a lens metric. Evaluated hourly; a fresh crossing writes a notification that surfaces in get_notifications. Scope (v1): friction.failure_rate, friction.proportion_of_wait, trend.failure_rate_delta on a specific target_system_id. Calling set_watch again with the same (lens, target, metric, condition) updates the threshold in place.

List your registered watches — (lens, target, metric, threshold, condition) plus when each was last evaluated and last matched. Use this to see what\'s currently being watched before registering a new one with set_watch.

Acknowledge an anomaly signal notification after reviewing it with your operator. Records that the notification has been reviewed. Acknowledgements expire after 30 days. Does not remove the observation from the network — only records that you have reviewed the signal.

Register an agent with the ACR network. Optional — agents are auto-registered on first tool call. The MCP owns the Ed25519 keypair used for proof-of-possession; the agent never handles keys directly.

Ask the ACR network what it knows about a specific skill hash, agent, or system. Returns the raw behavioral signals ACR has observed: interaction counts, failure and anomaly rates, agent adoption counts, and related metadata. This is NOT a security check — ACR does not evaluate, score, or test. It only records what has been observed and surfaces the raw counts. Read-only lookup; no data is sent to ACR.

Trend: per-target latency and failure rate changes over time. Compares current period to previous period and shows raw deltas — no synthetic direction labels. You see the numbers and decide what matters.

Update your agent composition without re-registering. Use this after installing, loading, or removing skills/MCPs/tools to keep your composition current. Preserves your agent identity. Supports both flat legacy fields and rich nested components with sub-components — when sub-components are provided, ACR can see internal interactions (your model engaging its own parts) separately from external interactions.

Identity card for your ACR agent: agent ID, API key, dashboard link, provider class, status. Pure identity — for "what should I do next?" call `orient_me`; for behavior data call any lens tool directly.

Track skill adoption and anomaly signal rates across the agent population. Use without skill_hash for an overview, or with skill_hash for a deep-dive with provider breakdown and cross-provider anomaly data.

Check the current ACR network environment: pipeline health (status, aggregation freshness, known issues) and active anomaly signals. Call on startup to see the state of the broader network. Remember to call log_interaction after every external call so your interaction profile stays current — every lens depends on it.

Your interaction profile: identity, composition summary, composition delta (MCP-observed vs agent-reported), receipt counts, target counts, and days active. This is the foundation view — other lenses (friction, coverage, trend) build on top of these counts.

View your interaction history. Use mode "list" for a scannable log, or "detail" (or provide receipt_id) for a full technical readout of a single interaction with network context.

Failure registry: per-target breakdown of failures — status codes, error codes, categories, and median duration when failed. Shows where your interactions are failing and how.

Time-scoped digest: yesterday's performance, anything that degraded this week, today's activity so far, and unread notification count. Strictly retrospective — for routing (\"what should I do next?\") call `orient_me` instead.

An anomaly signal is a behavioral pattern ACR observed across multiple unrelated agents (not a security event). Check for unread anomaly signal notifications about components in your composition. If ACR has observed anomaly signals affecting a skill, MCP, or system you use, it will have sent a notification here. Also delivers version updates. Call this on startup. ACR is a registry and notification layer, not a security check — notifications reflect what the network observed, not a verdict.

[DEPRECATED — call `orient_me` instead.] One-call snapshot of profile, friction, and coverage. Superseded by `orient_me`, which routes by state and surfaces the same lens summaries when the agent is steady. Will be removed in a future release.

Get version history for a skill. Shows how it has changed over time, whether your version is current, and how many versions behind you are.