AI Agents Workflow for Library Integrators#

This page defines the minimum contract so AI agents can safely consume SMonitor signals from your host library without breaking human workflows.

Why this matters#

If your team uses agents for triage, QA, or patch proposals, the agent needs:

  • stable machine-readable identifiers (code, signal),

  • stable grouping/correlation identifiers (fingerprint, run_id, session_id, optional correlation_id),

  • deterministic structure in events,

  • reproducible artifacts (bundles),

  • explicit safety limits.

Without this, agent output is noisy and difficult to trust.

Required operational contract in the host library#

  1. Keep code values stable once published.

  2. Keep signal names stable and descriptive.

  3. Emit actionable hint for human users in user profile.

  4. Ensure agent profile keeps compact, structured output.

  5. Enable local bundle export in support flows.

  6. Keep strict validation enabled in CI:

    • strict_signals=True

    • strict_schema=True

  7. Preserve both explicit machine and handoff views:

    • normalized

    • human_summary

CI pattern for agent-readiness#

Add these checks in CI:

  • tests run with strict signal/schema settings,

  • a smoke test that exports a bundle,

  • snapshot/assertions for representative emitted events.

This ensures agents always receive a stable data contract.

Copy-paste checklist for onboarding a new agent#

Use this checklist in any new host-library repo:

  • read standards/SMONITOR_GUIDE.md first;

  • verify _smonitor.py + mylib/_private/smonitor/catalog.py are present;

  • avoid adding hardcoded warning/error strings outside catalog;

  • validate representative events under profile="agent";

  • validate representative events include fingerprint, normalized, and human_summary;

  • confirm bundle export works in CI smoke path;

  • confirm smonitor compare ... gives meaningful diffs for representative runs;

  • include test evidence before proposing fixes.

Guardrails for autonomous tooling#

  • Never auto-merge fixes produced from agent triage.

  • Require human review for any patch suggested from SMonitor output.

  • Prefer deterministic triage keys (code, fingerprint) before free-text matching.

  • Redact sensitive fields before sharing bundles externally.

Practical flow#

  1. User or CI run emits SMonitor events.

  2. Bundle is exported locally.

  3. Agent inspects triage, normalized, and human_summary.

  4. If needed, agent compares against a previous bundle.

  5. Agent proposes diagnosis.

  6. Human reviews diagnosis and proposed patch.

  7. Fix is validated with tests and strict checks.