There’s a tension at the heart of agentic integration. The reason to let an AI agent build integrations is speed — it drafts a working tool as fast as you can describe it. The reason enterprises hesitate is trust — you can’t hand software that’s seconds old the keys to your order system, your CRM, or your payment API.
The usual fix is to rein the agent in with approvals on every step until the team feels comfortable. That trades away the very thing you adopted the agent for, and buys a feeling of safety rather than a guarantee. The better fix: let the agent run at full speed where speed is free of consequence, then move the artifact it produced — not the agent — through a few deterministic gates.
That is the capability lifecycle: three stages, two human gates, and one property that makes it cheap — the reviewed contract never changes shape as it moves.
Stage 1 — Craft at agentic AI speed, on mocked sources
Given a goal and some source API specs, the agent drafts a capability: what it consumes upstream, what it exposes to the model, how inputs and outputs are shaped, where the guardrails sit. This is the fast, throwaway-friendly part — and it runs entirely against mocked sources and mocked data.
The important word is runs. A mocked capability isn’t a sketch waiting to be implemented — it’s a working server on the developer’s machine. Serve it, point an MCP client or the agent itself at it, call the tool, see the exact payload the model will receive. That closes a real test loop at developer level: the signature gets exercised, the output shape gets inspected, and the agent reveals that the field it needs is missing or the shape is awkward — all before a single real system is involved.
That’s what makes the stage cheap. No credentials are in play, so there’s nothing to leak, and a mock has no rate limit, no cost, and no way to corrupt a real record. Mocks aren’t a compromise; they’re the fastest correct place to find out you designed the wrong tool.
ikanos: "1.0.0-beta2"
info:
display: "Support Order Lookup"
description: "Find a caller's most recent order and its live status"
tags: [Support, Orders]
capability:
# No `consumes` block at all — mock mode. Nothing to authenticate,
# nothing to leak, no upstream to hit.
exposes:
- type: mcp
port: 3001
namespace: support
tools:
lookup-order:
inputParameters:
phone: { type: string, required: true }
outputParameters:
- type: object
properties:
# Mustache templates resolve against the tool's inputs.
orderId: { type: string, value: "ORD-{{phone}}" }
status: { type: string, value: "in_transit" }
eta: { type: string, value: "2026-08-02" }
The output isn’t a running integration — it’s a candidate capability.yaml, a declarative artifact describing exactly what the capability will consume and expose. That artifact moves forward. The agent’s chat history, dead ends, and retries do not. Only the shape that survived testing does.
Gate 1 — Review the YAML, not the agent
The capability’s entire behavior is legible before it touches a real system — and by now it’s been run against mocks, so the reviewer isn’t reading a hypothesis. They don’t replay the agent’s reasoning or audit generated code; they read one YAML file and answer plain questions: What does it consume, and nothing more? Is the exposed surface right-sized or a raw API dump? What does the output shape reveal, and what does it correctly leave out? Where are the masking and validation?
It’s a pull-request review, not security theater: a small, human-readable diff in version control that “shifts left” into the process teams already own. Approving it means one thing — the declared behavior is acceptable.
Stage 2 — Staging on synthetic data
Staging is where the capability meets data that looks like reality without being it: staged APIs carrying synthetic data, generated from the shape of production data but with no real customer, PII, or money. Promotion is deliberately mechanical: point the capability at a real source, swap mocked values for mappings against what actually comes back. The tool signature and output shape don’t move — the contract approved at Gate 1 survives the switch from mock to wire.
From here the capability YAML is stable and the environment moves around it. Secrets never live in the spec; they’re declared in binds and resolved per environment:
# Same capability.yaml. Only the bind location changes per environment.
binds:
- namespace: registry-env
location: "${BINDS_LOCATION}" # dev: file:// · staging: vault://
keys:
ORDERS_TOKEN: "orders-bearer-token" # staging scope: orders:read
CRM_TOKEN: "crm-bearer-token" # staging scope: customers:read
This is what makes the promotion cheap and safe. You aren’t re-authoring anything or asking the agent to regenerate — you’re running the already-reviewed behavior against realistic-but-synthetic data to confirm it holds up: pagination, shape mapping, error handling, latency. Because the behavior is declared rather than improvised, staging is a validation step, not a discovery step.
Gate 2 — Bind least-privilege keys, with trust
Here’s what every security team is really asking: when do the real credentials get attached, and on what basis? Not before now. Only after the capability has proven its declared behavior on synthetic data are the real keys injected and the capability pointed at the golden sources — the systems of record holding the authoritative data. Those golden sources are why the gate exists: they’re where a wrong call becomes a duplicated order, an overwritten record, or a real charge.
# Same capability.yaml. Production resolves the same bind namespace
# from a vault, with least-privilege scopes.
binds:
- namespace: registry-env
location: "vault://kv/data/support/prod"
keys:
ORDERS_TOKEN: "orders-bearer-token" # scope: orders:read
CRM_TOKEN: "crm-bearer-token" # scope: customers:read
capability:
consumes:
- namespace: orders
baseUri: "https://orders.internal/v1" # golden source — system of record
authentication: { type: bearer, token: "ORDERS_TOKEN" }
- namespace: crm
baseUri: "https://crm.internal/v2" # golden source — system of record
authentication: { type: bearer, token: "CRM_TOKEN" }
Binding is also the moment to make the keys as small as possible — narrowed to the exact operations the capability declared, and nothing more. A capability that reads orders and looks up a customer holds a read-scoped orders token and a lookup-scoped CRM credential, not a broad admin key that happens to work. This tightens at every stage: no credential on mocks, non-production scopes in staging, minimal production scopes only here. The reason is blast radius — the exposes side is a live surface, and any exposed port is one a rogue or compromised client might reach. When that happens, the damage is bounded by exactly what the bound credential can do. A narrow key keeps a breach small; a broad “to be safe” key quietly widens the impact radius of every client that finds the port.
And you can bind those keys with trust rather than a leap of faith:
- Deterministic. The capability does what its YAML declares — same inputs, same upstream calls, same shaped output, every time. The agent’s non-determinism lives above the capability; the capability itself is a fixed contract.
- Traceable. Every call can be followed from the agent, through the capability, to the golden source and back — one span per hop, metrics per operation — because there’s exactly one declared surface to instrument.
- The golden source stays authoritative. The capability points at the system of record rather than copying it, so it never forks a stale shadow.
The keys aren’t attached to something you hope will behave, but to something whose behavior was read, run on synthetic data, and signed off first.
“But my systems aren’t clean REST APIs”
Everything above used tidy JSON endpoints, which is not what most enterprises have. The real estate is a SOAP service from 2009, an XML feed, a CSV drop, and a system whose owner retired. Any lifecycle that only works on greenfield APIs isn’t solving the enterprise problem.
Format is the tractable part. A capability normalizes non-JSON payloads before mapping — declare the inbound format, and conversion stops being your problem:
capability:
consumes:
- type: http
namespace: legacy
baseUri: "https://legacy.internal/vessels"
produces: application/xml # the payload is XML; the mapping below is not
resources: { ... }
One line, and a legacy XML system maps into the same flat, right-sized tool shape the agent already knows — SOAP-over-HTTP, RSS/Atom, fixed-format exports all land here. The point isn’t the format list: it’s that the shape the agent sees is decoupled from the shape the legacy system emits, and the mapping between them is declared and reviewable.
Reachability is the next objection. Legacy systems usually have no public endpoint, and shouldn’t get one. The direction is outbound-only connectivity — the capability reaches the system, rather than the network opening a door for it.
And the honest part: this is a direction, not a finished product. Some sources are reachable today, others aren’t yet, and some of the resilience and governance machinery this model implies is still ahead of us. What matters is the shape of the solution — a reviewed, declarative artifact between the agent and the golden source — because that’s what stays stable while the surrounding pieces mature.
Where determinism belongs — the red line the agent can’t cross
There’s a subtler question underneath the gates, and it’s the one Jean-Jacques Dubray — decades in B2B standards and state machines, now building the Polygraph verification layer — pressed hardest: where should the determinism live? An agent given a loose goal is powerful, but every degree of freedom is a degree of freedom to find an unwanted path. His warning: even a spec that never explicitly permits something dangerous can be walked, step by allowed step, into a harmful outcome.
A capability answers part of this by construction. Because it declares exactly what it consumes and exposes, the agent above it can’t invent a new upstream call, reach an unnamed system, or leak a masked field — the set of moves is exactly the set the reviewer approved. But Dubray’s stronger point is that allowed calls and safe sequences aren’t the same thing. The second deserves its own layer, best expressed as a human-legible invariant — a red line in a sentence: “a customer is never charged twice,” “an order is never shipped before it is paid.” You define the unsafe states ahead of time and stop before the final harmful step, rather than trusting one LLM to supervise another — which isn’t deterministic enough to be the final trust layer.
So the gates give a human a place to read the shape and bind the keys; invariants give the running system a red line it won’t cross no matter what sequence the agent discovers. The result is a secure harness — a goal-oriented agent free to maneuver inside boundaries that are guaranteed, not merely hoped for.
Why the trust cost stays flat
The lifecycle is affordable — not just safe — because you pay the trust cost once. The YAML describes what the capability does; it says nothing about how bytes move on the wire — MCP transport, sessions, auth mechanics, schema validation. That all lives in the engine. So when the MCP protocol revises — and it does, breakingly — or the engine ships a fix or a CVE patch, the YAML you approved is untouched.
The governance consequence is direct. With hand-built or generated servers, every protocol change is code that touches the wire, so every server goes back through review and recertification — the cost lands once per server, every time. In the capability model, a protocol or engine fix is a single reviewed engine upgrade, and every capability rides through with its reviewed behavior intact. You don’t re-open Gate 1 or Gate 2 because a header changed. Governance is spent on the artifact, not re-spent on the plumbing.
The sharpest version is a CVE. When a vulnerability lands in a transport library or a TLS stack, the hand-built estate has to patch, re-test, and re-certify every server — under a disclosure clock. In the capability model that dependency lives in the engine: one version bump across the fleet, not a single capability.yaml changed, nothing re-entering review. “Are we patched?” becomes a version check rather than an audit, and security maintenance stops scaling with the number of integrations you own.
The shape of the whole thing
| Stage | Sources | Data | Credentials | Gate to pass |
|---|---|---|---|---|
| 1 · Mock | Mocked | Mocked | None | — craft and test freely |
| 2 · Staging | Staged APIs | Synthetic | None real | Gate 1 — review the YAML |
| 3 · Production | Golden sources | Real | Least-privilege, bound at the gate | Gate 2 — bind real keys |
The agent moves at full speed where consequences are zero. The artifact it produces moves through two small, human-readable gates. The keys attach last — least-privilege, fenced by red lines the agent can’t cross. And because the reviewed contract rides through unchanged while the engine absorbs the protocol churn and the CVE patches beneath it, the trust you build is established once and stays cheap.
That is the point of a capability: not that an agent can build an integration quickly, but that the fast thing it builds becomes a secure harness you can move into production with trust you can price, review, and keep.
