Capability-Driven AI Integration¶

Most integration projects start from the source API and ask "how do I expose this to my application?". Capability-driven AI integration flips the question: start from the AI surface — the tools, resources, and prompts an agent needs — and wire the spec backwards to the APIs (or mocks) that fulfill it.

This design pattern is one of the core reasons SDI works so well for AI: the spec is small enough to fit in an agent's context, deterministic enough to be trusted, and shaped exactly to the task at hand.

What is a capability?¶

Before we look at the design pattern, it helps to be precise about what a capability actually is. In SDI, a capability is more than an integration artifact — it is a standard container of business value, with a defined runtime model behind it.

The capability as a standard container of business value¶

Each capability encapsulates four dimensions that together define a complete, self-contained unit of organizational worth:

• Skills — the accumulated knowledge and expertise encoded in the capability: domain rules, data interpretation patterns, transformation heuristics, and the understanding of how upstream systems actually behave beyond their documented APIs. Skills answer how the integration reasons — the intelligence that turns raw data into meaningful, well-shaped output.
• Services — the concrete operations the capability performs, spanning the full spectrum from fully deterministic flows, through hybrid flows that interleave deterministic steps with LLM-mediated reasoning, up to fully agentic harnesses that hand control to an LLM under declared guardrails. Services answer what the integration does — its inputs, its outputs, and the orchestration logic.
• Events — the signals that trigger, inform, or result from the capability's execution: webhooks, state changes, notifications, and feedback loops that tie the capability into the broader operational landscape. Events answer when the integration acts and what happens as a consequence.
• Terms — the shared vocabulary and domain language that give the capability meaning: how concepts are named, what upstream systems it connects to, what authentication and compliance boundaries apply, and what organizational constraints shape its behavior. Terms answer how this integration is expressed — making all other dimensions intelligible.

A capability specification is the declarative document that captures all four dimensions in a single place. It is self-contained and human-readable, without requiring knowledge of the underlying implementation. In practice, this means a structured YAML document that describes skills, services, events and terms — along with the authentication, protocol mappings, and transformation logic that connect them. The spec is the integration — not a description of it.

This framing matters because it aligns integration boundaries with business boundaries. When a capability maps to a recognizable unit of business value — not just an API endpoint or a data pipeline — it becomes something the organization can reason about, prioritize, govern, and standardize at the right level of abstraction. Capabilities still deliver context as a first-class output: when exposed via the Model Context Protocol (MCP), each capability provides AI agents with structured, well-scoped context — turning integration surfaces into context surfaces. The same capability can be projected through Agent-to-Agent (A2A) for multi-agent collaboration, through REST for traditional consumers, or through classic query protocols like SQL and GraphQL — one specification, many surfaces.

The Capability Engine¶

For specifications to be executable, a runtime must interpret them directly. Rather than generating code from a spec (which reintroduces drift), the engine reads the specification at runtime and handles all integration concerns: HTTP consumption, data transformation, format conversion, and exposure via REST, MCP, A2A, or classic query interfaces such as SQL and GraphQL.

Derived artifacts — client SDKs, human-readable documentation, validation schemas — are still generated, but always from the capability spec, which remains the single source of truth. Combined with GitOps workflows, this ensures that every derived artifact stays traceable to a specific spec version, and drift is caught as a diff rather than discovered in production.

Packaging this engine as a self-contained container means any capability specification can be deployed without build pipelines, language runtimes, or bespoke infrastructure. The engine is the stable layer; the specification is the variable one.

The Capability Ship¶

A single engine runs a single capability. In practice, organizations group related capabilities into a shared hosting integration partition — a ship. Because every capability conforms to the same specification standard, ships can load, schedule, and run any combination of them without custom integration work — much as a container ship carries diverse cargo in uniform containers. A ship is an independently operated runtime cell that hosts many capability-containers at once, with its own network edge, identity and secrets domain, telemetry, and policy enforcement.

This standardized container format is what makes co-location practical: capabilities from different teams or domains can share a ship's resources while remaining individually versioned, deployable, and replaceable. Grouping capabilities into ships provides a natural isolation boundary: each ship can be scaled, secured, and governed as a unit, without requiring global coordination for every change.

The Capability Fleet¶

Ships, in turn, are organized into a federated layer for enterprise enforcement and traceability — a fleet — that manages capabilities across teams, regions, and compliance boundaries. The Fleet coordinates placement, routing, and policy rollout across ships, providing global visibility through a manifest that tracks what is deployed, where it runs, and whether it conforms to organizational policy. Governance is structural: identity-based access controls, automated compliance gates, and immutable audit trails are applied uniformly across the fleet rather than configured per ship or capability.

This matters because scaling specifications without scaling governance reintroduces the drift and fragility that specifications were designed to eliminate. The Fleet ensures that as the number of capabilities and ships grows, operational consistency grows with it — turning a collection of individual integrations into a managed supply chain of business value.

The pattern in one picture¶

   Step 1                Step 2                  Step 3
   ──────                ──────                  ──────
   Author the            Mock the                Wire to real
   MCP / Skill tool   →  outputs with         →  APIs via consumes +
   schema first          static `value:`         `call` + `mapping`

Result: the agent works from day one, before any backend is migrated. The contract is locked in YAML; the data source is a swappable detail.

Why start from the AI side¶

The capability-driven checklist¶

When designing a new capability for an AI use case, work through these in order:

1. Name the task. Not the API — the agent task. "Plan a voyage." "Resolve a customer." "Score a lead."
2. Sketch the MCP tools. What does the agent ask for, and what does it expect back? Write the tools: block first.
3. Mock the outputs. Use value: (static + Mustache templates) so the agent can be wired up before any backend exists.
4. Add consumes last. Once the contract is stable and the agent works, swap value: for mapping: and connect a real API.
5. Right-size the output. Drop fields the agent does not need. Add description: to every tool, every input, every output.

Steps 1–3 are the Tutorial Track 1, Steps 1–2 in a nutshell.

How Ikanos supports the pattern¶

Closing the loop with deterministic linting¶

Capability-driven AI integration creates a recursive setup: an agent reads capabilities, and increasingly an agent writes them. Mock outputs evolve into real mapping: blocks; tools: schemas get extended as new tasks appear; consumes adapters get added when a backend lands. Much of this editing happens inside generate-validate-retry loops, with an LLM proposing changes to the YAML.

The risk is familiar: the LLM produces a spec that parses and even passes schema validation, but breaks a capability invariant — a duplicated port, a call referencing a non-existent operation, an input declared but unused, an MCP tool shipped without a description:. In a capability-driven workflow, where the spec is the AI contract, these flaws are exactly what the pattern is meant to prevent.

This is why deterministic, capability-aware specification linting is a peer concept to the capability engine itself: the engine guarantees the spec runs the same way every time; the linter guarantees the spec is worth running in the first place. In the Naftiko stack, Polychro fills this role — embeddable in agent loops as an MCP server, runnable as a CLI or GitHub Action in CI, and shipped with rulesets that already understand capability domain invariants (naming, security, cross-object consistency, unused inputs, dangling references, …).

The practical pattern is the same one used everywhere else in SDI: keep the agent on one side, the deterministic tool on the other, and let the specification be the only thing that crosses the boundary.

Anti-patterns to avoid¶

Read next¶

• Tutorial — Track 1: Context Engineering — the canonical capability-driven walkthrough
• Use Cases — see the pattern applied across different scenarios
• Ikanos schema — MCP exposes
• Polychro — deterministic linting for agent-generated capability specs