Amplifier Agent

Install  •  Integration guide  •  Configuration  •  CLI reference  •  Who uses it

---

Need an AI agent in your project, app, or service? Tell your coding agent:

Use amplifier-agent for the AI agent parts of this project.
Start here: https://github.com/microsoft/amplifier-agent/blob/main/docs/INTEGRATION.md

Or install our skill, so your coding agent knows how to install and integrate the engine:

npx skills add microsoft/amplifier-agent

Alternatively, copy skills/amplifier-agent/SKILL.md into your agent's skills directory.

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. The engine is a library: a Python application adds it as a dependency and calls it in-process. Everything else reaches the same engine by spawning it or calling its HTTP face: a shell script, a Node app, a chat bot, an IDE plugin.

Public integrations run opencode, paperclip, and NanoClaw on it: see who has integrated it.

What comes with it

amplifier-agent ships with:

• Nine providers behind one interface: Anthropic, OpenAI, Azure OpenAI, Ollama, GitHub Copilot, ChatGPT (a Plus/Pro/Team subscription via OAuth device-code, no API key), Chat Completions (any OpenAI Chat Completions-compatible endpoint, e.g. llama.cpp, vLLM, LM Studio), Gemini (Google's Gemini API, large context windows plus thinking/reasoning support), and vLLM (a self-hosted or remote vLLM server via its OpenAI-compatible Responses API, for open-weight models like gpt-oss), with credentials read from the environment or a cached OAuth session
• 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

# Linux, MacOS
curl -fsSL https://raw.githubusercontent.com/microsoft/amplifier-agent/main/install.sh | bash

# Windows requires Git, Git Bash, and git long paths enabled
git config --global core.longpaths true
# Fill in C:\<Path To Git> with where your Git is installed
& "C:\<Path To Git>\Git\bin\bash.exe" -lc "curl -fsSL https://raw.githubusercontent.com/microsoft/amplifier-agent/main/install.sh | bash"

Installs the latest release and primes the bundle cache so your first run is instant. Requires uv, curl, and git; the installer tells you what is missing rather than bootstrapping silently. git is a runtime dependency too -- bundles and modules are fetched by cloning git repositories.

To review the script first, pin a version, install without the script, or uninstall, see docs/INSTALL.md.

Quick start

Set a provider key, then run a turn. The -y auto-approves tool calls, which is required in headless mode.

export ANTHROPIC_API_KEY=sk-ant-...

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

Provider is auto-detected from the environment in this order, first match wins:

ANTHROPIC_API_KEY  >  OPENAI_API_KEY  >  AZURE_OPENAI_API_KEY + AZURE_OPENAI_ENDPOINT  >  OLLAMA_HOST

For "set once, works everywhere" instead of editing shell rc files, persist credentials to ~/.amplifier-agent/credentials.json (mode 0600). Resolution stays env-first, so an exported variable still wins and existing workflows keep working:

amplifier-agent auth set anthropic sk-ant-...
amplifier-agent auth status              # diagnose env-vs-file precedence per provider
amplifier-agent models list              # enumerate available models from providers

Full precedence rules, GitHub Copilot's environment-only caveat, the chat-completions provider's required CHAT_COMPLETIONS_BASE_URL, and the host config file schema are in docs/CONFIGURATION.md.

Use it from your code

Both SDKs are BYO-engine: they spawn the amplifier-agent binary on your PATH and expose a typed async API. All inference, tool execution, and session state live in the Python engine.

TypeScript / Node.js (amplifier-agent-ts, Node 20+, zero runtime deps)

import { spawnAgent } from 'amplifier-agent-ts';

const session = await spawnAgent({ lifecycle: 'one-shot', sessionId: 'chat-42' });

for await (const event of session.submit('Hello, agent.')) {
  if (event.type === 'result') console.log(event.text);
}

Python (amplifier-agent-py, zero runtime deps)

from amplifier_agent_py import AaaError, spawn_agent_sync

with spawn_agent_sync(session_id="chat-42", approval={"mode": "yes"}) as handle:
    for event in handle.submit("Hello, agent."):
        if event.type == "result":
            print(event.text)
        elif event.type == "error":
            raise AaaError(event.code, event.message)

A Python host should embed amplifier_agent_lib directly rather than spawning anything. Start at the integration guide: it opens with a complete working embedding, then covers the wrappers for hosts that cannot embed, the wire protocol, session continuity, and approval policy for services.

Architecture at a glance

Amplifier-agent is standalone. You do not need the Amplifier CLI, bundles, or any other Amplifier repository to use it.

Host Application                              ← your code
    ↓
    ├─ import ───────────────────────────────────┐   Python hosts
    │                                            │
    └─ subprocess / HTTP                         │   everyone else
           ↓                                     │
       amplifier-agent CLI  /  HTTP face         │   ← this repo
       (argv in, JSON envelope out)              │
           ↓                                     │
    ┌────────────────────────────────────────────┘
    ↓
amplifier_agent_lib (the engine)              ← this repo

amplifier_agent_lib is the engine and the contract. The CLI binary is an argv and stdio adapter over it, the HTTP face is an OpenAI-compatible adapter over it, and the TypeScript and Python SDKs are subprocess clients for hosts that cannot import Python in-process. The library is transport-free, so a Python host skips every one of those layers.

Documentation

Document	Covers
Install	Install, pin, update, uninstall, offline and CI notes
Integration guide	Start here to build on the engine. Embedding the library, then the TypeScript and Python SDKs, HTTP face, wire protocol
Engine API	The library contract: turn assembly, Engine lifecycle, protocol points, spawn
Configuration	Providers, credentials, approval policy, host config file
CLI reference	Every command and flag, output and display modes, session continuity, skills and modes
Architecture	How the layers fit together and what runs where
Specifications	Normative contracts: wire protocol, envelope, host config, CLI, HTTP face
Ecosystem	Applications built on amplifier-agent
Known issues	Tracked defects and current limitations

Built with amplifier-agent

See docs/ECOSYSTEM.md for applications that run on the engine, and the integration shape each one uses.

Development

This repo is developed spec, e2e, and eval driven: there is no unit test tier, and the contract suite runs the real CLI and HTTP server against a realistic install inside an isolated container. DEVELOPMENT.md covers first-time setup, the make command surface, the four development skills, and the DTU and Gitea prerequisites those skills need.

Contributing

Note

This project is not currently accepting external contributions, but we're actively working toward opening this up. We value community input and look forward to collaborating in the future. For now, feel free to fork and experiment!

Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit Contributor License Agreements.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.

License

MIT. See LICENSE.

---

🤖 Built with Amplifier.