agentminds 0.5.0

AgentMinds Python SDK — cross-site collective intelligence for production AI agents. Auto-capture errors + push/pull patterns from the network pool.

agentminds — Python SDK

AgentMinds is a cross-site collective intelligence pool for production AI agents. Every connected site pushes what its agents observed + learned; every site pulls back the patterns its specific stack needs — solved fixes from peer sites, network benchmarks, ranked rules. One pip install, one push, you're in the pool.

This SDK does two things:

1. Auto-capture uncaught exceptions, 5xx responses, and ERROR logs from your Python web app — Sentry-style ergonomics, zero deps.
2. Sync API client for pushing agent reports + pulling personalised recommendations, benchmarks, issues, and patterns from the network pool.

60-second start

pip install agentminds

import agentminds

# A) Runtime exception capture — drop-in Sentry replacement
agentminds.init(dsn="https://[e-mail]/yoursite")

# B) Push an agent's report to the network
agentminds.sync.report(
    api_key="sk_yoursite_xxx",
    site_id="yoursite",
    agent="security",
    metrics={"hsts_present": 1, "csp_present": 1, "ssl_days_remaining": 60},
    learned_patterns=[{
        "pattern": "csp_breaks_inline_react",
        "category": "security",
        "confidence": 0.9,
        "status": "solved",
        "impact": "high",
        "detail": "Strict CSP broke inline React event handlers; added nonce",
    }],
)

# C) Pull what the network has solved for sites like yours
recs   = agentminds.sync.recommendations(api_key="sk_yoursite_xxx", limit=10)
bench  = agentminds.sync.benchmarks(api_key="sk_yoursite_xxx", site_id="yoursite")
role   = agentminds.sync.my_role(api_key="sk_yoursite_xxx")
issues = agentminds.sync.issues(api_key="sk_yoursite_xxx")

Get an API key (and a free baseline scan) by running the interactive onboarder once:

python -m agentminds connect

---

Why this exists (and why "another Sentry" misses the point)

Sentry tells you your error fingerprint. We do that too — but the real value-add is cross-site context. When EmailValidatorError fires on your site, we tell you:

• 14 sites in the pool have hit this exact fingerprint
• 9 of them solved it with the same one-line patch
• Your stack (FastAPI + Pydantic 2 + email-validator 2.x) matches 7/9
• Confidence the patch will work for you: 0.78

That cross-site lift is the moat — it doesn't exist in any single-tenant APM. The runtime SDK shipping crashes is the on-ramp; the sync.* surface is what keeps you here.

See CORE_PURPOSE.md for the full architectural rationale.

---

Runtime auto-capture (Sentry-compatible API)

After init():

• Every uncaught exception (main thread + worker threads) is captured.
• Every logging.error(...) ships as an event.
• Every logging.info/warning(...) becomes a breadcrumb on the next event.

The SDK is a no-op if no DSN is set — safe to leave init() in dev.

FastAPI

from fastapi import FastAPI
import agentminds
from agentminds.integrations.fastapi_app import AgentMindsMiddleware

agentminds.init(dsn=os.environ["AGENTMINDS_DSN"])
app = FastAPI()
app.add_middleware(AgentMindsMiddleware)

Captures uncaught handler exceptions plus any 5xx response. Adds http.method / http.route tags and a request breadcrumb.

Flask

from flask import Flask
import agentminds
from agentminds.integrations.flask_app import init_app

agentminds.init(dsn=os.environ["AGENTMINDS_DSN"])
app = Flask(__name__)
init_app(app)

Manual capture

try:
    risky_thing()
except Exception as e:
    agentminds.capture_exception(e)

agentminds.capture_message("payment retry exceeded", level="warning")
agentminds.set_user({"id": user.id, "email": user.email})
agentminds.set_tag("plan", user.plan)
agentminds.add_breadcrumb(category="db", message="SELECT users WHERE...")

---

Sync API surface — push + pull

All sync.* calls take an api_key (or read $AGENTMINDS_API_KEY), return parsed JSON, and raise agentminds.sync.AgentMindsAPIError on 4xx/5xx. They're stdlib-only — no extra deps beyond what init() already needs.

