Agent Integration¶
Primr can be operated from agent hosts through MCP, A2A, packaged skills, and documented host configuration snippets. There are two distinct agent workflows:
primr prepplus theprimr-zeroskill performs hard-zero collection and uses an existing host plan for research and synthesis.- MCP, A2A, or CLI launches the provider-backed Primr pipeline after an estimate and explicit spend approval.
Do not describe the first path as an API-key substitute inside Primr. The host owns its research and reasoning; Primr owns deterministic evidence collection and the handoff artifacts.
Default Routing In An Agent Host¶
Keep the user-facing request clean:
Inside an agent host, that bare request defaults to Primr Zero. The host uses
the primr-zero skill, runs primr prep internally when it has a shell, and
continues through research, writing, QA, and artifact handoff without asking
the user to choose a Primr mode. This also applies to requests such as "run
Primr" or "build a full Primr dossier" when they do not contain explicit paid
intent.
Use the provider-backed pipeline only when the user explicitly asks for paid, metered, provider-backed, or premium Primr; supplies a dollar budget; asks to use provider API keys; or gives provider-only CLI modifiers. The presence of a configured key is not spend consent. Choose this route before choosing MCP or CLI transport so an available MCP research tool cannot accidentally turn a bare request into a billable run.
This routing is guidance for agent conversations. It does not change the
provider-backed behavior of primr "Company" https://company.example when a
human runs it directly in a terminal.
Operating Rules¶
For authenticated remote MCP/A2A clients, QA and existing-artifact generation
require both research and report authority. Only artifacts of the currently
retained owned job can be reused. Skill-pack directory reuse must stay in its
dedicated job directory, including any JD or saved-plan inputs. Unknown and
historical server files need a local operator workflow. Omit a standalone
skill-pack destination to receive an isolated server-selected folder; explicit
remote destinations must belong to the caller's current job. These restrictions
apply in addition to the normal estimate and approval gates.
Any explicitly billable agent-driven Primr run must follow this lifecycle:
- Estimate the exact run.
- Show the cost, time, mode, platform, and strategy choice.
- Get explicit approval from the user.
- Launch the job.
- Monitor asynchronously.
- Read the output artifact before summarizing.
For CLI transport, estimate with the exact command plus --dry-run. After the
user approves that quote, replace --dry-run with --skip-confirm when
launching through automation or a background job. Do not depend on an
interactive prompt or pipe y into the process. Without --skip-confirm, a
noninteractive CLI invocation returns an approval-required refusal and starts
no provider work. The experimental primr orchestrate command uses an approved
--max-cost <usd> ceiling as its noninteractive approval token instead.
Do not start billable work from a vague request like "research ExampleCo" or a bare Primr company-and-URL request. Use Primr Zero for a named Primr request and normal web research for an unnamed quick brief. Reserve provider-backed Primr for explicit paid intent.
For hard-zero collection:
- Run
primr prep "Company" https://company.example --dry-runinternally and verify that it reports$0.00and zero model calls. - Explain that collection costs
$0.00in model API spend but performs public network requests. - Run
primr prepwithout a spend-approval gate. - Read
prep_manifest.json,source_index.json,research_packet.md, andHOST_WORKFLOW.md. - Use
primr-zeroin the current host to close external gaps and write the dossier inside the prep bundle without silently switching to API billing. - Run deterministic report QA when available, then confirm the Markdown as
artifact_role: primary_reportinside that prep bundle through the local JSON inventory before passing its exact path to a requested downstream workflow. - Render each finished report to DOCX/TXT with
primr render <file>.md(zero cost, no model calls) and host-write the AI Strategy from the same evidence, so the Zero output set (Strategic Overview + AI Strategy, each.mdand.docx) matches a paid run.
primr prep is already noninteractive. Never pipe y into it and never add
--skip-confirm; either action obscures the boundary between free collection
and an approved provider-backed launch. If prep unexpectedly presents a spend
prompt, stop and correct the selected command instead of answering it.
Treat prep exit code 130 as an intentional interruption, not a completed or failed bundle. Inspect the configured output root before retrying because publication may already have completed at the interruption boundary. If a portable skill installation returns 130, inspect its destination before use or retry because installation updates files individually.
If the host lacks a shell, cannot launch Primr, or cannot install it with user approval, use the skill's host-native research fallback. Installation is not a prerequisite for useful Zero-path research. Disclose that Primr DNS, adaptive scraping, ATS adapters, trace artifacts, and local QA were unavailable. If the host cannot search the web, request a prep bundle or source files rather than writing from model memory.
See Zero-Cost and Host-Assisted Research for the complete contract and failure behavior.
MCP Server¶
The Model Context Protocol server is the main programmatic surface:
Use stdio for local desktop agent hosts. Use HTTP only when you need a networked service with JWT auth. Both transports require estimate-bound cost caps and approval tokens by default.
HTTP validates Host and Origin through the MCP SDK. Local loopback aliases
work by default. When binding to 0.0.0.0 or :: behind a TLS ingress, set
MCP_ALLOWED_HOSTS to the exact public hostname, with a port if clients send
one (for example mcp.example.com). A missing allowlist stops wildcard
listeners at startup. Set MCP_ALLOWED_ORIGINS to any trusted browser origins
such as https://agent.example.com. Both settings accept comma-separated exact
values; wildcards are rejected. Native clients may omit Origin. Reverse proxies
must preserve an allowed Host header; forwarded headers never grant trust.
The bundled Azure template sets the app's exact ingress hostname automatically.
Important MCP concepts:
estimate_runproduces a structured cost and time estimate.research_companylaunches approved research jobs.- Job resources expose status and output paths.
primr://output/artifacts/by_job/{job_id}exposes compact artifact metadata for one owned job without report body content, including physical types and semantic roles for primary reports, strategy modules, diagnostics, and run metadata. Use it before requesting full report previews or reading files directly.primr://output/qa_summary/by_job/{job_id}exposes compact QA score/status and count metadata for attached QA JSON sidecars and text QA reports without detailed QA or report body content.primr://output/usage_summary/by_job/{job_id}exposes compact cost, timing, approval, execution, and artifact-count metadata from owned-job run manifests without full manifest content. Completed research jobs report run-scoped actual spend. The field remains null for cancellation and failures whose spend cannot be measured; a failed Premium job with a durable paid partial can report reconciled spend. Estimates and ceilings are never actual spend.primr://output/source_summary/by_job/{job_id}exposes compact citation/source appendix counts, domains, missing citations, duplicate URL counts, and source URLs without report body content.primr://output/trace_summary/by_job/{job_id}exposes compact scrape trace counts, tier health, latency, block, HTTP status, and validation metadata without URLs, raw trace entries, or page content.primr://output/verification_summary/by_job/{job_id}exposes compact claim verification trust score, claim counts, status counts, first-party downgrade counts, and source-reference counts without raw claims, source URLs, search queries, explanations, or report body content.primr://output/calibration_summary/by_job/{job_id}exposes compact label-calibration per-label counts, inference source-copy counts, evidence-review count buckets, judge provenance, and judge-agreement metadata without raw claims, source URLs, evidence reviews, rationales, or report body content.- Every MCP transport requires server-side cost caps and estimate-bound approval tokens by default.
- Audit resources record MCP tool calls, MCP resource reads, and A2A skill calls with hashed payloads and normalized resource kinds for admin review.
- MCP/A2A doctor and the recent-audit resource expose only body-free audit-sink
state (
not_observed,ok, ordegraded) and bounded-reader metadata; no path, event body, URL, caller id, or exception message is returned. - A first health read reports overall
degradedwhile audit persistence isnot_observed. Subsequent health reads can reporthealthyonly after the shared MCP/A2A audit sink has been observed successfully.
Full tool and resource details are in MCP and A2A API.
A2A Server¶
A2A support is optional:
Use unauthenticated A2A only on loopback for local development. Networked
deployments should use auth and the same cost controls as MCP HTTP mode. A2A
bearer tokens use the same scope vocabulary as MCP: read can estimate, check
job status, and run system health; research is required to start research,
run QA, or cancel an A2A task. Legacy write tokens still satisfy
research-scope A2A calls for compatibility. Authenticated A2A jobs are owned
by the bearer token client_id; unauthenticated loopback jobs keep the legacy
local a2a owner id.
A2A skill invocations and task cancellation append privacy-preserving audit
events to the shared audit log. Events include hashed message/result payloads,
hashed caller ids, granted scopes, outcome, duration, and job id when present,
but not raw message text, task ids, URLs, report paths, raw results, or caller
ids.
Host Configuration¶
Portable Agent Plugins v1 package¶
agent-plugin/ is an experimental distribution artifact
for the Agent Plugins v1.0.0 Working Draft. It contains the portable root
plugin.json, immediate skills/primr and skills/primr-zero children, and a
root mcp.json that starts primr mcp over stdio.
The portable specification standardizes Agent Skills and MCP discovery. It
does not standardize installation, permissions, user interface, or every
client extension. Check the specification's compatible-client registry and
the selected client's installation guide before claiming support. Claude Code
is not currently claimed through this portable artifact; use the existing
claude-code/ package for Claude-specific installation.
Agent Plugins v1 defines skills and MCP servers as separate portable component
types, and clients can support them incrementally. Primr's mcp.json uses the
bare executable token primr, so the MCP component works only when Primr is
installed and discoverable through the client's executable search rules. If
that server cannot start, the skills can still load and provide the host-native
Primr Zero fallback. The portable operator skill omits argument-hint and the
experimental allowed-tools metadata because their support or semantics vary
between hosts.
The package is deterministically generated from the canonical skill sources:
Installing or loading it performs no research and authorizes no spend. The same Primr Zero routing and provider-backed estimate/approval rules apply after installation.
See the Agent Plugins specification and compatible clients.
Host-specific configuration¶
Per-host snippets live under clients/:
- Codex and other repository Agent Skills hosts
- Cursor
- Windsurf
- VS Code and Copilot
- Kiro
- Claude Desktop
The common launch shape is:
Agent hosts differ in where they store MCP configuration and how they load local guidance. Use the host-specific snippet when available instead of hand-writing paths.
Packaged Skills and Agent Guidance¶
Primr ships four related guidance surfaces:
clients/primr-operator.md, the operator guide to copy into a workspace asAGENTS.mdfor tools that auto-load the open agents.md format. (The repository rootAGENTS.mdis the development contract.).agents/skills/primr-zero/as the canonical portable hard-zero skill.claude-code/plugin files, including a checkedprimr-zeromirror, for the Claude Code plugin workflow.- Generated skill packs from
primr skills, which are company-specific Agent Skills artifacts for downstream work.
The full primr operating guidance remains thin over the CLI and MCP server.
primr-zero is intentionally different: it defines a host-native synthesis
workflow over a versioned Primr evidence packet. Generated skill packs are
company-specific downstream artifacts and are not Primr operating skills.
Skill-Only Install¶
When a host supports local skill files but not the plugin flow, install the entire desired skill directory, including its references.
For hard-zero research, use the canonical package:
Source: .agents/skills/primr-zero/
Codex personal install: ~/.agents/skills/primr-zero/
Claude Code personal install: ~/.claude/skills/primr-zero/
Claude Code in this checkout: .claude/skills/primr-zero/
Repository skill install: <workspace>/.agents/skills/primr-zero/
From an installed wheel, use
primr prep --install-skill <directory> --dry-run to preview the requested
destination without network access or file writes, then remove --dry-run to
copy the complete skill and references into that explicit destination.
Claude Code discovers the checked .claude/skills/primr/ and
.claude/skills/primr-zero/ project skills in this source checkout. Users may
also copy the plugin mirror from claude-code/skills/primr-zero/ or install the
Primr plugin. Hosts without shell access can consume a prep bundle through
their official file-import or research UI and use HOST_WORKFLOW.md as the
task contract.
For provider-backed Primr guidance, install the existing full-pipeline skill:
Fetch https://raw.githubusercontent.com/pueo-labs/primr/main/claude-code/skills/primr/SKILL.md
Save it to the host's local skills directory as primr/SKILL.md
Fetch the files under claude-code/skills/primr/references/
Save them under primr/references/
Run primr init before launching billable work
Use the host's documented local skill directory. Do not let an installer overwrite unrelated user configuration.
Credential Boundaries¶
Primr separates credential types:
- Provider API keys, such as
XAI_API_KEY,GEMINI_API_KEY,OPENAI_API_KEY, andANTHROPIC_API_KEY, pay for direct model calls inside Primr. - Agent-host credentials operate the surrounding host and do not automatically replace provider API keys.
primr-zerokeeps synthesis inside that surrounding host and never passes its credentials into Primr.- Primr has an unpromoted Codex runner for
fast.source_relevance. It becomes eligible only for an explicitly acknowledged, single-company hybrid experiment. Codex authentication can be plan-backed or API-key billed, Primr cannot prove which applies, and unknown host charges remain outside Primr's estimate and budget. - Local and gateway endpoints are first-class paths when configured and measured, but full local report profiles remain roadmap work.
Do not paste browser-session cookies, personal web app tokens, or unofficial subscription proxy credentials into Primr.
See API Key Setup for the full credential model.
Async Monitoring¶
Primr runs can take 35-120 minutes. Good agent integrations avoid tight polling.
Preferred patterns:
- Launch in the background and report completion. An approved provider-backed
CLI command must include
--skip-confirm. - Stream sparse phase markers from logs.
- Do one early sanity check after the first few minutes.
- On the next user turn, read job state before saying anything about completion.
A job is complete only when the job state reports completion and the expected report artifact exists.
For agent handoff, read primr://output/artifacts/by_job/{job_id} first to
confirm which artifacts exist, their classifications, semantic roles, sizes,
timestamps, and hashes. Select the Markdown primary_report and only relevant
strategy_module paths for downstream document workflows. Request
primr://output/by_job/{job_id} only when the agent needs a report preview for
summarization. If QA artifacts are attached, read
primr://output/qa_summary/by_job/{job_id} before loading any QA body text.
Read primr://output/usage_summary/by_job/{job_id} when the handoff needs
run cost, timing, approval, execution, or artifact-count metadata.
Read primr://output/source_summary/by_job/{job_id} when the handoff needs
citation/source appendix health without report body content.
Read primr://output/trace_summary/by_job/{job_id} when the handoff needs
scrape trace health without URLs, raw trace entries, or page content.
Read primr://output/verification_summary/by_job/{job_id} when the handoff
needs claim verification trust and count metadata without raw claims, source
URLs, search queries, explanations, or report body content.
Read primr://output/calibration_summary/by_job/{job_id} when the handoff
needs label-calibration counts, inference source-copy counts, or
judge-agreement metadata without raw claims, source URLs, evidence reviews,
rationales, or report body content.
Resource reads and A2A skill calls are audit-logged without raw URI query
values, raw message text, raw result bodies, or caller ids, so prefer compact
resources before requesting report previews or files.