microsoft/amplifier-drumbeat

microsoft/amplifier-drumbeat

Description: Drumbeat - scheduled automations using Amplifier Agent

Language: Python

License: MIT

Stars: 2

Forks: 1

Open issues: 0

Created: 2026-08-25T18:26:09Z

Pushed: 2026-08-28T04:11:58Z

Default branch: main

Fork: no

Archived: no

README:

drumbeat

An automation engine for long-running agent sessions. You write an automation as a markdown file — a schedule, a notify policy, and an ordered list of natural-language steps. drumbeat runs those steps as sequential turns in a pinned agent session, on time, unattended, with the tools you bring; then it emits a reasoned, durable record of what it decided, including *why* it stayed quiet. It never delivers anything itself: it hands your service a delivery intent and gets out of the way.

The design goal is not "agents that do things." It is agents that run unattended for months without silently going wrong — so most of what is in here exists to convert a silence you cannot trust into a record you can.

---

Prerequisites

Two things. The engine installs as a single command that co-installs the agent it runs; you supply the provider key it runs against.

1. `uv` and `git`. drumbeat installs from a git URL with uv, which also provisions the Python it needs (3.13). Install uv first if you don't have it; git must be present because the install is a git reference. amplifier-agent — which ships the engine library every turn imports — is a dependency, so the single install below brings it too. It is not on PyPI; there is nothing separate to install and nothing to put on your PATH.

2. An LLM provider key, exported in the environment the engine starts in.

export ANTHROPIC_API_KEY=sk-ant-... # or your provider's equivalent

Check it against the same engine your turns run on: if the key is missing, a turn still exits 0 and returns the reply Error: No providers available. That is a successful-looking run that did nothing, so verify it once by hand rather than discovering it in a run artifact at 03:40:

uvx --from git+https://github.com/microsoft/amplifier-agent \
amplifier-agent run --fresh --session-id keycheck --output json -y --cwd . "say ok" \
| python3 -c 'import json,sys; print(json.load(sys.stdin)["reply"])'

If that prints an actual greeting, you are done. If it prints Error: No providers available, the engine will start fine and every automation will produce that string as its output.

Running the engine under systemd? The key must be in the *unit's* environment (an EnvironmentFile=), not just your shell's.

---

Quickstart

1. Install the engine. One command. It installs drumbeat and co-installs the amplifier-agent engine library it runs on into the same tool environment.

uv tool install git+https://github.com/microsoft/amplifier-drumbeat
drumbeat --help

That is the whole install. amplifier-agent rides along as a dependency, so its engine library lands in the same tool venv and every turn imports it there automatically — there is no second install and nothing to put on your PATH. The agent dependency is unpinned, so uv tool upgrade drumbeat takes drumbeat *and* the latest agent main in one step.

A running engine keeps executing the code it was started from until you restart it: reinstall or upgrade under a live engine and drumbeat doctor reports exactly that, as STALE — the difference between "I upgraded that" and "I upgraded that and restarted."

2. Make a workspace. One command scaffolds the whole layout — the four directories, both prompt files, a drumpack list, a placeholder agent config, and one working example automation.

drumbeat init ~/myspace

Run it twice and it refuses rather than overwrite, naming exactly what already exists; --force overwrites the scaffold files and nothing else. Everything it writes is yours to edit.

prompts/ is not optional decoration. auto-notify.md is the exact text sent to the agent to ask "is any of this worth telling the user about?" — the engine ships no built-in copy, so a notify: auto automation aborts, loudly and by name, if you empty or delete it. init writes it for you; it is a plain file.

3. Write one automation. init already dropped one example under automations/ (shipped disabled, like every exemplar). For your very first run, add a trivial always-on one — ~/myspace/automations/hello.md:

---
automation:
name: Hello
enabled: true
trigger:
type: schedule
expression: every 10 minutes
notify: always
---

1. Report the current time and confirm which schedule triggered this run.

That runs today, with no tools at all.

4. Start the engine.

drumbeat serve --workspace ~/myspace --port 9100

It refuses to start, naming the fix, if the amplifier-agent engine library cannot be imported — so an engine that cannot execute a single turn never reaches the point of reporting itself healthy.

5. Run it now, before trusting the schedule. In a second terminal:

KEY=$(drumbeat api-key --workspace ~/myspace --show)
curl -s -X POST -H "X-API-Key: $KEY" localhost:9100/api/automations/hello/run
curl -s -H "X-API-Key: $KEY" localhost:9100/api/automations/hello/runs

Every mutating request needs that key, including from loopback. It is minted on first start and lives in your data dir; --show prints it.

Then read the run artifact under ~/myspace/runs/hello//. Every step's output is there.

6. Check it.

drumbeat doctor --workspace ~/myspace

What healthy looks like: status: FRESH (the running process matches the code on disk), agent turns in flight: 0 between runs, agent command: naming the engine library and the interpreter that imports it, bundle prewarm: OK, draining: no, and orphan pins: 0. FRESH is the one to learn — it goes STALE the moment you edit engine code under a running process, which is the difference between "I fixed that" and "I fixed that and restarted."

Two notes you will see on a fresh quickstart workspace, both expected. workspace git: not a git checkout — the engine is telling you your policy has no archive, which is true and fine for an evaluation. And a CONTAINMENT WARNING that your data dir sits inside your workspace: with the layout above it does, deliberately, because one directory is simpler to start with. It matters the day you git init that workspace, since a `git clean...