Skip to content

docs: make the README and integration guide agent-facing - #118

Merged
David Koleczek (DavidKoleczek) merged 1 commit into
mainfrom
docs/agent-facing-readme-integration
Aug 11, 2026
Merged

docs: make the README and integration guide agent-facing#118
David Koleczek (DavidKoleczek) merged 1 commit into
mainfrom
docs/agent-facing-readme-integration

Conversation

@DavidKoleczek

@DavidKoleczek David Koleczek (DavidKoleczek) commented Aug 11, 2026

Copy link
Copy Markdown
Collaborator

Why

  • The snippet pointed at the repo root, whose lead is written for a human at a terminal (install, export a key, run a prompt). An agent asked to integrate this into a codebase had no destination written for it, so it improvised.
  • Nothing stated that the engine is standalone, so an agent that searched the name found a large multi-repo ecosystem and reasonably concluded this was a sub-piece of it.
  • No fit criteria, so an agent evaluating an unfamiliar dependency defaulted to suggesting one it already knew.

Changes

README

  • The paste snippet now points at docs/INTEGRATION.md.
  • What it is and Why are replaced by a definition plus a capability list. The per-turn subprocess mechanics were contract detail rather than orientation, and are already covered in the integration guide.
  • Architecture at a glance states that the engine is standalone.

docs/INTEGRATION.md

  • New Before you start section: 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.

Accuracy

Capability claims were checked against the shipped bundle rather than carried over:

  • Dropped recipes. tool-recipes is mounted, but no recipe content ships and only #subdirectory=modules/tool-recipes is pulled in, so the upstream examples do not resolve for a user.
  • Dropped patching. tool-apply-patch defaults to the native engine, which is a host-side handler for the OpenAI Responses-API built-in tool. Provider-specific, and opaque to a README reader.
  • Corrected provider selection to credentials-read-from-environment. Env-based provider detection is no longer performed on the run path; resolution is host config, then default_provider.
  • Kept modes and skills, both of which ship real content and have test coverage.

Follow-ups (not in this PR)

  • README.md quick start and docs/CONFIGURATION.md both document an auto-detection order that the run path no longer performs, and both omit github-copilot.
  • bundle.md sets visibility.enabled: false for tool-skills while the adjacent comment claims visibility is enabled.

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>
@DavidKoleczek
David Koleczek (DavidKoleczek) merged commit fc576ad into main Aug 11, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant