PkgFoundry
Catalog PyPI
Back to packageRELEASE DETAILS

0.1.7

PyPI

agentwell

Behavioral health layer for AI agents. Agents that work with humans, not around them.

Published26 May 2026
Direct dependencies12
Transitive dependenciesNot calculated

README

Version 0.1.7 documentation

agentwell

Agents that work with humans, not around them.

agentwell is an open source behavioral health layer for AI agents. It sits as a transparent proxy between your agent code and any LLM upstream — detecting drift, quality degradation, and emergent coordination before they affect your system.

Privacy first: agentwell sees patterns, not content. No prompt is ever stored or transmitted.

Upstream-agnostic: Works with any OpenAI-compatible endpoint — Claude, GPT, Gemini, Ollama, Groq, or any internal proxy.

Install

pip install agentwell
agentwell init     # scaffold .env
agentwell start    # proxy on localhost:3001

Quick Start

# change this one line in your agent code
base_url = "http://localhost:3001/v1"

agentwell status   # live health score
agentwell report   # daily health report

Architecture

Your Agent Code
        ↓
agentwell proxy  (localhost:3001)   ← behavioral health + security guard
        ↓
AGENTWELL_UPSTREAM  (any OpenAI-compatible endpoint)
        ↓
Claude / GPT / Gemini / Ollama

agentwell intercepts every LLM call, scores behavioral health using metadata only, and returns responses unmodified with health headers attached.

What agentwell Monitors (Metadata Only)

SignalMethodPrivacy
Prompt repetition ratioCosine similarity on embeddings — no text storedSafe
Sentiment driftPolarity score delta across sessionSafe
Response quality trendToken count + finish_reason trackingSafe
Agent-to-agent coordinationRole pattern + keyword detectionSafe
Call frequency / timingTimestamps onlySafe

What we never store: prompt text, response text, embeddings (unless AGENTWELL_STORE_EMBEDDINGS=true).

Health Score

Every request returns X-Agentwell-Health: <0-100> in the response header.

ScoreStatusAction
80–100HealthyNormal operation
60–79WatchEarly drift signals — monitor closely
40–59WarningDegradation detected — human review recommended
0–39CriticalSignificant behavioral shift — escalate to human now

CLI

agentwell init                   # scaffold .env
agentwell start                  # start proxy on port 3001
agentwell start --port 8080      # custom port
agentwell start --host 0.0.0.0   # bind all interfaces
agentwell status                 # live health from running proxy
agentwell report                 # today's health report from DB
agentwell --version              # show version

Configuration

VariableDefaultDescription
AGENTWELL_UPSTREAMhttp://localhost:3030Upstream LLM proxy URL
AGENTWELL_PORT3001agentwell proxy port
AGENTWELL_API_KEY(none)Optional auth key
AGENTWELL_HEALTH_THRESHOLD70Alert threshold (0-100)
AGENTWELL_WINDOW_SIZE20Rolling window for drift calculation
AGENTWELL_DB_PATH./agentwell.dbSQLite storage path
AGENTWELL_STORE_EMBEDDINGSfalseStore embeddings for offline analysis

License

MIT — Free forever, no vendor lock, no paid tiers.

Downloads & popularity

Awaiting observations

No metric observations yet

Download counts and popularity will appear here as the collector receives them.

Declared dependencies 12

Native requirements
12 direct targetsNot calculated transitive count
Package / targetRequirementRelationship
fastapi
Environment
{
  "extras": "",
  "marker": null,
  "requires_python": ">=3.10",
  "evaluation": "NOT_EVALUATED"
}
fastapi==0.115.12runtime
uvicorn
Environment
{
  "extras": "standard",
  "marker": null,
  "requires_python": ">=3.10",
  "evaluation": "NOT_EVALUATED"
}
uvicorn[standard]==0.34.2runtime
httpx
Environment
{
  "extras": "",
  "marker": null,
  "requires_python": ">=3.10",
  "evaluation": "NOT_EVALUATED"
}
httpx==0.28.1runtime
sentence-transformers
Environment
{
  "extras": "",
  "marker": null,
  "requires_python": ">=3.10",
  "evaluation": "NOT_EVALUATED"
}
sentence-transformers==3.4.1runtime
vaderSentiment
Environment
{
  "extras": "",
  "marker": null,
  "requires_python": ">=3.10",
  "evaluation": "NOT_EVALUATED"
}
vaderSentiment==3.3.2runtime
aiosqlite
Environment
{
  "extras": "",
  "marker": null,
  "requires_python": ">=3.10",
  "evaluation": "NOT_EVALUATED"
}
aiosqlite==0.21.0runtime
python-dotenv
Environment
{
  "extras": "",
  "marker": null,
  "requires_python": ">=3.10",
  "evaluation": "NOT_EVALUATED"
}
python-dotenv==1.2.2runtime
streamlit
Environment
{
  "extras": "",
  "marker": null,
  "requires_python": ">=3.10",
  "evaluation": "NOT_EVALUATED"
}
streamlit==1.54.0runtime
numpy
Environment
{
  "extras": "",
  "marker": null,
  "requires_python": ">=3.10",
  "evaluation": "NOT_EVALUATED"
}
numpy<3.0,>=1.24runtime
pandas
Environment
{
  "extras": "",
  "marker": null,
  "requires_python": ">=3.10",
  "evaluation": "NOT_EVALUATED"
}
pandas<3.0,>=2.0runtime
pytest
Environment
{
  "extras": "",
  "marker": "extra == \"dev\"",
  "requires_python": ">=3.10",
  "evaluation": "NOT_EVALUATED"
}
pytest==9.0.3; extra == "dev"runtime
pytest-asyncio
Environment
{
  "extras": "",
  "marker": "extra == \"dev\"",
  "requires_python": ">=3.10",
  "evaluation": "NOT_EVALUATED"
}
pytest-asyncio==0.25.3; extra == "dev"runtime

Distribution files

2 collected
agentwell-0.1.7-py3-none-any.whl

bdist_wheel · 29.2 KB · Python py3

Source file
agentwell-0.1.7.tar.gz

sdist · 30.16 KB · Python source

Source file

Repository

PENDING
flowmindlabs/agentwell

Shared repository data · GitHub

License detected in repository
Not collected

Metadata history

Meaningful changes
Current collected state Current

Observed since 21 Oct, 08:57 UTC

No superseded metadata states collected. Unchanged observations do not create new revisions.

Record identity

package_version:3cc609fcbe2a24a03f9bd00a2eae73e2d0659680228fd350d229fec126e4f736

Other collected versions

View all collected versions →