amplifier-agent

Amplifier Agent integration

Build against the public bindings and their docs. Read the linked page before writing API calls. Prefer docs/ in a matching local checkout when one exists.

Docs root: https://github.com/microsoft/amplifier-agent/blob/main/docs/index.md

Versions

Links and file paths here use main. Installs use a release tag; when the installed tag differs from main, read the docs at that tag.

Before upgrading an integration, read CHANGELOG.md from the installed version to the target and apply every Breaking entry.

Pick a surface and install

Follow install and providers. amplifier-agent-ts versions before 0.20.0 on npm are an older, incompatible API. Install the Python binding as amplifier-agent[github-copilot] unless the user asks otherwise; do not ask them whether to include the extra.

Python      Python 3.12-3.14, uv add from a release tag  docs/python/{quickstart,names,reference}.md
TypeScript  Node 22, ESM; Linux x86-64 with glibc 2.35+   docs/typescript/{quickstart,names,reference}.md
            or macOS 11+ on Apple silicon;
            npm install amplifier-agent-ts
HTTP        chat-completions server amplifier-agent-face  docs/http/{quickstart,reference,turns,limits}.md
ACP         stdio executable amplifier-agent-acp          docs/acp/{quickstart,reference,limits}.md
            started by an ACP editor

• TypeScript options are camelCase; received records keep snake_case spelling (session_id, call_id), except ImagePart.mediaType. Counters are bigint, costs are decimal strings.
• HTTP carries less than a binding: no caller tools. Chat completions carries reply text and reasoning only; /v1/amplifier/turns streams every event and, with "approvals": "ask", takes approvals over HTTP. Requests may pick <provider>/<model> and reasoning_effort, and an Amplifier-Session-Id header keeps a durable session on the server. Its tools run under a static policy from AMPLIFIER_AGENT_APPROVALS, "approvals" in the config file, or create_app options; with tools and no policy the server refuses to start. All clients share the server's tools, filesystem, and credentials. Each response carries one usage summed across the turn. The face binds 127.0.0.1; set AMPLIFIER_AGENT_FACE_BIND to serve from a container.
• ACP carries less than a binding: no caller tools. The editor starts amplifier-agent-acp with no arguments; provider, model, and credentials come from its environment (the editor's env for the agent), never from keys the editor stores for its own models. Each ACP session is a durable session in the editor's cwd. Unless AMPLIFIER_AGENT_APPROVALS is allow or deny, the session's approvals picker decides: ask, allow-reads (the default: reads and searches inside the session's directories run, every other call is a permission request), or allow-all. Results carry a diff per changed file. The editor's model picker switches <provider>/<model> and reasoning effort.

Add the ACP face to an editor

Follow the ACP quickstart. The editor starts the face as a custom agent; it needs uv where the agent runs (uv --version):

command   uvx, as an absolute path such as /home/<user>/.local/bin/uvx when the editor starts it in WSL or remotely
args      --from git+https://github.com/microsoft/amplifier-agent@v0.26.2#subdirectory=packages/acp amplifier-agent-acp
env       AMPLIFIER_AGENT_PROVIDER, AMPLIFIER_AGENT_MODEL, and that provider's credential variable

• Add the entry to the editor's custom agent settings, merged into any existing entries. When the editor runs the agent in WSL or on a remote machine, use which uvx on that machine for command. Restart the editor after a change; the first start is slow while uvx fetches the package.
• The settings are plain text. Ask before writing a credential into env.
• AMPLIFIER_AGENT_APPROVALS: "allow" in env runs every tool call without asking and removes the approvals option.
• Skills: AMPLIFIER_AGENT_SKILLS in env, comma-separated, or "skills" in ~/.amplifier-agent/config.json. Personal instructions: ~/.amplifier-agent/AGENTS.md.
• Verify with one prompt in a new thread. A sign-in prompt, error -32000, means the provider's credentials are missing from the agent's environment.

Build the integration

