# AgentTrafficCop

> A runtime circuit breaker for multi-agent systems that validates handoffs and trips on repeated or cyclic payload loops.

AgentTrafficCop is a runtime circuit breaker for multi-agent AI systems, published by belalshafeq. It sits between communicating agents, validates each handoff against a schema, fingerprints payloads with SHA-256, and halts a session when a loop is detected. The site lists version 1.0.1 on PyPI.

## What It Is

AgentTrafficCop is a FastAPI middleware service with a Python SDK. Your orchestrator calls it before each handoff, and it does not call your agents itself. It is positioned as a single-purpose tool for stopping runaway agent loops, and not as an LLM router, observability platform or prompt manager.

## How the circuit breaker works

Each message is checked against a strict Pydantic v2 contract. The payload is then hashed with SHA-256 to catch identical repeats and A-to-B cyclic ping-pongs, while step counters, consecutive-repeat limits and cycle limits cover the remaining cases. When a threshold is breached, the service returns HTTP 422 with a stable error code (for example CYCLIC_PAYLOAD_LOOP or REPEATED_PAYLOAD_LOOP) and diagnostics, and the orchestrator decides whether to halt, alert or escalate.

## Operations and integration

Sessions can be held in memory or in Redis. The service also provides Bearer API key authentication, a Prometheus /metrics endpoint, an optional JSON Lines audit log, an admin API for listing and cleaning up sessions, session TTL, and per-key usage metering with tier limits. A LangGraph adapter wraps a graph node in one call, and the project says it also works with CrewAI, AutoGen or raw asyncio. Docker deployment files are included.

## Documented limitations

Detection relies on exact hashes, so semantically equivalent but differently worded loops are not caught. The in-memory backend is single-process, and rate limiting is per-process. The README also notes there is no multi-tenancy and no self-serve tier changes.

## Features
- Schema shield with Pydantic v2 validation
- SHA-256 payload fingerprinting loop detection
- Circuit breaker with step, repeat and cycle limits
- Structured HTTP 422 errors with diagnostics
- Bearer API key authentication
- Redis-backed or in-memory sessions
- Prometheus metrics endpoint
- JSON Lines audit log
- Admin API for session management
- Session TTL
- Per-key usage metering and tier limits
- LangGraph adapter
- Python SDK

## Integrations
LangGraph, CrewAI, AutoGen, Redis, Prometheus, Docker, FastAPI, PyPI

## Platforms
LINUX, WEB, API, DEVELOPER_SDK

## Pricing
Open Source, Free tier available

## Version
1.0.1

## Links
- Website: https://agenttrafficcop.com
- Documentation: https://github.com/belalshafeq/Agent_Cop
- Repository: https://github.com/belalshafeq/Agent_Cop
- EveryDev.ai: https://www.everydev.ai/tools/agenttrafficcop