Adopt Anvil across a platform
Anvil is useful at platform scale only if ownership stays explicit.
- The API owner owns business meaning.
- The platform team owns Anvil, CI, runtime patterns, and delivery.
- Security owns policy for sensitive exposure and execution.
- The agent team consumes approved capabilities. It does not approve them.
Do not ask the platform team to guess whether a call is safe. Do not ask every service team to build its own CLI, MCP server, SDK, and skill. Keep semantics with the service owner. Generate the surfaces centrally.
Pick a pilot that can fail for a useful reason
Section titled “Pick a pilot that can fail for a useful reason”Choose one service with:
- a real mutation with a visible consequence;
- an owner who can answer auth and idempotency questions;
- a usable API contract, or a gateway export plus the authoritative contract; and
- a mock or non-production endpoint for executable checks.
A read-only demo proves parsing. It does not prove the review model.
A refund, provisioning action, or case update forces the team to answer the questions that matter: who may call it, what must be confirmed, and what happens on retry.
For a legacy queue, EJB, or WCF endpoint, include the middleware owner. A reviewed binding is still only a design artifact until a deployment-local adapter exists and passes assurance.
Know when the pilot is done
Section titled “Know when the pilot is done”The pilot is done when the team can reproduce:
- the exact source bytes Anvil compiled;
- the evidence behind every exposed operation;
- the calls the runtime will refuse;
- the checks required before release;
- the operator action that performs deployment; and
- the response to source or policy drift.
Generated tool count is not an exit criterion.
Adoption path
Section titled “Adoption path”1. Capture the source
Section titled “1. Capture the source”Keep content-addressed source snapshots.
For gateway exports, inventory and audit the estate before importing individual APIs. Do not flatten a gateway estate into one tool catalog.
2. Build a candidate
Section titled “2. Build a candidate”Use anvil agentify for an unfamiliar API. It captures the source, compiles it, assesses operations, proposes capability groups, and stops for review.
For legacy configuration, inventory first. The result is evidence and a candidate binding. It is not a runtime.
3. Add facts the owner can defend
Section titled “3. Add facts the owner can defend”Keep anvil.yaml beside the source contract.
Record stable names, idempotency, confirmation, auth posture, retry constraints, and authored workflows. Review the manifest like code because it changes what agents may call.
4. Approve the smallest useful set
Section titled “4. Approve the smallest useful set”Approval changes exposure in the CLI, MCP server, and SDKs.
Approve only the operations needed for the use case. Reviewing one operation is not evidence for approving the whole service.
5. Verify one bundle hash
Section titled “5. Verify one bundle hash”Run certification, self-test, conformance, and simulation against the same bundle.
If target or ledger artifacts become part of the certified bundle, generate them before the final assurance pass.
anvil publish creates an operator plan. Your delivery system still owns credentials, provider mutations, rollout, and rollback.
6. Reconcile drift
Section titled “6. Reconcile drift”Recompile or run anvil sync when the source changes.
Not all diffs mean the same thing. A description edit, a removed confirmation rule, and a wider auth scope deserve different review. Review semantic drift, not just changed lines.
Ownership table
Section titled “Ownership table”| Decision | API owner | Platform | Security / risk | Agent team |
|---|---|---|---|---|
| Maintain source contract | Owns | Supports | Reviews material changes | Consumes |
| Supply missing semantics | Owns | Provides schema and tools | Reviews safety-sensitive claims | Provides use cases |
| Approve exposure | Consulted | Runs the workflow | Owns sensitive-operation policy | Never self-approves |
| Build and verify bundle | Supports | Owns | Defines required gates | Consumes records |
| Deploy runtime | Provides upstream coordinates | Owns | Reviews IAM and egress | Registers endpoint |
| Resolve drift | Owns source change | Runs detection | Reviews safety loosening | Revalidates workflows |
| Confirm legacy binding | Consulted | Coordinates middleware owner | Reviews exposure | Does not infer semantics |
| Operate legacy adapter | Supports behavior | Owns adapter lifecycle | Reviews identity and network | Consumes approved surface |
Fit Anvil into controls you already have
Section titled “Fit Anvil into controls you already have”| Existing control | Anvil artifact or gate |
|---|---|
| Source provenance | Content-addressed source snapshot |
| Change review | Manifest and capability decision in the service repository |
| Least privilege | Only approved operations enter callable surfaces |
| Separation of duties | Explicit operation review and human-approval policy |
| Release evidence | Hash-bound certification, self-test, conformance, and simulation records |
| Change detection | Semantic drift report that separates policy changes from documentation changes |
| Secret management | Credential contract with names and references, never values |
| Runtime egress | Reviewed host policy plus platform network controls |
Anvil should plug into source review, identity, secrets, deployment, and incident response. Do not build a second control plane around it.
Roll out in three steps
Section titled “Roll out in three steps”- One service.
- One owning team.
- One consequential mutation.
- One approved capability.
- One mock or non-production runtime.
- One written list of unresolved gaps.
Template
Section titled “Template”- Put source capture, compile, lint, and assessment in CI.
- Keep approval as a reviewed change.
- Require the same assurance gates for every bundle hash.
- Standardize runtime identity, secret references, egress, and telemetry.
- Publish one service-repository example.
- Require a written ownership contract for onboarding.
- Publish approved bundles and skills through the catalog you already operate.
- Keep estate inventory separate from operation approval.
- Track failures by source, review, assurance, deployment, and runtime stage.
Measure the work that matters
Section titled “Measure the work that matters”Track:
- time to first approved capability;
- percentage of candidate operations still in
review_required; - review latency by missing claim type;
- assurance failure rate by lane;
- time to resolve blocking drift;
- percentage of live runtimes with current bundle evidence; and
- incidents caused by wrong source or manifest claims.
Do not optimize generated tool count. A useful capability has an owner, a reviewed contract, current evidence, and an operated runtime.