Composable Agent Specs: Spec Delegation and the OAS Registry

Scotty G — Mon, 20 Apr 2026 00:31:19 +0000

Most agent frameworks solve reuse the way libraries do: write a class, import it, hope the abstractions line up. That works inside one codebase. Between teams or across organisations? It breaks down fast.

Open Agent Spec 1.4 takes a different approach.One agent spec can delegate a task to another spec, loaded from a local path, a URL, or a public registry:

tasks:
  summarise:
    spec: oa://prime-vector/summariser@1.0.0   # version-pinned, from registry
    task: summarise

One line. Version-pinned. No copy-paste. Your pipeline gets a battle-tested summariser without importing anything.

Why spec composition matters

An agent that fits in one YAML file is easy. But as soon as you build a second agent that needs the same summarisation step, or the same sentiment classifier, or the same document-extraction task — you start copy-pasting.

The usual fix is to wrap the shared logic in a Python function. But now the agent definition is split across YAML and Python, the function drifts from the spec over time, and you're back to the problem OAS was meant to solve: agent logic spread across framework abstractions you can't review in a PR diff.

Spec composition keeps the contract in YAML.

Three ways to delegate

A delegated task declares spec: + task: instead of its own prompts and output schema. The runtime loads the referenced spec, runs the target task, and surfaces the result transparently.

1. Local file

For intra-repo reuse:

tasks:
  summarise:
    spec: ./specs/summariser.yaml
    task: summarise

The path resolves relative to the calling spec's directory. Useful when you have a shared specs directory in a monorepo.

2. HTTP/HTTPS URL

For cross-repo reuse without a registry:

tasks:
  summarise:
    spec: https://raw.githubusercontent.com/your-org/agents/main/summariser.yaml
    task: summarise

Any spec reachable over HTTP works. Good for internal GitHub-hosted specs behind SSO.

3. Registry reference (`oa://`)

For public, versioned reuse:

tasks:
  summarise:
    spec: oa://prime-vector/summariser@1.0.0
    task: summarise

oa://namespace/name expands to https://openagentspec.dev/registry/namespace/name/latest/spec.yaml. With @version, it pins to an exact version. Drop the version for "latest" semantics — useful in development, risky in production.

What lives on the registry

The OAS registry is open for community contributions. A handful of Prime Vector-authored specs are already published as a baseline:

Reference	Purpose
`oa://prime-vector/summariser`	Document summarisation
`oa://prime-vector/classifier`	Multi-class document classification
`oa://prime-vector/sentiment`	Sentiment analysis with confidence scores
`oa://prime-vector/keyword-extractor`	Key phrase extraction
`oa://prime-vector/code-reviewer`	Code review task for PR diffs
`oa://prime-vector/memory-retriever`	Retrieve relevant context from a memory store

You can compose these into your own pipelines without writing the prompts yourself. Each is a single YAML file with a typed output schema — so when you call it, you know exactly what you're going to get back.

Composing delegated tasks with `depends_on`

Delegation stacks with depends_on. You can chain multiple delegated tasks together:

open_agent_spec: "1.4.0"

agent:
  name: document-processor
  description: "Extract, summarise, and classify a document"

intelligence:
  type: llm
  engine: openai
  model: gpt-4o

tasks:
  extract_keywords:
    spec: oa://prime-vector/keyword-extractor@1.0.0
    task: extract

  summarise:
    spec: oa://prime-vector/summariser@1.0.0
    task: summarise
    depends_on: [extract_keywords]

  classify:
    spec: oa://prime-vector/classifier@1.0.0
    task: classify
    depends_on: [summarise]

Three delegated tasks. Three different authors possible. One pipeline. The runtime handles the load → run → merge flow, and the result envelope tells you exactly which spec each task delegated to:

{
  "task": "classify",
  "delegated_to": "oa://prime-vector/classifier@1.0.0#classify",
  "output": {"category": "technical-documentation", "confidence": 0.94}
}

Safety: cycle detection

One risk with delegation: A delegates to B which delegates to A. An infinite loop waiting to happen.

The runtime detects this before any model call is made and raises DELEGATION_CYCLE_ERROR:

{
  "error": "Circular spec delegation detected: './summariser.yaml' is already in the delegation stack",
  "code": "DELEGATION_CYCLE_ERROR",
  "stage": "delegation",
  "task": "summarise"
}

This is specified in the formal OAS standard as a MUST requirement — any conforming runtime has to detect cycles before spending tokens.

Version pinning: why you should care

The registry supports both floating (oa://.../summariser) and pinned (oa://.../summariser@1.0.0) references.

In production, pin your versions. Same reason you pin npm or PyPI packages. A spec author can update prompts, tighten schemas, or change defaults in ways that look like minor improvements but subtly alter your pipeline's output.

Semantic Versioning applies:

Patch bumps (1.0.0 → 1.0.1) — prompt tweaks, typo fixes, no schema changes
Minor bumps (1.0.0 → 1.1.0) — added optional output fields, expanded input acceptance
Major bumps (1.0.0 → 2.0.0) — schema changes, prompt overhauls, model swaps

For CI agents or anything that fans out to production data, pin. Always.

Publishing your own

The registry is open for contributions. If you build a well-scoped agent spec that others could reuse — a good test generator, a bug-triager, a changelog writer — open a PR to add it.

Specs that make good registry citizens:

Single-responsibility — do one thing, not five
Stable I/O schema — typed inputs, typed outputs, documented fields
Engine-agnostic — work across OpenAI, Claude, Grok, or local models
Minimal prompts — the less cleverness, the less breakage

Getting started

Add a delegated task to any existing spec:

tasks:
  summarise:
    spec: oa://prime-vector/summariser@1.0.0
    task: summarise

Run it:

oa run --spec .agents/my-pipeline.yaml --task summarise \
  --input '{"document":"..."}' --quiet

The runtime resolves the registry reference, loads the spec, runs the delegated task, and returns the result. No extra install. No framework to adopt.

Resources:

Also in this series:

Open Agent Spec is MIT-licensed and maintained by Prime Vector. The registry is open — we'd love to see what you build.

DEV Community: Scotty G