Skip to main content

Agentspecs

Agent Runtimes uses the Agentspecs repository as the source of truth for:

  • Agents
  • MCP servers
  • Skills
  • Environment variables

These specs are cloned locally and then compiled into the runtime catalogs used by Agent Runtimes.

For the public platform docs and broader Agentspec context, see datalayer.ai/docs.

Clone and Generate​

From the repository root:

make specs

This command:

  • Clones the agentspecs repository into ./agentspecs (or pulls updates)
  • Generates Python and TypeScript catalogs for agents, MCP servers, skills, and env vars

Using a Local Agentspecs Checkout​

If you already have agentspecs checked out elsewhere, copy or symlink it to ./agentspecs before running make specs.

Where Specs Are Used​

The generated catalogs are written under agent_runtimes/specs/ (Python) and src/specs/ (TypeScript):

  • agent_runtimes/specs/agents/ · src/specs/agents/ (agents, subfoldered)
  • agent_runtimes/specs/teams · src/specs/teams
  • agent_runtimes/specs/skills.py · src/specs/skills.ts
  • agent_runtimes/specs/tools.py · src/specs/tools.ts
  • agent_runtimes/specs/frontend_tools.py · src/specs/frontendTools.ts
  • agent_runtimes/specs/envvars.py · src/specs/envvars.ts
  • agent_runtimes/mcp/catalog_mcp_servers.py · src/specs/mcpServers.ts
  • plus models, memory, guardrails, evals, events, notifications, outputs, personas, loops, triggers, benchmarks — one catalog each, same pattern

What You Can Define in an Agent Spec​

Agent specs are not just static prompts. They define runtime behavior across UX, workflows, controls, programmatic tooling, and delivery.

UX Patterns and Protocol-Oriented Agents​

Use transport and UI configuration in specs to power GenUI experiences and protocol-targeted agents (AG-UI, A2UI, ACP, Vercel AI, A2A).

Interactive and Triggered Workflows​

Specs can run interactively (chat-driven) or as event/schedule-driven workflows.

  • trigger: Defines schedule/event execution and startup prompt behavior.
  • pre_hooks / post_hooks: Lifecycle setup/teardown in sandbox.
  • tool_hooks: Tool lifecycle hooks using pydantic-ai names:
    • before_tool_execute
    • after_tool_execute
    • on_tool_execute_error
    • deferred_tool_calls

Identity and Controls​

Specs can include controls such as tool approval workflows, guardrail-oriented runtime behavior, and monitoring-friendly metadata (used by snapshots/streams).

Programmatic Tooling (Sandbox, Codemode, Skills)​

  • sandbox_variant: Selects execution sandbox (eval or jupyter).
  • enable_codemode and codemode config: Enables MCP-discovery + programmatic composition.
  • skills / enable_skills: Enables reusable skill execution.

Outputs and Notifications​

For triggered workflows, specs can define delivery behavior:

  • notifications: Email/slack/webhook style delivery channels and recipients.
  • output-oriented fields in workflow specs to control the shape/destination of generated artifacts.

Real-Time Collaboration and Multi-Agent Teams​

Specs can represent single agents or orchestrated teams.

  • Team/orchestrator specs coordinate specialized workers.
  • Collaboration is surfaced through runtime protocols (especially ACP/A2A).

Minimal Example Fragments​

id: generate-weekly-reports
trigger:
	type: schedule
	cron: "0 8 * * MON"
	prompt: "Run the scheduled workflow and produce the configured deliverable."

sandbox_variant: jupyter

skills:
	- report-generation

notifications:
	email: "team@acme.com"
id: example-tool-approvals
tool_hooks:
	before_tool_execute:
		- function: agent_runtimes.integrations.tool_policy:evaluate_tool_request
	after_tool_execute:
		- python: |
				print("success", payload.get("tool"), payload.get("status"))
	on_tool_execute_error:
		- python: |
				print("error", payload.get("tool"), payload.get("error_type"))
	deferred_tool_calls:
		- python: |
				print("deferred hook invoked")
id: comprehensive-sales-analytics
description: Multi-agent team with orchestrator + specialists

mcp_servers:
	- postgres
	- slack

skills:
	- data-quality
	- forecasting