microsoft/amplifier-agent

microsoft/amplifier-agent

Language: Python

License: MIT

Stars: 1

Forks: 1

Open issues: 1

Created: 2026-05-18T17:49:51Z

Pushed: 2026-06-11T02:22:19Z

Default branch: main

Fork: no

Archived: no

README:

Amplifier Agent

`amplifier-agent` is a thin CLI wrapping the Amplifier kernel as a reactive stdio coprocess. Anything that can spawn a subprocess — a shell script, a Node app, a Python script, a chat bot, an IDE plugin — can use it as an agentic AI backend.

---

What it is

A single binary that:

• Accepts a prompt and returns a result (single-turn): amplifier-agent run "your prompt"
• Emits one JSON envelope on stdout per invocation — wrappers spawn one process per turn and pass --session-id for continuity

It is *not* a server, daemon, or long-lived service. Each invocation is a fresh process that runs one turn and exits. Multi-turn conversations are managed at the wrapper or session-ID layer — not inside a persistent process.

The engine library inside (amplifier_agent_lib) is transport-free Python that any Python app can also embed in-process — no subprocess needed.

Why

Existing AI agent infrastructure assumes you're building a chat product. amplifier-agent is the opposite: it's an *engine you point other software at*. The CLI is the universal adapter — wherever you can shell out, you can use Amplifier.

The Mode A wire protocol is intentionally simple: the engine takes a single invocation (argv + env), runs one turn, and writes one JSON result envelope to stdout. Wrapper SDKs (TypeScript and Python) handle spawning, result parsing, and session continuity on top.

Install

The Python engine is not yet published to a package registry, but uv tool install installs it directly from git:

uv tool install git+https://github.com/microsoft/amplifier-agent
amplifier-agent doctor # verify environment

Pin to a specific engine release by appending a tag:

uv tool install git+https://github.com/microsoft/amplifier-agent@engine-v0.3.0

Engine and wrapper releases are tagged separately (engine-v0.3.0, wrapper-v0.4.0). For local development against a checkout, git clone the repo and run uv tool install -e . from inside it.

First-run will prepare the built-in bundle and cache it to $XDG_CACHE_HOME/amplifier-agent/. Subsequent invocations skip this step.

Quick start

Set a provider API key:

export ANTHROPIC_API_KEY=sk-ant-...

Run a one-shot turn:

amplifier-agent run "Summarize the README of github.com/microsoft/amplifier"

The TypeScript and Python wrapper SDKs handle subprocess management automatically. See wrappers/typescript/ (amplifier-agent-ts on npm) and wrappers/python/ for ready-to-use clients.

Provider configuration

Provider is auto-detected from environment variables in this precedence:

1. ANTHROPIC_API_KEY 2. OPENAI_API_KEY 3. AZURE_OPENAI_API_KEY + AZURE_OPENAI_ENDPOINT 4. OLLAMA_HOST (defaults to http://localhost:11434)

Override with --provider . No settings.yaml to maintain.

> Deprecated alias: AZURE_OPENAI_KEY (without _API_) is still accepted as a fallback for backwards compatibility and triggers a one-time stderr warning when used. Prefer AZURE_OPENAI_API_KEY — the legacy name will be removed in a future release.

Modes

| Mode | Invocation | Caller | Lifecycle | |---|---|---|---| | A (single-turn) | amplifier-agent run "prompt" | Shell scripts, wrapper SDKs, host adapters, ad-hoc CLI use | Spawn → one turn → JSON envelope on stdout → exit |

Multi-turn conversations are built by the caller: spawn one process per turn, passing --session-id for continuity. A persistent stdio JSON-RPC mode (Mode B) was originally designed but was superseded by the Mode A subprocess driver in PR #8 (see docs/designs/2026-05-24-aaa-v2-mode-a-pivot-amendment.md).

Session continuity

# First turn
amplifier-agent run --session-id chat-42 "My favorite color is blue."

# Continue the conversation
amplifier-agent run --session-id chat-42 --resume "What did I say my favorite color was?"

# Start fresh in the same session ID (overwrites prior transcript)
amplifier-agent run --session-id chat-42 --fresh "Start over."

Sessions are persisted as transcript JSONL in $XDG_STATE_HOME/amplifier-agent/sessions//. Continuity is per-session-id, not per-process.

Admin commands

amplifier-agent doctor # Diagnose env, providers, paths, bundle cache
amplifier-agent prepare # Pre-warm bundle cache (run once after install)
amplifier-agent verify # Verify install integrity
amplifier-agent config show # Print resolved config with source annotations
amplifier-agent cache clear # Invalidate the prepared-bundle cache
amplifier-agent --version # Print version

Approval flow

Some tools (file writes, command execution) request approval before acting:

• Interactive terminal: prompted on stderr; respond y to approve, anything else to decline
• Non-interactive (CI, pipe, background): denied by default
• Override: -y accepts all, -n denies all (apt-style)

Wrapper SDKs can install their own approval handler (callback, message-back, email, or anything else creative — adapter's choice) via the ApprovalSystem protocol point on the engine library.

Embedding in your own Python host

Skip the CLI entirely if your host is Python:

import sys
from amplifier_agent_lib import __version__
from amplifier_agent_lib._runtime import make_turn_handler
from amplifier_agent_lib.bundle.cache import load_and_prepare_cached
from amplifier_agent_lib.engine import Engine
from amplifier_agent_lib.protocol import PROTOCOL_VERSION
from amplifier_agent_lib.protocol_points.defaults_cli import CliApprovalSystem, CliDisplaySystem

prepared = await load_and_prepare_cached(aaa_version=__version__)
handler = make_turn_handler(prepared, cwd=None, is_resumed=False, mcp_config_path=None)

engine = Engine(
turn_handler=handler,
protocol_points={
"approval": CliApprovalSystem(mode="no"),
"display": CliDisplaySystem(verbosity="normal", stream=sys.stderr),
},
)
await engine.boot({
"protocolVersion": PROTOCOL_VERSION,
"clientInfo": {"name": "my-host", "version": "0.1.0"},
"capabilities": {},
"sessionId": "my-session",
"resume": False,
})
result = await engine.submit_turn({
"sessionId": "my-session",
"turnId": "turn-1",
"prompt": "Hello!",
})
await engine.shutdown()

Engine.boot() is an…