DEV Community

Cover image for Composable Agent Specs: Spec Delegation and the OAS Registry
Scotty G
Scotty G

Posted on

Composable Agent Specs: Spec Delegation and the OAS Registry

#ai #python #opensource

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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]
Enter fullscreen mode Exit fullscreen mode

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}
}
Enter fullscreen mode Exit fullscreen mode

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"
}
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Run it:

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

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.

Top comments (0)