Agents loop. They call the same tool with the same arguments, retry a failing dependency, bounce work between two agents, or press on through a failure streak. BehaviorWeave watches observable runtime activity, detects these patterns deterministically, and returns a typed intervention, such as nudge, escalate, human review, or stop, that your application applies.

Highlights

• Deterministic and explainable. The same events always produce the same decision, with the pattern, count, threshold, and policy that caused it. No model calls, no heuristics.
• One-line LangChain integration. BehaviorWeaveMiddleware guards every tool call of a create_agent agent, including Deep Agents: it appends guidance, blocks stop decisions, and tracks failures.
• Built for real agent failure modes. Repeated tool calls, node loops, failure and retry streaks, delegation churn, and agents handing work back and forth.
• Correct under concurrency. Scope isolation, idempotent redelivery, and atomic state transitions; a once-only policy fires exactly once even when workers race.
• Your runtime stays in control. The engine returns decisions; it never stops, reroutes, or mutates your graph. The optional middleware refuses tool calls only for the intervention kinds you configure.
• Fast and lean. Pure-Python core with no framework imports, tens of thousands of events per second, and bounded memory. Fully typed, with 100% test coverage including property-based tests.

Installation

pip install behaviorweave

or uv add behaviorweave. BehaviorWeave supports Python 3.12, 3.13, and 3.14.

Quickstart

from behaviorweave import (
    BehaviorEngine,
    BehaviorEvent,
    InterventionType,
    PolicyRule,
)

engine = BehaviorEngine(
    policies=[
        PolicyRule("repeat-nudge", "repeated_tool_call", 2, InterventionType.NUDGE),
        PolicyRule("repeat-stop", "repeated_tool_call", 3, InterventionType.STOP),
    ]
)

kinds = []
for _ in range(3):
    decision = engine.process(
        BehaviorEvent.tool_call("get_alarm", {"machine": "ETCH-3"}, scope="incident-42")
    )
    kinds.append(decision.intervention.kind.value)

print(kinds)  # ['noop', 'nudge', 'stop']
print(decision.intervention.reason)  # 'get_alarm' occurred 3 consecutive times

Guard a LangChain agent

from langchain.agents import create_agent

from behaviorweave.integrations.langchain import BehaviorWeaveMiddleware

agent = create_agent(
    "openai:gpt-4.1-mini",
    tools=[get_alarm],
    middleware=[BehaviorWeaveMiddleware(engine)],
)
agent.invoke(
    {"messages": [{"role": "user", "content": "Inspect ETCH-3."}]},
    config={"configurable": {"thread_id": "incident-42"}},
)

The second identical call returns the tool result with [BehaviorWeave:nudge] ... appended; the third is blocked before the tool runs.

Built-in patterns

Policies map these patterns to interventions (nudge, warning, redirect, retry, escalate, human_review, force_synthesis, pause, stop, or custom) with thresholds, priorities, per-policy cooldowns, and once-only semantics. You can also configure your own instances of the pattern classes or implement the Pattern protocol.

Integrations

Examples

The examples/ directory contains fifteen runnable scenarios that use a real, OpenAI-compatible model: middleware guards, MCP, LangGraph loops, multi-agent delegation, Swarm, Deep Agents, retry caps, oscillation, cooldowns, escalation ladders, concurrency, and a provenance-linked audit with langgraph-xai.

Agent Skill

The behaviorweave Agent Skill teaches coding agents such as Claude Code, Codex, Cursor, and GitHub Copilot to integrate, tune, and test BehaviorWeave. It follows the Agent Skills specification and includes API references, recipes, troubleshooting, an offline setup check, and a policy test template; see installation.

Documentation

Full documentation is at behaviorweave.readthedocs.io: quickstart, concepts, integrations, API reference, and architecture. Release notes and upgrade guidance are in CHANGELOG.md.

Contributing and security

Contributions are welcome; see CONTRIBUTING.md and the Code of Conduct. Please report vulnerabilities privately as described in SECURITY.md.

License

Apache License 2.0. See LICENSE.