Metadata-Version: 2.4
Name: agentenna
Version: 0.1.3
Summary: The agent awareness layer
Project-URL: Homepage, https://agentenna.com
Project-URL: Repository, https://github.com/agentenna/agentenna
Author-email: Håvard <contact@agentenna.com>
License-Expression: Apache-2.0
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: httpx>=0.28
Requires-Dist: pydantic>=2
Provides-Extra: station
Requires-Dist: fastapi>=0.138.0; extra == 'station'
Requires-Dist: fastmcp>=2; extra == 'station'
Requires-Dist: uvicorn>=0.49.0; extra == 'station'
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://raw.githubusercontent.com/agentenna/agentenna/main/docs/assets/agentenna-readme-hero.png" alt="Agentenna — the awareness layer for AI agents" width="100%" />
</p>

<h1 align="center">agentenna</h1>

<p align="center"><strong>Agentenna is the awareness layer for AI agents.</strong></p>

<p align="center">
  <a href="https://github.com/agentenna/agentenna/releases/latest"><img src="https://img.shields.io/github/v/release/agentenna/agentenna?display_name=tag&sort=semver&color=9bd23c" alt="Latest release"></a>
  <a href="https://pypi.org/project/agentenna/"><img src="https://img.shields.io/pypi/v/agentenna?color=9bd23c&label=PyPI" alt="PyPI"></a>
  <a href="https://pypi.org/project/agentenna/"><img src="https://img.shields.io/pypi/pyversions/agentenna" alt="Python versions"></a>
  <a href="https://github.com/agentenna/agentenna/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/agentenna/agentenna/ci.yml?branch=main&label=CI" alt="CI"></a>
  <a href="https://github.com/agentenna/agentenna/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue" alt="Apache 2.0"></a>
</p>

<h2 align="center"><i>Your agent already knows.</i></h2>

<p align="center">
Agentenna gives agents a live, token-bounded view of what's happening —<br/>
messages, logs, alerts, tickets — rendered straight into context, refreshed every turn.<br/>
Inspect the details, rewind the history, wake up when it matters.
</p>

<p align="center">
  <code>pip install agentenna</code>
</p>

<p align="center">
  <a href="#quickstart">Quickstart</a> ·
  <a href="#connect-claude-code">Claude Code</a> ·
  <a href="#connect-any-mcp-host">MCP</a> ·
  <a href="https://github.com/agentenna/agentenna/blob/main/docs/cheatsheet.md">API cheatsheet</a> ·
  <a href="https://github.com/agentenna/agentenna/blob/main/docs/manifesto.md">Manifesto</a>
</p>

---

Agentenna puts a compact awareness surface inside the model's context. Emit a
fact from a terminal, service, webhook, or another agent; a reader tuned to
that channel sees it on its next turn. It is designed for proactive agents,
ambient assistants, and agent loops that need to notice what changed without
receiving an unbounded raw feed.

## See what the agent sees

This is real renderer output. It is not a dashboard screenshot or a prompt
mockup — this XML block is what the model receives:

```xml
<agentenna-awareness slot="agentenna:awareness" channel="prod.checkout" generated_at="2026-06-22T12:00:00+00:00">
  <instructions scope="kind:prod.error">
    Summarize impact first.
  </instructions>
  <learnings scope="kind:prod.error" confidence="0.9">
    Check the deploy first.
  </learnings>
  <states>
    <state kind="deploy.prod" message="rolled_back" t="-2m" />
  </states>
  <tasks open="1" claimed="0" blocked="0">
    <task id="task_12" priority="high" status="open" t="-11m" kind="ops.triage">
      Investigate recurring checkout 5xx spikes.
    </task>
  </tasks>
  <agentenna-events window="30m">
    <event id="evt_456" t="-2m" severity="crit" kind="prod.error" has_payload="true">
      Billing worker failed processing webhook.
    </event>
  </agentenna-events>
  <actions>Use inspect(id) to expand any event or task with has_payload="true".</actions>
</agentenna-awareness>
```

The surface is a HUD for the agent:

- **events** show what changed
- **states** show what is true now
- **tasks** show work awaiting judgment
- **instructions and learnings** travel with the signals they govern
- **inspect and rewind** keep full detail and history out of the prompt until needed

With replace-mode injection, the block occupies one named slot and replaces
the previous block every turn. The agent gets a bounded view, not an
ever-growing paste of old alerts.

## Quickstart

**Emit → Station → reader.**

Requires Python 3.12 or newer.

```bash
pip install "agentenna[station]"
agentenna hello
```

`agentenna hello` leaves no files behind. It emits sample signals and prints
the awareness surface an agent would receive.

### 1. Start a Station

A **Station** stores signals, serves the HTTP API, and hosts the read-only MCP
surface.

