Safe trace sharing

Redact and verify traces before attaching them to PRs, issues, or design-partner threads.

Docs site: https://agentinspect.vercel.app/docs/safe-sharing/

AgentInspect traces, log-ingest outputs, and exports are local files. They may still contain sensitive metadata that you attached manually, collected from logs, or included through optional preview settings. Use this checklist before sharing an artifact in a GitHub issue, Discussion, PR, support thread, or public post.

This guide is practical sharing guidance, not a guarantee that any artifact is safe to publish. Redaction profiles are best-effort transformation, not compliance-grade DLP or a safety certification. Always finish with verify-safe before sharing.

Built-in profiles redact high-confidence credential forms (provider keys, JWTs, bearer tokens, and bounded token= / api_key= / internal_token= style key/value secrets). Broad or context-sensitive findings—such as private filesystem paths—may still appear under verify-safe and as residual status after redact. Org-specific patterns can use a local CLI --policy JSON file (extraKeys plus bounded literal/prefix patterns; no user regex) or programmatic custom detectors.

strict is a stricter rule set (more keys), not a promise that every input produces bytes different from share.

Quick presets (v1.3.0+)

• --redaction-profile share — PRs, GitHub issues, Slack/email threads inside your org. Redacts correlation IDs, customer/user IDs, and common contact fields.
• --redaction-profile strict — external sharing or public posts. Also redacts prompt/output/message-like metadata keys.
• Default (local) — same as before; still review before sharing.

npx agent-inspect export <run-id> --format markdown --redaction-profile share
npx agent-inspect export <run-id> --format html --redaction-profile strict
npx agent-inspect redact trace.jsonl --profile share --json

Original trace files under .agent-inspect-runs/ are not modified by export or redact copy workflows.

Default redaction before disk

Manual traces redact common sensitive keys before disk by default. Pass redact: false only when you accept the risk locally.

Before sharing

When a maintainer or support responder needs reproducible evidence, follow the safe support reproduction workflow to create and review a minimized Evidence bundle. Do not attach a raw trace directory.

For reviewer-reproducible trajectory checks (6.28+), prefer Evidence that includes contract.resolved.json and a matching contract digest in evidence.json / check-results.json. That lets a reviewer see the resolved TraceContract or check preset that was evaluated. Custom/programmatic rules remain partial — JSON cannot replay executable rule functions. Contract binding verifies packaged digests only; it does not prove producer identity, trusted time, or that the artifact is safe to publish. See EVIDENCE-FORMAT.md.

• Use --redaction-profile share for PR/issue attachments; use strict when sharing outside your team.
• Review the exported file — profiles do not detect all sensitive data.
• Treat traces written with redact: false as sensitive. Review every event before sharing them outside your team.
• Inspect manual metadata passed to inspectRun(), step(), step.tool(), step.llm(), or observe().
• Inspect log-derived fields from logs / tail ingest configs, including custom run-id, event, parent, timestamp, and attribute mappings.
• Avoid posting raw prompts, completions, tool inputs, or tool outputs in public threads unless the content is approved for public disclosure.
• For cross-system correlation, retain a bounded identifier instead of copying the external record or payload. Follow External reference metadata, and expect share / strict profiles to redact the named correlation fields.
• share and strict rewrite http(s) URLs rather than dropping them: userinfo and credential-looking query or fragment params are replaced, identifier-like path segments become [id], and scheme, host and path stay, so a retry on the same page is still recognizable. The same profiles also strip userinfo from common connection URIs (postgres / postgresql, mysql / mariadb, mongodb / mongodb+srv, redis / rediss, amqp / amqps) while keeping scheme, host, port, and database/queue path: postgres://user:secret@db.example.com:5432/app_db becomes postgres://db.example.com:5432/app_db. When a connection authority cannot be parsed as a standard URL (for example multihost MongoDB lists), userinfo is still stripped or the whole value is withheld so credentials never remain in a SAFE share. Incomplete placeholders such as token=[REDACTED]/… are treated as residual secrets in free text. Other schemes still need a manual check.
• Prefer Markdown export for issue or PR sharing when a summarized tree is enough.

Remove or replace sensitive values

Search the artifact for:

• API keys, bearer tokens, cookies, session IDs, JWTs, OAuth codes, and webhook secrets
• passwords, private keys, certificates, signing secrets, and database URLs
• email addresses, phone numbers, physical addresses, usernames, and customer IDs
• internal hostnames, service URLs, ticket IDs, order IDs, account IDs, and tenant IDs
• proprietary prompts, system instructions, model outputs, retrieved documents, and tool responses
• file paths that expose user names, project names, or internal directory layouts

Replace sensitive data with clear placeholders such as example.test, user@example.test, CUSTOMER_ID_REDACTED, or TOKEN_REDACTED.

Export and ingest-specific checks

• Markdown / HTML exports: review rendered text and copied snippets, not only the source trace.
• Eval JSON / Markdown: review failed-rule messages, expected/actual summaries, source IDs, and evidence paths before attaching them to PRs or issues.
• Redacted copies from agent-inspect redact: review the output file itself; findings show detector/path/action evidence but do not certify full safety.
• OpenInference / OTLP JSON exports: check attributes, span names, events, and resource metadata.
• Structured log ingest configs: confirm mapped keys do not pull in full request bodies, headers, raw prompts, or unbounded output fields.
• Framework adapter traces (ai-sdk, openai-agents, langchain): keep capture: "metadata-only" for shareable examples; review capture: "preview" traces carefully because previews can include prompt or output fragments. Preview redaction is key-based and bounded, not a sanitization guarantee.
• Third-party adapter packages: follow the Adapter SDK privacy checklist before sharing adapter traces, examples, or registry submissions.

When to use each profile

Guardrails and circuits (v2.5 planning)

• Optional @agent-inspect/guardrails and @agent-inspect/circuit packages evaluate local text/JSON/trace patterns deterministically.
• They reuse @agent-inspect/redact for PII-style findings where applicable — same best-effort limits as redaction profiles.
• They are not compliance tools and do not guarantee an artifact is safe to publish.
• Circuits detect repetition, retries, and width in traces or explicit counters; they do not stop runaway agents unless your code enforces results.

What this guide does not claim

• Redaction profiles are not GDPR/HIPAA/SOC2 compliance tools.
• Export redaction does not upload anywhere — it only shapes a local copy.
• No automated scan guarantees an artifact is safe to publish.

Final review

• Open the exact file you plan to share and search for common sensitive strings: token, secret, authorization, cookie, password, email, apiKey, key, jwt, bearer.
• Confirm any screenshots do not show terminal history, environment variables, browser account data, or private repository names.
• Share the smallest useful artifact: a summary, selected excerpt, or minimized synthetic reproduction is better than a full trace.
• If the artifact includes production or customer data, do not share it publicly. Use a private security or support channel.

See SECURITY.md for the security policy and redaction expectations.