Skip to main content

🧾 Agentspecs

Declarative YAML specifications for AI agents, MCP servers, skills and more...

What Is Agentspecs?​

Agentspecs is the source of truth for runtime catalogs compiled into Python and TypeScript.

The documentation has three parts, and they answer different questions.

Agents — what one agent is, and everything it is made of. An agent spec is mostly references: to the skills it has, the tools and MCP servers it can reach, the model it runs on, where its memory lives, what it is judged by. Each of those is a catalogue of its own, documented under Agents:

  • Skills, Tools, MCP Servers
  • Models, Memory, Env Vars
  • Hooks, Triggers, Guardrails
  • Evals, Benchmarks, Outputs, Notifications

Agent Teams — several agents working on one job, plus a supervisor deciding what happens next. A team composes agents from the catalogue by reference rather than restating them, and says in data — not in prose — what order they run in.

Modularity — how a spec is built out of other specs, rather than copied from them. Extension (extends) for "the same agent, adjusted", composition (includes) for "this bundle, wherever needed". It sits beside the other two because it applies to both: a team member and an agent are composed by the same rules.

Key Properties​

  • Single Source of Truth: YAML files are the authoritative specification
  • Declarative: Define what the system should do, not implementation details
  • Composable: Specs reference each other by stable IDs
  • Validated: JSON Schema ensures consistency and correctness
  • Extensible: Easy to add new fields or specification types
  • Human-Readable: YAML format is easy to read and edit

Versioning​

All specs are versioned and include:

  • id
  • version (currently 0.0.1)

Cross-spec references should use id:version format (for example tavily:0.0.1).

Generated catalogs are keyed by unversioned id only (e.g. tavily). The get_* / get*Spec accessor functions accept both bare ids and versioned refs (tavily:0.0.1), stripping the version suffix automatically. Iterating catalog values returns each spec exactly once.

Directory Structure​

agentspecs/
├── agents/
├── teams/
├── mcp-servers/
├── skills/
├── tools/
├── envvars/
├── models/
├── memory/
├── guardrails/
├── evals/
├── benchmarks/
├── triggers/
├── outputs/
└── notifications/

Writing Specs​

  1. Create or update a YAML file in the relevant folder.
  2. Always set id and version.
  3. Prefer explicit versioned references (id:version) for linked specs.
  4. Keep IDs stable and bump version for breaking changes.

Parameters​

Agentspecs can declare launch-time parameters using JSON Schema. These parameters are validated before runtime creation and then injected into templated fields.

Why use parameters?​

  • Build one reusable spec for many runtime contexts.
  • Enforce input shape (type, enum, required, defaults).
  • Drive prompts, hooks, and messages from validated values.

Where parameters are used​

Parameter values can be referenced with {{name}} templating in fields such as:

  • system_prompt
  • welcome_message
  • pre_hooks.sandbox
  • other text fields that support runtime templating

Example​

id: demo-parameters
version: 0.0.1

parameters:
  type: object
  properties:
    project:
      type: string
      default: Orbit
    role:
      type: string
      enum: [product analyst, engineering lead, support specialist]
      default: product analyst
  required:
    - project

system_prompt: >
  You are an assistant dedicated to {{project}}.
  Assume the user is a {{role}}.

pre_hooks:
  sandbox:
    - |
      project_name = """{{project}}"""

Validation behavior​

  • Missing required parameters fail validation.
  • Invalid values (for example enum mismatch) fail validation.
  • Optional parameters use their schema defaults when provided.

Documentation​

Notes​

  • Use kebab-case IDs for most specs.
  • Use UPPER_SNAKE_CASE IDs for env vars.
  • Keep references explicit and versioned.

License​

Copyright (c) 2025-2026 Datalayer, Inc.
Distributed under the terms of the Modified BSD License.