```bash
agentenna serve \
  --db .agentenna/agentenna.db \
  --port 1234
```

That is the complete local first run: a loopback Station runs open, and local
SDK clients, hooks, and MCP connect without a token. For a shared or exposed
Station, pass `--token` and give clients the same bearer token.

### 2. Emit something

In another terminal, use the same local database:

```bash
# One fact
agentenna emit prod.errors "Checkout 5xx rate jumped to 12%" \
  --kind fault --severity crit \
  --db .agentenna/agentenna.db

# Every non-empty line becomes a low-severity log event; output still passes through
tail -f app.log | agentenna pipe terminal.logs \
  --db .agentenna/agentenna.db

# Emit the result of a command; fast successful commands stay quiet
agentenna run ci.builds --db .agentenna/agentenna.db -- pytest -q
```

`pipe` and `run` redact common secret-looking values by default. The v0.1 CLI
producers write directly to local SQLite, so use the Station's `--db` path on
the same machine. Remote producers use the Python SDK or webhook endpoint.

### 3. Add a reader

#### Connect Claude Code

The included installer configures project-level turn hooks and MCP:

```bash
export AGENTENNA_STATION_URL=http://localhost:1234
export AGENTENNA_CHANNELS=prod.errors,ci.builds,terminal.logs

agentenna install claude-code
agentenna doctor
```

Start Claude Code from that shell. At session start it receives a composed
snapshot; before each prompt it receives only new events. Quiet turns inject
nothing. `agentenna_inspect` and `agentenna_rewind` are available through MCP
when the agent needs depth.