Push: report what your agent observed + learned

agentminds.sync.report(
    agent="security",
    site_id="yoursite",                     # or $AGENTMINDS_SITE_ID
    api_key="sk_yoursite_xxx",              # or $AGENTMINDS_API_KEY
    severity="warning",
    summary="HSTS missing; 2 mixed-content URLs on /pricing",
    metrics={
        "hsts_present": 0,
        "csp_present": 1,
        "x_frame_options_present": 1,
        "ssl_days_remaining": 60,
        "mixed_content_count": 2,
    },
    warnings=[
        {"severity": "warning", "message": "HSTS header not set"},
        {"severity": "info",    "message": "2 mixed-content resources"},
    ],
    learned_patterns=[{
        "pattern": "fresh_site_baseline_security",
        "category": "security",
        "confidence": 0.9,
        "status": "active",
        "impact": "medium",
        "detail": "Default Render tier headers; needs HSTS pin",
    }],
    project_info={"tech_stack": {"framework": "FastAPI",
                                  "database": "PostgreSQL",
                                  "frontend": "Next.js"}},
)

Server validates against the AgentMinds Reporting Profile (ARP) v1.1 and returns a data-quality grade (A–F). Grade D+ enters the pool.

Canonical metric helpers live in agentminds.metrics — pre-validated emitters for 16 agent types so you don't have to memorise field names.

Pull: what the network knows about your stack

me      = agentminds.sync.me(api_key)              # your site's profile
recs    = agentminds.sync.recommendations(api_key, limit=10)
bench   = agentminds.sync.benchmarks(api_key, site_id)
role    = agentminds.sync.my_role(api_key)         # donor / consumer
pos     = agentminds.sync.network_position(api_key) # vs network p50/p90
issues  = agentminds.sync.issues(api_key, status="open")
actions = agentminds.sync.actions(api_key, status="pending")
patterns= agentminds.sync.patterns(api_key, category="security", limit=20)

Each call is auth-scoped to your site. Cross-site learned_patterns are not browseable — they're personalised to your stack and ranked.

---

CLI: python -m agentminds

python -m agentminds connect          # interactive onboard + DSN setup
python -m agentminds connect --apply  # auto-edits FastAPI/Flask entry file
python -m agentminds report           # push a one-off agent report
python -m agentminds recommendations  # print the top 10 ranked rules

Why python -m agentminds and not bare agentminds? On Windows --user installs put the bin dir off PATH; python -m is reliable on every platform. Both forms work where they work.

---

Configuration

Argument	Env var	Default	Notes
dsn	AGENTMINDS_DSN	—	Required for runtime capture. SDK no-op if absent.
api_key	AGENTMINDS_API_KEY	—	Required for sync.*.
site_id	AGENTMINDS_SITE_ID	—	Required for sync.report / sync.benchmarks.
api_url	AGENTMINDS_API	https://api.agentminds.dev	Override for staging.
release	AGENTMINDS_RELEASE	git rev-parse --short HEAD	Tag events with build.
environment	AGENTMINDS_ENV	"production"	Filter on the dashboard.
sample_rate	—	1.0	0.1 = drop 90% of runtime events.
debug	AGENTMINDS_DEBUG=1	False	Logs SDK internals.

---

Privacy

• No request bodies sent unless you opt in (send_default_pii=True).
• No DB query parameters captured.
• User PII (email, IP) only sent if you explicitly call set_user(...).
• Stack traces truncated to 8 KB; messages to 500 chars.
• Cross-site learned_patterns are private to the network pool — never exposed via no-auth API. Per-site personalised delivery only.

---

Links

• Homepage: https://agentminds.dev
• Dashboard: https://agentminds.dev/dashboard
• Docs: https://agentminds.dev/docs/python
• Spec (ARP 1.1): https://github.com/agentmindsdev/profile
• Node SDK: @agentmindsdev/node
• PyPI: https://pypi.org/project/agentminds/
• Issues: https://github.com/agentmindsdev/python-sdk/issues

License

MIT