1. Construct the agent with provider, model, and instructions. instructions replaces the default system prompt; start from it and adapt it to your use case. The user's AGENTS.md beside the host configuration file, then AGENTS.md files from the repository root to the working directory, are still appended; see AGENTS.md. Configuration is captured at construction; recreate the agent after changing credentials. See configuration and models. With no provider configured, the first provider with credentials is used, with its default model. Set both provider and model to choose one. An unavailable model is reported by the first turn, not at construction. For a provider or model picker, call list_providers / listProviders and list_models / listModels; they need no agent. See discovering providers and models. reasoning_effort (reasoningEffort in TypeScript) sets reasoning from none to max, default "medium". Session and turn values replace it, even when higher. A list_models record's reasoning_efforts lists the values its model accepts. The HTTP face reads AMPLIFIER_AGENT_REASONING_EFFORT at start and reasoning_effort per request. Never set effort in extra_request_params; it is refused.
2. Sessions are durable by default. To resume, keep the session ID and sessions directory, and rebuild tools and approvals. Resumed and forked sessions keep their provider, model, and reasoning effort. session.set_model(provider, model, reasoning_effort=None) (TypeScript session.setModel({ provider, model, reasoningEffort })) switches them between turns and keeps the conversation; the new provider's credentials must be present when the agent is created. session.info reports the current selection. See switching models. Use ephemeral sessions for disposable work or caller-supplied history. One turn at a time per session.
3. session.run returns a final result; start_turn / startTurn streams. See turns.
4. Check both a raised AgentError and the terminal TurnResult.state / error, and surface code, message, and remedy; the remedy names the fix. Returned text alone is not success. See errors. Long conversations are compacted automatically; context_exceeded means even that did not fit, so start a new session.
5. Close agents and sessions with context managers or finally. To stop a streaming turn, call cancel() and drain to terminal; leaving the loop does not cancel. An open TypeScript agent keeps the Node process alive.
6. Images go inline as base64 image parts (png, jpeg, gif, webp) in input content or user messages; over HTTP, as image_url parts with data: URLs. Output is text. image_unsupported means the model or provider cannot take them; choose another model or remove the images. The failed turn's images become one-line descriptions in the conversation, so the session continues. Images are sent as given, with no size limit or resizing; a provider's size refusal fails provider_failed. See providers.

Tools and approvals

Read tools, approvals, and, for reusable instructions and named agents, skills.

• tools is the whole set. Omitted, it is every built-in; [] is no tools; keep the built-ins and add yours with [*BUILTIN_TOOLS, mine] / [...BUILTIN_TOOLS, mine]. Built-ins run with the host process's permissions. With both edit_file and apply_patch in the set, gpt- models other than gpt-4 and oss are offered apply_patch and every other model edit_file.
• Every tool call, including reads and MCP, needs an approval handler or a static "allow" / "deny" policy. AgentOptions.approvals wins; otherwise the host's AMPLIFIER_AGENT_APPROVALS or config file "approvals" applies. Without one, tool requests fail with approval_unavailable. "allow" permits every effect, including writes and shell; "deny" refuses each one.
• A handler receives request.arguments, exactly what the tool will receive; decide on it and show request.summary, the bounded, redacted preview. A deny does not end the turn: the tool does not run, the model gets an approval_denied result carrying the response's reason, and continues. Give a reason that says what is allowed instead. Answer cancel to end the turn.
• working_directory / workingDirectory is where built-ins, bash, and stdio MCP servers work. Absent, the process's current directory. environment adds per-agent variables, including provider credentials, without changing the process environment.
• sessions_directory holds stored sessions. Absent, it is computed from the working directory, so resume from the same directory or set it. It is not a sandbox.
• Ordinary tool errors, and arguments that fail the tool's schema (invalid_input, the handler never runs), return to the model and the turn continues. Set tool_error_policy="stop" / toolErrorPolicy: "stop" to end the turn on the first.
• Caller tools need a unique name, a JSON Schema with $schema, and a handler. Report known failures with ToolFailed and uncertain effects with ToolOutcomeUnknown; never retry an unknown outcome. A handler returns a string, or a list of text and image parts; events describe each image in one line, never its bytes.

Streaming UI

Use events and usage. Each turn's stream has one consumer. Correlate tools by call_id and approvals by request_id. Render output_delta parts or the terminal content, not both. Usage events replace the previous snapshot; do not sum them. A progress event with context.compacted reports compaction. A stream without terminal is incomplete.

Examples

examples/ holds complete applications on the public surface. examples/python/llm-wiki/ runs many sessions in parallel with caller tools, an approval handler on request.arguments, skills, streamed events, and usage totals. Every library call is in its llm_wiki/agent/.

Verify

Run one small live turn, one failure path, and cleanup. With tools or streaming, also exercise an approval denial and a cancellation. Live turns need credentials and cost money.

Source inspection

Optional, for diagnosing behavior. Keep application code on the public surface; engine internals and upstream module APIs are not the public interface. There is no amplifier-agent CLI.

git clone --depth 1 --single-branch --branch v0.26.2 \
  https://github.com/microsoft/amplifier-agent.git "$(mktemp -d)/amplifier-agent"

Start at docs/development/architecture.md. Upstream module revisions are in packages/engine/pyproject.toml and uv.lock.