Agent Specification

The open BeeSystem agent specification defines everything about an agent in a structured, version-controllable format.

Overview

An agent specification is a YAML document. It is the source of truth for an agent's identity, capabilities, tools, memory, and runtime behavior. The spec is read by Bee Worker at runtime and by Bee Platform for design and management.

Full specification example

agent.yamlyaml

# BeeSystem Agent Specification v0.1
name: market-research-agent
version: "0.2.1"
description: |
  Reads, summarizes, and synthesizes structured research output
  from market documents and web sources.

# Agent capabilities
capabilities:
  - reason
  - use_tools
  - remember_context
  - produce_structured_output

# Tool definitions
tools:
  - name: web_search
    type: builtin
    config:
      provider: configured_search_api
      max_results: 20

  - name: document_reader
    type: builtin
    config:
      supported_formats: [pdf, txt, md, html]
      max_size_mb: 50

  - name: structured_writer
    type: builtin
    config:
      output_formats: [json, markdown, yaml]

# Memory configuration
memory:
  short_term:
    type: session
    max_tokens: 16384
  long_term:
    type: persistent
    backend: configured_store
    namespace: market-research

# Runtime parameters
runtime:
  timeout: 120s
  max_retries: 3
  on_failure: structured_error

# Behavioral constraints
constraints:
  - no_silent_fallbacks
  - structured_errors_only
  - no_mock_dependencies

# Output schema
output:
  type: structured
  schema: ./schemas/research_output.json

Required fields

Field	Type	Description
`name`	string	Unique agent identifier. Lowercase, hyphens allowed.
`version`	semver	Agent specification version (semver format).
`description`	string	Human-readable description of the agent's purpose.
`capabilities`	string[]	List of capability declarations the agent can exercise.

Capabilities

Available capability declarations:

reason — Agent can reason about tasks and produce logical outputs
use_tools — Agent can invoke configured tools
remember_context — Agent can use configured memory
produce_structured_output — Agent produces typed structured output
delegate_subtask — Agent can delegate to other agents (requires Bee Hive)
self_evaluate — Agent evaluates its own output quality

Tool types

builtin — Provided by BeeSystem standard tool library
custom — Custom tool built with the Bee SDK
connector — External service connector from the integration library

All tool calls must target real dependencies. No mocks, no simulated responses. If a dependency is unavailable, Bee Worker returns a structured error and stops.

Memory types

session — Cleared after each agent run. Appropriate for stateless tasks.
persistent — Retained across runs. Requires a configured backend.
retrieval — Queried at runtime from an external knowledge store.

Runtime constraints

The constraints field enforces behavioral rules at the Bee Worker level:

no_silent_fallbacks — Agent must not use hidden secondary paths on failure
structured_errors_only — All errors must be structured typed errors
no_mock_dependencies — No simulated tool responses permitted