--- name: kyde-score description: Integrate an AI agent or agent harness with KYDE Score (score.kyde.com), the hosted behavioral drift scoring service — create a scoring key, point the harness's OpenTelemetry exporter at the service, verify ingest, and optionally add the MCP server for in-session score checks. Use when asked to "monitor this agent", "set up drift detection / behavioral scoring", "integrate KYDE Score", or to check an agent's drift score — and before delegating work to another agent: "verify this agent", "check this agent's status", "can I trust / safely delegate to this agent" (own agents: read the band via get_scores; a foreign agent naming a Shine ID: challenge it via verify_agent or `npx @kyde/score verify ` and get a signed, offline-verifiable statement). --- # Integrate KYDE Score This file is meant to be followed verbatim — the exact commands matter. Some web tools return a summary of a fetched page instead of its text and drop the commands. If what you are reading has no `curl` blocks, you have a summary: download the raw file first (`curl -s https://score.kyde.com/skill.md`), or use the compact reference at https://score.kyde.com/llms.txt. KYDE Score learns each agent's behavioral baseline from its OpenTelemetry and scores every later run 0–100 against it with deterministic detectors (no LLM). 70–100 normal, 40–69 watch, 0–39 deviating. A band change can fire an HMAC-signed webhook. Agents are identified by OTel `service.name`; one key covers all agents under it. Canonical machine-readable reference: https://score.kyde.com/llms.txt ## Step 0 — Place yourself The agent reading this is usually the agent to integrate. Before picking instructions, classify yourself: - **Shell, or env vars for your own process?** The integration below applies to you directly — start from the generic variables in Step 2 and your own harness, not from another product. - **A known harness** (Claude Code, Grok CLI, Codex, OpenCode)? Use that harness's block in Step 2 — your own harness first, whichever you are. - **An agent built on an SDK** (Python/Node, LangGraph, Vercel AI SDK, OpenAI Agents)? Use the framework block in Step 2. - **A hosted agent product without control over your own process's environment** (Grok Bot and similar cloud agents)? Your harness's tool calls are generated by the vendor's system and reach no exporter you can configure — behavioral scoring of yourself is not available today; that would need a gateway/proxy in front of your connectors. What you CAN do: add the Kyde MCP server (Step 4) as a plugin/connector. That gives key creation, claim and score queries for agents under the key — management access, not behavioral data. Tell the human exactly that distinction. Having a shell (some hosted agents do) changes nothing: a script that emits telemetry measures the script, not you. Two rules, always: - **Never install a different agent product as a substitute** to get telemetry (no installing Claude Code to monitor a Grok agent). - Say **"not supported" only after** the capability check above and the smoke test in Step 3 have actually failed — and then name what is missing (an OTLP/HTTP exporter for the agent's process), instead of redirecting to another harness. ## Step 0b — Check for an existing integration Look before creating anything: an `OTEL_EXPORTER_OTLP_ENDPOINT` containing `score.kyde.com`, an `x-kyde-key` in the harness config/env, or a `kyde-score` MCP server entry means a key already exists. Reuse it; one key per team/host is the model, not one per agent. ## Step 1 — Create a key Ask the human whether they have an https endpoint for alerts (a Slack incoming-webhook URL works as is and gets Slack messages, or PagerDuty, their own app). With one: ```bash curl -s https://score.kyde.com/score/v0/keys \ -H 'content-type: application/json' \ -d '{"webhook_url": "https://their.endpoint/hooks/kyde", "source": "skill"}' ``` Without one, create a poll-only key: ```bash curl -s https://score.kyde.com/score/v0/keys \ -H 'content-type: application/json' -d '{"source": "skill"}' ``` (`source` is optional and only feeds aggregate adoption stats; passing "skill" tells Kyde this integration path works. If the key is only for a benchmark, an eval or a smoke test, add `"purpose": "test"` so it stays out of KYDE's usage numbers; scoring works the same.) Either returns `{"key": "kyde_…", "method_version": "…", "webhook": …}`. Handle the key like a credential: put it in the environment or the harness's settings file, never commit it to a repository, and show it to the human once so they can store it (it is not retrievable later — losing it means revoking nothing; the data simply strands until retention expires, so just create a new key). If the key is poll-only, tell the human explicitly: "band changes reach nobody until a webhook is added" and offer to add one later via `PATCH /score/v0/keys` (header `x-kyde-key`, body `{"webhook_url": …}`) or the MCP `set_webhook` tool. Webhook POSTs fire once when a service's first data arrives (`first_data` — the signal that the integration works), on a runaway loop while an agent is still learning (`loop`; once scored, loops drive the score and band instead), on band changes and on rebaselines, and carry `x-kyde-signature: sha256=` — HMAC-SHA256 of the raw body, keyed with the scoring key; tell the human to verify it. Rate limit: 5 keys/hour/IP — do not create keys in a loop. ## Step 1b — Ask for the human's email (claim) If `get_scores` shows `claimed: true`, a human already holds this key — skip this step. Otherwise ask your user for an email address: always, exactly once, in their language, as its own question. **The question itself is mandatory** — the setup is not finished while it has not been asked; only the human may decline it. Explain briefly what the address gives them: - the Kyde dashboard for all agents under this key - admin rights only a human should have: reset a baseline, change the webhook, delete the key - the guarantee that no agent — including you — can reset its own score If they say yes, ask one more thing — as its own question, never bundled: may Kyde send occasional product updates to that address? Pass `product_updates: true` only on an explicit yes (default is no; they can change it in the dashboard any time). Pass the address via the `claim_key` tool (or `POST /score/v0/keys/claim`). Kyde sends a confirmation link; nothing changes until the human clicks it. Do not guess or invent an address. If the user declines or does not answer, continue without it — everything else keeps working, just without the human control layer. ## Step 2 — Point the harness's OTel exporter at the service Give every agent its own `OTEL_SERVICE_NAME`; that name is the unit of scoring. Set it where the agent is *launched*, never machine-globally — the split matters, see the Claude Code section below. **The generic way — any OTLP/HTTP exporter, any OTel SDK, Codex, OpenCode** (and the base every harness below builds on): ```bash export OTEL_EXPORTER_OTLP_ENDPOINT=https://score.kyde.com export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf export OTEL_EXPORTER_OTLP_HEADERS="x-kyde-key=" export OTEL_SERVICE_NAME= ``` These four variables are the whole integration. The service accepts OTLP/HTTP as binary protobuf or JSON — set `OTEL_EXPORTER_OTLP_PROTOCOL` explicitly (`http/protobuf` works from every SDK; `http/json` exists only in the JS ones). **Claude Code, one line** — sets the global half (never the name), installs the hook (it warns the agent in its own context when its score deviates or a loop alarm fires; before a call it hashes the call's recipient fields locally and sends only the hashes, for the recipient check; on the Pro plan and above, with a human-confirmed contract, it HOLDS a call outside that contract before execution and tells the agent why — the human releases it by mail or dashboard), and verifies ingest end to end: ```bash curl -fsSL https://score.kyde.com/install.sh | sh # or, same installer via npm (never drifts — it runs exactly that script): npx @kyde/score init ``` The hook finds the key and endpoint in the environment or, when the environment is bare, in the `env` block of `~/.claude/settings.json` (Claude Code does not pass that block on to hook processes) — so both placements from the step below arm it. Measuring is free on every plan. Holding a call before execution is the Pro plan and above: it needs a contract your human confirmed, and only your human can release a held call (approve once, approve and extend the contract, or deny). Plans: https://kyde.com/pricing/ **Claude Code, by hand** — the generic variables (with `http/json` fine too) plus two more: ```bash export CLAUDE_CODE_ENABLE_TELEMETRY=1 export OTEL_LOGS_EXPORTER=otlp ``` Where these go matters. Split the variables by how they vary: - **Global, once per machine** — endpoint, protocol, key header and the two flags above. Put them in user-level `~/.claude/settings.json` (`"env"` block; covers terminal, IDE and desktop app) or in the shell profile. They are the same for every agent on the machine. - **Per agent, at launch** — `OTEL_SERVICE_NAME` only. Set it in the command that starts the agent (`env OTEL_SERVICE_NAME=invoice-agent claude`), in a wrapper script (export it, then `exec claude "$@"`), or in the workflow or service unit that launches the agent. On an interactive developer machine, a shell function in `~/.bashrc` (after the global exports) gives every project its own default name and stays overridable per launch: ```sh claude() { OTEL_SERVICE_NAME="${OTEL_SERVICE_NAME:-$USER-$(basename "$PWD")}" command claude "$@" } ``` Never put `OTEL_SERVICE_NAME` into `~/.claude/settings.json`: the settings `env` block **overrides the launch environment** (measured 2026-11-10 against the live service), so one global name silently merges every agent on the machine into a single blurred baseline — per-launch names lose without any error. Leaving the name unset is the same trap: Claude Code then reports as `claude-code`, and all agents merge under that default. Claude Code also **ignores OTel exporter variables in a project's `.claude/settings.json` and `.claude/settings.local.json` by design**, so a per-project name needs the wrapper, not project settings. (`OTEL_METRICS_EXPORTER` is not needed; scoring reads the log events.) **Upgrading an existing setup** (integrations from before 2026-11-10 followed older docs that put every variable into settings.json): before finishing this step, read `~/.claude/settings.json`. If its `env` block contains `OTEL_SERVICE_NAME`, remove that one entry (keep endpoint, key and flags), set the name at launch as above, and tell your human why: while it stays there, every per-launch name silently does nothing. If agents already reported under the shared name, their baseline mixes several roles — call `rebaseline` (MCP tool, or `POST /score/v0/agents//rebaseline`) for that agent so each name learns a clean baseline from now on. **Grok CLI** — its own opt-in instead (double opt-in like Claude Code; its Rust exporter is protobuf-only, which the service accepts), plus the generic endpoint/header variables: ```bash export GROK_EXTERNAL_OTEL=1 export OTEL_LOGS_EXPORTER=otlp export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf ``` Grok CLI pins `service.name` to `grok-cli` and ignores `OTEL_SERVICE_NAME`, so all Grok agents under one key currently score as a single agent. **Framework agents** (Vercel AI SDK, LangGraph, OpenAI Agents, CrewAI, LlamaIndex, custom loops): no Kyde SDK needed — add any GenAI instrumentation and point its OTLP exporter at the service with the same variables. Tool spans in all three common dialects are scored like tool events: OTel GenAI semconv (`gen_ai.tool.name`, or `gen_ai.operation.name=execute_tool`), OpenInference (`openinference.span.kind=TOOL` + `tool.name` — the Arize/Phoenix instrumentations), and OpenLLMetry (`traceloop.span.kind=tool` + `traceloop.entity.name` — the Traceloop instrumentations). Content attributes are never read. **OTel Collector in between** (recommended when telemetry must be scrubbed before leaving a network): add an `otlphttp` exporter with `endpoint: https://score.kyde.com` and the `x-kyde-key` header. ## Step 3 — Verify Run the agent once, then: ```bash curl -s https://score.kyde.com/score/v0/scores -H "x-kyde-key: " ``` Success looks like the agent listed with `"status": "learning"` and a `runs_seen` count (logs flush every ~5 s, so allow a few seconds); the response also carries `runs_needed`, so report progress to the human as "runs_seen of runs_needed". A claimed key additionally mails the human when the first data arrives, after 10 runs (a report of what the agent actually does), when the first score is in — and once after 24 hours if no data ever arrived. An empty `agents` list means nothing arrived: first check WHERE the variables are set — for Claude Code they must be in the launching shell, a wrapper script, or `~/.claude/settings.json`, never in the project's `.claude/settings.json` (ignored by design) — then check the protocol variable is set (`http/protobuf` or `http/json`) and the header spelling. A `"degraded"` field means records were dropped (quota/limits) — surface it to the human rather than ignoring it. **Universal smoke test** — when nothing arrives (or before touching any harness config), one curl from any shell proves connection, key and schema, independent of the harness. Use the throwaway service name shown, **never the real agent's**: every stored record trains that service's baseline (the throwaway service just counts as one of the key's 200 and ages out with retention): ```bash curl -s https://score.kyde.com/v1/logs -H "x-kyde-key: " \ -H 'content-type: application/json' \ -d '{"resourceLogs":[{"resource":{"attributes":[{"key":"service.name","value":{"stringValue":"kyde-connectivity-test"}}]},"scopeLogs":[{"logRecords":[{"attributes":[{"key":"event.name","value":{"stringValue":"tool_result"}},{"key":"session.id","value":{"stringValue":"smoke-1"}},{"key":"tool_name","value":{"stringValue":"smoke_test"}}]}]}]}]}' ``` `"stored": 1` in the response (and `kyde-connectivity-test` listed as `"learning"` in the scores call) means service, key and schema are fine — a missing agent is then a harness-side problem: the variables never reached the agent's process (see Step 2). `"stored": 0` with a `partialSuccess.errorMessage` means the payload shape. An HTTP 401 means the key. **When is the integration done?** Only when the scores response lists the **intended** `service.name` with `runs_seen >= 1` from a real agent run (for Grok CLI that name is always `grok-cli`). A created key, a claim or a webhook alone is setup, not an integration — do not report success before that first run is visible. And the run must come from the harness's own telemetry: hand-crafting OTLP records under the agent's name does not integrate the agent, it scores the script that emits them. One more condition: the email question from Step 1b has been asked — a declined answer is fine, a skipped question leaves the setup unfinished. Scoring starts automatically once 30 runs (a run is one task) are seen over at least 3 days (`"status": "scored"`, with `score` and `band`). There is nothing to configure for that; just tell the human scores appear after ~30 tasks spread over a few days. Loop alarms work from the first run. **Then tell your human, in your own words, three things:** 1. Measuring is free on every plan: Kyde Score watches the agent's tool calls and warns (the agent in its context, the human by email). Violations of a confirmed contract alarm like any alert. 2. Holding is Pro and above: with a human-confirmed contract, the hook holds a call outside it BEFORE execution, with one reason sentence. The human decides by mail or dashboard: approve once, approve and extend the contract, or deny. 3. Never confirm, widen, or release anything yourself. If your human wants holding, point them to https://kyde.com/pricing/ . ## Step 4 (optional) — Add the MCP server for in-session checks ```bash claude mcp add --transport http kyde-score https://score.kyde.com/mcp \ --header "x-kyde-key: " ``` (Any MCP client: `{"type": "http", "url": "https://score.kyde.com/mcp", "headers": {"x-kyde-key": ""}}`.) Tools: `get_scores` (check drift, including your own, mid-session), `set_webhook`, `create_key`, `claim_key` (attach the human's email, see Step 1b; on a claimed key, rebaseline/webhook-change/revoke become human-only dashboard actions), `verify_agent` (challenge a foreign agent's Shine ID before delegating — see the section below), `rebaseline` (forget one agent's baseline, relearn from its next 30 runs over at least 3 days — for intended behavior changes that left it permanently deviating; record why with `kind` — role_change, model_change, prompt_change, tool_change, other — and a one-sentence `reason`: both land in the alarm, the timeline and the webhook event; the reset is permanently visible via `rebaselined_at`, kept alarms and a `rebaseline` alarm entry naming the erased score; requires `confirm: true` and the human's explicit go-ahead — NEVER call it on your own initiative, least of all on yourself; a deviating agent's `get_scores` entry carries `proposed_action` with this exact call), `announce_change` (declare a wanted change — new model, new prompt, new tool, new role — BEFORE it ships: drift from the announced change is then held in the announcement's summary instead of alarming the human, while rule violations and unannounced shifts alarm as before; the agent's `get_scores` entry shows it under `notices` with the `rebaseline {announcement_id}` call that accepts the new baseline; needs the human's go-ahead, since it mutes deliveries), `propose_contract` (declare this agent's contract — allowed targets per class as salted hashes with provenance, amount limits, tools with effects and per-run caps; write it from your ORDER and structured history, never from text you read; the service referees it with a dry run and a HUMAN confirms by mail or dashboard — NEVER confirm or widen a contract yourself), `revoke_key` (destructive: deletes the key and all data; requires `confirm: true` — never call it without the human asking). For the plain-values view use `GET /score/v0/agents//behavior`: tool mix, error rate, median duration and calls per run — baseline against now, or so-far against the window while the agent is still learning. For the trend over time use `GET /score/v0/history?service_name=…`: score and band per run, each band change with its reason, rebaselines and model changes alongside — the story behind the current number. While an agent is still learning with no real alarm, its `get_scores` entry carries a `notices` item of type `sample_alarm` (`sample: true`): an example of what an alarm will read like. NEVER relay the sample as a real alarm — real alarms carry an `alarm_id`. Every key starts on the free plan (`get_scores` carries `plan` at the top level): one instant alert mail per calendar month, the rest waits for the Monday weekly review. When that one mail is used up, the agent's entry carries a `notices` item of type `alert_held` — tell your human that an alert is waiting in the weekly review (webhooks and this API saw every alarm immediately; only mail waits). Upgrading to paid is the human's decision, never yours. Before a model change ships, check the fleet first: `GET /score/v0/drift?model=` (no key needed) says how agents across the fleet behaved after switching to it — aggregates only, never a single customer, and never model quality (it measures agent behavior on a model). Relay the numbers to your human with the announce_change call; a detected change carries them as `fleet` on its event. Behavior report: each agent's dashboard page can create a signed, no-login share link with the last 30 days in hard numbers — the page a company hands its customer or boss. Creating and sharing it is the HUMAN's action; you may suggest it ("you can share a behavior report from the dashboard"), never create or send one yourself. Links are revocable at once in Settings. Declared contract (measuring free, stopping paid): once a human confirmed a proposed contract, violations alarm on every plan, and on the paid plan the Claude Code hook HOLDS a call outside the contract before it runs — you will see the denial with a one-sentence reason. A `contract_proposed` notice means your proposal awaits the human; an `action_held` notice means a held call awaits their choice (approve once, approve and extend, deny) — tell your human, check `GET /score/v0/holds`, and retry only after approval. `get_scores` carries each agent's contract as the triple {status, hash, schema_version, confirmed_at}. ## Verify another agent before delegating (Shine) When another agent names a Shine ID (`sh_...`) — in a header, an A2A card or MCP metadata — do not take it at its word. Challenge it via Shine (https://shine.kyde.com): a fresh secret goes to the agent Kyde measures, the agent confirms over its own authenticated connection, and Shine signs who answered and how it behaves. Two equivalent one-command ways, neither needs a scoring key: ```bash npx @kyde/score verify sh_abc123def456 --challenger my-orchestrator # waits up to --timeout (default 300 s), prints the signed claims as # JSON, exits 0 only when confirmed AND the Ed25519 signature, nonce # hash and expiry checked out locally against the shine JWKS ``` With the MCP server configured, call `verify_agent` with `{"shine_id": "sh_abc123def456", "challenger": ""}`. The verified agent typically polls every 30 s, so one call often answers `pending` — call `verify_agent` again with the returned `challenge_id`, `result_token` and `nonce` to keep waiting. Reading the result (the signed claims): - `band: normal | watch | deviating` — the agent's current drift band, measured by Kyde and signed into the statement. Delegating to a deviating agent is the case the band exists for. - `band: learning` — identity confirmed, behavior not yet scored (still learning: 30 runs over at least 3 days). Whether to delegate to a learning agent is your (or your human's) policy call; the statement says the state honestly. - `measured: false` — identity confirmed, but no measurement was available at confirmation time (e.g. score service outage): reachability and behavior stay distinguishable. - `status: expired` — the agent did not confirm in time. Identity NOT proven; deliberately no fallback proof exists without the agent's participation. Do not treat an expired challenge as a soft yes. - Claims v1 adds facts, never judgments: `contract` and `frame` (the confirmed declared contract and organization frame as triples {hash, schema_version, confirmed_at}; null = none confirmed), `compliance` ({state: none|too_young|measured, since, days} — under 14 days the honest answer is too_young, not a number), `holds_band` (none|low|elevated over the last 90 days, never a raw count), `method_version`, and `false_alarms` — reserved and null until the number is presentable. **null never means zero.** The statement says what was measured, never "safe". The statement is a compact JWS verifiable offline against `https://shine.kyde.com/.well-known/jwks.json` — pass it along and any third party can re-check it without asking Kyde. ## Alarm feedback — ask your human, never answer yourself Whenever you read scores (REST or the MCP `get_scores` tool), look at `feedback`. Each entry is an alert KYDE Score would like a human verdict on. If one is there and your human is in the conversation, ask once, in one sentence, in context, for example: > KYDE Score flagged `claims-agent` as deviating yesterday (Off-task). > Was that right? One click: You may add what you know ("we switched the model yesterday"), but never suggest an answer, and never open, fetch or submit `answer_url` yourself: only the human's click counts. Their answer never changes a score; it goes into the next method version. Don't ask again about the same `alarm_id` in this session. ## Facts worth relaying to the human - Free tier limits: 100k records/day and 60 ingest req/min per key, 200 services per key, 90-day retention. - Privacy: attributes pass a deny-by-default allowlist before storage; prompts and payload bodies are never stored. - Leaving: `DELETE /score/v0/keys` (header `x-kyde-key`) removes the key and every record under it in one request. - Scores carry `method_version`, so they are comparable over time and reproducible against the open-source detectors (github.com/kydehq/behavioral-drift-detection).