agentenna 0.1.2

The agent awareness layer

agentenna

The agent awareness layer.

The whole API on one page: docs/cheatsheet.md.

Quickstart

pip install agentenna
python examples/passive_quickstart.py

Run A Station

pip install "agentenna[station]"
agentenna serve --db .agentenna/agentenna.db --port 1234 --token dev-token

Passive Awareness

from agentenna import Antenna, State

ant = Antenna.connect("http://localhost:1234", token="dev-token", entity="billing-service")
ch = ant.channel("prod.errors")

# Events are the ticker — what happened.
ch.emit("checkout latency elevated", severity="med", kind="metric", source="checkout_api")

# States are the gauges — what is true right now. `kind` is the cell, `message`
# is the current value; re-emitting overwrites it (latest-per-kind, no history noise).
ch.emit(State(kind="deploy.prod", message="rolled_back"))

# One read verb: listen() gathers the events delta and the latest states into one
# awareness surface, and render() composes the <agentenna-awareness> block.
awareness = ch.listen(window="30m", limit=5)
print(awareness.render())

Producers

Anything can transmit:

import logging
from agentenna import Antenna, AgentennaLogHandler

ant = Antenna.local(".agentenna/agentenna.db", entity="billing-service")
logging.getLogger().addHandler(AgentennaLogHandler(ant.channel("app.logs")))

tail -f app.log | agentenna pipe app.logs        # tee stdin onto the surface
agentenna run ci.builds -- pytest -q             # emit a command's outcome

# Any webhook → the surface, one URL (no per-source code):
curl -X POST "http://localhost:1234/v1/ingest/ci.builds?message_path=workflow_run.name&token=dev-token" \
  -H "Content-Type: application/json" -d '{"workflow_run": {"name": "deploy failed"}}'

Hosts

Per-host guides with each host's delivery tier and guarantee: docs/hosts — raw message lists, Pydantic AI, LangGraph, Cursor, Codex CLI.

Triggers

See examples/trigger_receiver.py for the active awareness loop: emit an event with a Trigger, then run a receiver that wakes on it and acks it.

MCP

See examples/mcp_cursor.md for connecting an MCP client to a running Station.