Agentation

Visual feedback tool for AI coding agents. Adds a floating toolbar to your web application that displays structured page information optimized for AI consumption.

Installation

pip install agentation

With framework-specific extras:

pip install agentation[flask]
pip install agentation[fastapi]

Quick Start

Flask

from flask import Flask
from agentation import AgentationFlask

app = Flask(__name__)
AgentationFlask(app)  # Auto-enabled when app.debug=True

See the Flask Guide for complete documentation.

FastAPI

from fastapi import FastAPI
from agentation import AgentationMiddleware, AgentationConfig

app = FastAPI()
config = AgentationConfig(enabled=True)
app.add_middleware(AgentationMiddleware, config=config)

See the FastAPI Guide for complete documentation.

Configuration

All options can be passed to AgentationConfig:

Option	Type	Default	Description
enabled	bool | None	None	Enable toolbar. If None, uses env var or debug mode
default_detail	str	"standard"	Detail level: compact, standard, detailed, forensic
default_format	str	"markdown"	Output format: markdown, json
position	str	"bottom-right"	Toolbar position: bottom-right, bottom-left, top-right, top-left
theme	str	"auto"	Color theme: auto, light, dark
accent_color	str	"#3b82f6"	Accent color (hex)
keyboard_shortcut	str	"ctrl+shift+a"	Keyboard shortcut to toggle output
block_interactions	bool	True	Block page interactions while panel is open
auto_clear_on_copy	bool	False	Clear output after copying
include_route	bool	True	Include route info in output

Enabling

Agentation uses the following precedence to determine if it's enabled:

1. Explicit enabled config option
2. AGENTATION_ENABLED environment variable (true/1/yes or false/0/no)
3. Framework debug mode (e.g., app.debug in Flask)
4. Default: disabled

Output Formats

Markdown (default)

Structured text optimized for AI agents to understand page structure:

• Compact: Minimal output with key elements only
• Standard: Balanced detail with headings, forms, and main content
• Detailed: Full page structure including all interactive elements
• Forensic: Complete DOM analysis for debugging

JSON

Machine-readable structured data with the same detail levels.

Keyboard Shortcut

Press Ctrl+Shift+A (configurable) to toggle the output panel. This copies structured page information to your clipboard, ready for pasting into an AI coding assistant.

Development

uv venv
uv pip install -e ".[dev]"
pytest

Credits

Python port of Agentation by Benji Taylor.

License

MIT