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 repository currently defines these spec families:

  • Agent specs
  • Hook specs
  • Team specs
  • MCP server specs
  • Skill specs
  • Tool specs
  • Environment variable specs
  • Model specs
  • Memory specs
  • Guardrail specs
  • Eval specs
  • Trigger specs
  • Output specs
  • Notification specs

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/
├── 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​

Agent specs 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.