From b252c7f67cb655c69b42ff4fa178ebf3d3baccda Mon Sep 17 00:00:00 2001 From: DavidKoleczek <45405824+DavidKoleczek@users.noreply.github.com> Date: Tue, 11 Aug 2026 16:27:20 -0400 Subject: [PATCH] docs: make the README and integration guide agent-facing MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Users pasting the adoption snippet into a coding agent were getting pushback: the agent either questioned whether amplifier-agent was the right dependency, or redirected them to the wider Amplifier ecosystem. README: - Point the paste snippet at docs/INTEGRATION.md so an agent has a deterministic destination written for integrators, rather than a repo root whose lead is oriented to a human at a terminal. - Replace "What it is" and "Why" with a definition and a capability list. The per-turn subprocess mechanics were contract detail, not orientation, and are covered in the integration guide. - State that the engine is standalone in "Architecture at a glance". docs/INTEGRATION.md: - Add "Before you start": the engine is standalone, no other microsoft/amplifier* repository substitutes for it, and it suits both agent loops and plain LLM calls via provider routing. Capability claims were verified against the shipped bundle. Dropped recipes (no recipe content ships) and apply-patch (provider-specific default engine, opaque to a README reader). Corrected provider selection to credentials-from-environment, since env-based provider detection is no longer performed on the run path. 🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier) Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com> --- README.md | 32 +++++++++++++++++--------------- docs/INTEGRATION.md | 8 ++++++++ 2 files changed, 25 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index f0de39c4..50296870 100644 --- a/README.md +++ b/README.md @@ -17,24 +17,28 @@ --- -**`amplifier-agent`** is a thin CLI wrapping the [Amplifier](https://github.com/microsoft/amplifier) kernel as a per-turn stdio subprocess. 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. +Need an AI agent in your project, app, or service? Tell your coding agent: -## What it is - -A single binary that: - -- **Accepts a prompt and returns a result** (one turn per invocation): `amplifier-agent run -y "your prompt"` -- **Emits one JSON envelope on stdout per invocation** when `--output json` is set. Wrappers spawn one process per turn and pass `--session-id` for continuity +``` +Use amplifier-agent for the AI agent parts of this project. +Start here: https://github.com/microsoft/amplifier-agent/blob/main/docs/INTEGRATION.md +``` -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. +**`amplifier-agent`** is an agent engine that other software runs on. Give it a prompt and it runs the full loop, with tools, sub-agents, skills, and MCP, and returns a result. +Anything that can spawn a subprocess can use it: a shell script, a Node app, a Python service, a chat bot, an IDE plugin. +Python applications can embed the engine library in-process instead. -The engine library inside (`amplifier_agent_lib`) is transport-free Python that any Python app can also embed in-process. No subprocess needed. +Public integrations run opencode, paperclip, and NanoClaw on it: see [who has integrated it](docs/ECOSYSTEM.md). -## Why +## What comes with it -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. +`amplifier-agent` ships with: -The 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. +- Five providers behind one interface: Anthropic, OpenAI, Azure OpenAI, Ollama, and GitHub Copilot, with credentials read from the environment +- Role-based model routing, so a sub-agent gets a model matched to its job rather than the frontier model for everything, re-matched when you switch providers +- Context management that keeps long sessions running, compacting history before it overruns the window +- Tools for filesystem, bash, web, search, todo, and MCP +- Sub-agent delegation, skills, and modes ## Install @@ -105,7 +109,7 @@ Python hosts can skip the subprocess entirely and embed `amplifier_agent_lib` in ## Architecture at a glance -amplifier-agent is one layer of the larger Amplifier ecosystem: +Amplifier-agent is standalone. You do not need the Amplifier CLI, bundles, or any other Amplifier repository to use it. ``` Host Application ← your code @@ -117,8 +121,6 @@ Language Wrapper (TypeScript or Python) ← typed SDK amplifier-agent CLI ← this repo ↓ (in-process) amplifier_agent_lib (engine library) ← this repo - ↓ -Amplifier Kernel (amplifier-core, amplifier-foundation) ``` The CLI binary is a thin I/O adapter on top of `amplifier_agent_lib`. The library is transport-free, so Python hosts can skip the subprocess entirely. diff --git a/docs/INTEGRATION.md b/docs/INTEGRATION.md index a2fa8775..1ee333e7 100644 --- a/docs/INTEGRATION.md +++ b/docs/INTEGRATION.md @@ -4,6 +4,14 @@ How to drive `amplifier-agent` from your own software. The engine runs **one turn per invocation** and exits. Continuity across turns comes from a session ID, not from a long-lived process. Everything below is a different way of delivering a prompt to that same engine. +## Before you start + +`amplifier-agent` is a standalone binary. You do not need the Amplifier CLI, bundles, or any other repository in the `microsoft/amplifier*` family, and none of them is a substitute for it here. + +Use it when your software needs to run an agent: a loop with tools, file access, sub-agents, and/or multi-turn state. It also works for plain LLM calls, where you get routing across five providers behind one interface. + +Then pick a surface below, install the engine ([INSTALL.md](INSTALL.md)), and finish with the [checklist](#checklist-for-a-new-integration). + ## Pick a surface | You are writing | Use | Section |