agentwarden-ai

AgentWarden

AgentWarden is a local, OpenAI-compatible proxy that tracks and reduces repeated context sent by tool-using agents. Your API key stays in your own agent process.

Start here

Important: turn the optimizers on

Every optimizer is off by default. After starting the dashboard, open the top-right settings button, enable the four toggles, and press Apply settings. They apply immediately to the running local proxy.

The controls reset when the proxy stops. For durable defaults, use the environment variables in Configuration.

1. Install and start

Requirements: Python 3.11+ and an OpenAI API key.

python3.11 -m venv .venv
source .venv/bin/activate
pip install agentwarden-ai
agentwarden dashboard

This starts your local proxy and dashboard at http://127.0.0.1:8080/dashboard.

2. Change one line in your agent

Keep your API key exactly where it already is. Change only the OpenAI client's base URL:

from openai import OpenAI

client = OpenAI(
    api_key="your-openai-api-key",
    base_url="http://127.0.0.1:8080/v1",
)

Run your agent normally. Then return to the dashboard to see its request receipt: input tokens, estimated spend, tools removed, per-segment usage, and the optimization passes that ran.

That is the whole integration. AgentWarden supports OpenAI Chat Completions clients, including streaming. It does not store API keys.

How savings grow

Tool Prune observes the tools your agent actually calls, keeps the first three requests unchanged, then removes unused tool schemas. The other enabled passes clean redundant old context deterministically. In other words, AgentWarden has more opportunity to help as an agent has a longer, repeated workflow.

For agents with repeated tool schemas and growing history, 10-15+ requests can reduce input cost by roughly 16-50%, depending on the toolset and context. This is a workload-dependent range, not a guaranteed result. Always use the local receipt and replay verifier to measure your own agent.

The four optimizers

Every pass is independently toggleable. With all four off, AgentWarden is a byte-identical pass-through proxy.

Track what is happening

The dashboard is the simplest way to inspect a session. It is local and bundled with the Python package; no Node.js or separate frontend server is required.

For a stable receipt per agent run, optionally send a session header:

client.chat.completions.create(
    model="gpt-5.6-terra",
    messages=messages,
    extra_headers={"X-AgentWarden-Session": "support-agent-run-42"},
)

You can also query the receipt directly:

agentwarden stats --session-id support-agent-run-42
curl "http://127.0.0.1:8080/traces?session_id=support-agent-run-42"

Configuration

Use these before agentwarden dashboard or agentwarden serve when you want the settings to survive a restart:

export AGENTWARDEN_ENABLE_TOOL_PRUNE=true
export AGENTWARDEN_ENABLE_HISTORY_TRIM=true
export AGENTWARDEN_ENABLE_CONTEXT_DEDUP=true
export AGENTWARDEN_ENABLE_CACHE_ORDER=true
export AGENTWARDEN_SESSION_BUDGET_USD=0.02
agentwarden dashboard

Useful commands:

agentwarden dashboard                 # dashboard + proxy on port 8080
agentwarden serve                     # proxy only on port 8080
agentwarden doctor                    # check that the local proxy is reachable
agentwarden stats --session-id NAME   # print a session receipt
agentwarden verify --no-judge         # compare the demo workflow with optimizers off vs. on

Judge and contributor test path

AgentWarden is installable directly from PyPI; no frontend build is required:

python3.11 -m venv .venv
source .venv/bin/activate
pip install agentwarden-ai
agentwarden dashboard

Open http://127.0.0.1:8080/dashboard, enable the optimizer toggles, and point an OpenAI Chat Completions client at http://127.0.0.1:8080/v1. Live requests require the tester's own OPENAI_API_KEY and OpenAI API quota.

To run the repository's offline test suite instead:

git clone https://github.com/Jahanshah1/AgentWarden.git
cd AgentWarden
python3.11 -m venv .venv
.venv/bin/pip install -e '.[dev]'
.venv/bin/pytest -m 'not live' -q

Built with Codex and GPT-5.6

AgentWarden was built during OpenAI Build Week by Jahan Shah in collaboration with Codex and GPT-5.6. Codex accelerated implementation and iteration across the OpenAI-compatible streaming proxy, deterministic optimizer pipeline, pytest coverage, local dashboard, PyPI packaging, and the public site. Jahan defined the product direction, reviewed implementation choices, and ran the real agent workflows used for the receipts shown above.

The project keeps the build story inspectable: the repository includes the tests, demo agent, release workflow, design decisions, and documentation used to get from the core proxy to the packaged product.

Verify the project from a clone

python3.11 -m venv .venv
.venv/bin/pip install -e '.[dev]'
.venv/bin/pytest -m 'not live' -q

For the end-to-end demo agent:

export OPENAI_API_KEY="your-key"
.venv/bin/agentwarden demo
.venv/bin/agentwarden verify --no-judge

See the user guide for troubleshooting and the launch playbook for rollout guidance.

Current scope

AgentWarden is a local, single-user alpha, published on PyPI as agentwarden-ai. It currently proxies OpenAI Chat Completions only; the Responses API and non-OpenAI providers are outside the current scope.

Created by Jahan Shah.