fieldstate-agent 0.1.0

80% fewer tokens for multi-step AI agents. Same quality.

FieldState

80% fewer tokens for multi-step AI agents. Same quality.

Standard agents re-read their full conversation history every step — cost grows linearly, forever. FieldState replaces history with a compact geometric field state: flat cost per step, regardless of task length. Plus real-time signals when your agent drifts, conflicts, or suppresses an objective.

Try the live demo →

---

Benchmark results

Measured on claude-haiku-4-5-20251001 via response.usage. Two independent runs.

Steps	Standard agent	FieldState	Saving
6	11,540 tokens	3,408	70%
12	42,487 tokens	6,821	84%
20	~111,000	~11,000	90%
50	~670,000	~28,000	96%

Quality: 5/5 on both agents (LLM-as-judge, thoroughness + clarity).

Input tokens per step — Standard (↑) vs FieldState (—)

6000 │                                      ╱
     │                                    ╱
4000 │                                  ╱
     │                               ╱
2000 │                           ╱
     │     ▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁
   0 └──────────────────────────────────
     Step  1   2   3   4   5   6  ...  12

---

Install

pip install fieldstate-agent

---

Usage

Option 1 — FieldAgent (drop-in for any task)

from fieldstate import FieldAgent

agent = FieldAgent(
    task="Review this codebase and suggest improvements",
    objectives=["thoroughness", "efficiency", "clarity"],
    api_key="sk-ant-..."  # or set ANTHROPIC_API_KEY
)

# Each step: returns output + a field signal
output, signal = agent.step("What are the security issues in auth.py?")
print(output)

# Field signals — things standard agents never see
if signal.suppressed:
    print(f"⚠ {signal.suppressed} is being ignored — agent losing balance")

if signal.conflict:
    print(f"⚡ Objectives in conflict: {signal.basins}")

if signal.drift:
    print(f"↘ Drifting toward {signal.drift_toward}")

# Token tracking
print(f"Saving so far: {agent.token_savings_pct:.0f}%")
print(agent.summary())

Option 2 — Drop-in replacement for existing Anthropic code

Change one line. Everything else stays identical.

# Before
import anthropic
client = anthropic.Anthropic(api_key="sk-ant-...")

# After — one line change
from fieldstate.adapters import FieldStateClient
client = FieldStateClient(
    api_key="sk-ant-...",
    task="Your agent's task description",
    objectives=["accuracy", "speed", "clarity"]
)

# Identical API — no other changes needed
response = client.messages.create(
    model="claude-haiku-4-5-20251001",
    max_tokens=600,
    messages=[{"role": "user", "content": "Your message"}]
)

print(response.content[0].text)
print(f"Token saving: {client.token_savings_pct:.0f}%")
print(f"Last signal: {client.last_signal}")

Option 3 — Compare both agents on any task

from fieldstate import compare

results = compare(
    task="Plan a product launch strategy",
    objectives=["user_value", "feasibility", "revenue_impact"],
    steps=[
        "What are the top 3 pain points we should address?",
        "Which single feature should we build first?",
        "The CEO says revenue matters more than growth. Does that change things?",
        "A competitor launched last week. How should we respond?",
        "Summarize the roadmap in 3 bullet points.",
    ]
)

print(f"Token saving: {results['token_saving_pct']}%")
print(f"Signals fired: {results['signals_fired']}")

Option 4 — Web UI (run locally)

pip install "fieldstate-agent[web]"
fieldstate serve
# Open http://localhost:8000

---

Field signals

FieldState tracks your agent's objectives geometrically. After each step it detects:

Signal	What it means	What to do
conflict	Objectives pulling in different directions	Surface the trade-off explicitly
suppressed	One objective being systematically ignored	Correct at the next step
drift	Agent losing balance toward one objective	Recalibrate
deadlock	Genuine impasse, no objective resolving	Escalate to human

Standard agents have no awareness of any of these. FieldState surfaces them in real time.

---

How it works

Instead of re-reading conversation history, FieldState maintains a 64-dimensional field state per objective. After each step, a local field engine updates the state — zero API cost. Before each step, ~30 tokens of field state replace thousands of tokens of history.

Standard agent:
  Step N: [system 450 tokens] + [full history grows forever] + [task]

FieldState:
  Step N: [last exchange ~200 tokens] + [field state ~30 tokens] + [task]
  ─────────────────────────────────────────────────────────────────────
  Cost stays flat. History is compressed into geometry, not prose.

---

When it helps most

✅ Tasks with 6+ steps — savings compound with each step
✅ Multi-objective tasks — conflict/suppression detection adds value
✅ Long-running autonomous agents — 90%+ saving at 20+ steps
✅ Goal shifts mid-task — field detects and surfaces them

❌ Tasks of 1–3 steps — overhead exceeds savings at very short tasks
❌ Tasks needing verbatim recall of early messages — use with fact register

---

Requirements

• Python 3.11+
• Anthropic API key (sk-ant-...)
• Works with any Anthropic model (Haiku recommended for cost efficiency)

---

License

MIT — use it, fork it, build on it.

---

Links

• Live demo: https://web-production-44f2d7.up.railway.app
• Benchmark code: fieldstate/agents/token_benchmark_v3.py
• Paper (coming soon): arXiv preprint in preparation