Claude Code has an append-only transcript, so this integration uses delta mode:
eventful deltas remain until host compaction, then a fresh snapshot is seeded.
State changes mid-session appear at the next snapshot or an explicit MCP
listen. See the [Claude Code guide](https://github.com/agentenna/agentenna/blob/main/docs/hosts/claude-code.md) for the exact
delivery guarantee and configuration-file option.

#### Connect your own agent loop

```python
from agentenna import Antenna, inject_awareness

ant = Antenna.connect(
    "http://localhost:1234",
    entity="my-agent",
)
channel = ant.channel("prod.errors")

async def run_turn(messages, run_agent):
    surface = channel.listen(new_only=True)
    aware_messages = inject_awareness(messages, surface, max_chars=4_000)
    response = await run_agent(aware_messages)
    surface.ack()  # advance only after the turn succeeds
    return response
```

`inject_awareness` works with OpenAI-style message lists. Complete examples
for [raw messages](https://github.com/agentenna/agentenna/blob/main/docs/hosts/raw-messages.md),
[Pydantic AI](https://github.com/agentenna/agentenna/blob/main/docs/hosts/pydantic-ai.md), and
[LangGraph](https://github.com/agentenna/agentenna/blob/main/docs/hosts/langgraph.md) are included.

#### Connect any MCP host

Run the stdio bridge:

```bash
agentenna mcp \
  --station http://localhost:1234
```

It exposes four read-only tools:
`agentenna_list_channels`, `agentenna_listen`, `agentenna_inspect`, and
`agentenna_rewind`. Hosts without turn-start hooks, including the current
[Cursor](https://github.com/agentenna/agentenna/blob/main/docs/hosts/cursor.md) and [Codex](https://github.com/agentenna/agentenna/blob/main/docs/hosts/codex.md) integrations,
use MCP pull mode: freshness depends on the agent calling `listen`.

## Emit once. Every agent knows.

A Channel is a named shared bus, not point-to-point delivery. Many
producers can emit to it and many readers can tune in:

```text
               ticket   webhook  logger  health  terminal
                  │        │       │       │        │
support.urgent ───●────────●───────┼───────┼────────┼────●────────●────────┼────────▶
                                   │       │        │    │        │        │
prod.errors    ────────────────────●───────●────────┼────┼────────●────────●────────▶
                                                    │    │        │        │
terminal.logs  ─────────────────────────────────────●────┼────────┼────────●────────▶
                                                         │        │        │
                                                      support     AI     coding
                                                       agent   assistant   agent

             ● tap (emit above · listen below)   ┼ crossing, no connection   ▶ time
```

The multiplexer analogy is precise: producers place inputs onto named buses;
each reader's channel subscription is its select line. Every reader acts as
its own demultiplexer and keeps its own ack-position. One reader moving
forward does not hide the signal from another.

One emit can therefore update all your running agents without N copies of the
same webhook glue.

## Send from anything

Remote SDK:

```python
from agentenna import Antenna

ant = Antenna.connect(
    "http://localhost:1234",
    entity="checkout-api",
)
ant.channel("prod.errors").emit(
    "Stripe webhook failed: KeyError customer_id",
    severity="high",
    kind="fault",
    source="stripe-webhook",
)
```

Python logging:

```python
import logging
from agentenna import AgentennaLogHandler

logging.getLogger().addHandler(
    AgentennaLogHandler(ant.channel("app.logs"))
)
```

Any JSON webhook:

```bash
curl -X POST \
  "http://localhost:1234/v1/ingest/prod.alerts?kind=alert&severity=high" \
  -H "Content-Type: application/json" \
  -d '{"message":"disk usage reached 91% on db-1"}'
```

The generic ingest endpoint keeps the original body as inspectable payload.
Use `message_path=some.nested.field` when the message is nested.

> Webhooks deliver payloads to your server. Agentenna delivers awareness to
> your agent.

## How delivery fits the host

Agentenna uses the strongest delivery mode each host supports:

| Mode | Used by | Guarantee |
|---|---|---|
| **Replace** | message lists, Pydantic AI, LangGraph | one slot is replaced; fixed per-turn awareness budget |
| **Delta** | Claude Code | session snapshot, then only new events; quiet turns cost zero |
| **Pull** | Cursor, Codex, generic MCP hosts | awareness on demand; freshness depends on the agent asking |

The Station and surface stay the same. Only the last step into context changes.

## What people use it for

- **Self-monitoring coding agents and developer helpers** — keep tests,
  terminal output, CI results, and deploy state near the current task.
- **Production assistants** — surface application logs, health changes, and
  webhook alerts; wake a receiver only for deliberate trigger events.
- **Support and operations agents** — turn ticket or queue webhooks into a
  compact feed, current state, and durable tasks.
- **Personal and ambient agents** — carry selected calendar, inbox, home, or
  chat changes from your own integrations into an always-on assistant.
- **Multi-agent systems** — emit outcomes and handoffs onto shared channels
  without coupling one agent runtime to another.

Agentenna does not run your agents. It sits beside your runtime and carries
live context into the model:

| Layer | Question |
|---|---|
| Memory | What mattered before? |
| Tools | What can the agent do? |
| **Agentenna** | **What is happening now?** |

Memory is what mattered. **Awareness is what's happening.**

## Seeing is not waking

Most signals should simply appear on the next surface. For the few that
cannot wait, attach a `Trigger` and run a receiver:

```python
from agentenna import Antenna, Event, Trigger

ant = Antenna.connect(
    "http://localhost:1234",
    entity="oncall-agent",
)
channel = ant.channel("prod.errors")

channel.emit(
    Event(
        message="Checkout error rate crossed 12%",
        severity="crit",
        kind="incident",
        trigger=Trigger(key="oncall"),
    )
)

@ant.on("oncall")
async def handle(event):
    print(f"woke on: {event.message}")
    event.ack()

ant.run_receiver()
```

Triggered delivery is at-least-once and best-effort. **Some things your agent
should just see. Some things should wake it up.**

## Run it locally

The Python process above is the shortest path. The repository also includes a
Dockerfile and Compose setup that build from source:

```bash
docker compose up --build
```

The Station uses SQLite WAL, optional bearer-token auth, bounded age retention,
OpenAPI, health endpoints, and MCP at `/mcp`.

Apache 2.0. Everything in the repo is the whole product — no account, no
telemetry, and your feeds never leave your box.

## v0.1 status

The current public release is intentionally small and pre-1.0:

- Python 3.12+; local SQLite or one self-hosted HTTP Station
- XML awareness surface
- SDK, CLI `emit` / `pipe` / `run`, logging handler, and generic webhook ingest
- events, states, tasks, scoped instructions and learnings
- inspect, full-text rewind, per-reader ack-positions, triggers and receivers
- Claude Code hooks + MCP; MCP pull guides for Cursor and Codex
- bring inputs through the SDK, logging handler, terminal producers, or
  generic webhook

APIs may change before 1.0. If something does not work as documented, please
[open an issue](https://github.com/agentenna/agentenna/issues).

## Documentation

- [API cheatsheet](https://github.com/agentenna/agentenna/blob/main/docs/cheatsheet.md) — the complete v0.1 surface
- [Host guides](https://github.com/agentenna/agentenna/blob/main/docs/hosts/README.md) — delivery modes and setup by runtime
- [Examples](https://github.com/agentenna/agentenna/tree/main/examples) — runnable Python, MCP, and receiver integrations
- [Manifesto](https://github.com/agentenna/agentenna/blob/main/docs/manifesto.md) — why awareness is a separate agent primitive
- [Contributing](https://github.com/agentenna/agentenna/blob/main/CONTRIBUTING.md) — development setup and DCO

Apache 2.0 · the client in your code is an
*Antenna* · the process you run is a *Station*.

---

<p align="center">
Memory gave agents a past. Tools gave them hands.<br/>
<strong>Agentenna gives them the present.</strong>
</p>

<p align="center"><sub>When you turn to your agent — <i>it already knows.</i></sub></p>
