Runtime Reference

Bee Worker is the runtime container for BeeSystem agents. It handles execution isolation, tool invocations, memory access, and observability.

Starting Bee Worker

# Start with default config
bee worker start

# Start with custom config
bee worker start --config ./worker.yaml

# Start in Docker
docker run -v $(pwd):/workspace beesystem/bee-worker:latest

Worker configuration

worker.yamlyaml

# worker.yaml
port: 7433
log_level: info
log_format: json

runtime:
  max_concurrent_agents: 10
  default_timeout: 60s
  memory_limit_mb: 512

observability:
  traces: true
  metrics: true
  log_tool_calls: true

security:
  require_auth: false
  allowed_origins: ["*"]

Agent execution lifecycle

When Bee Worker receives a task for an agent, it follows this sequence:

Load and validate the agent specification
Initialize agent context (tools, memory, constraints)
Execute the agent with the provided task
Handle tool calls with structured input/output contracts
Produce typed output or structured error
Flush session memory if applicable
Emit observability events

Bee Worker enforces all constraints declared in the agent spec. If the agent spec declaresno_silent_fallbacks, any attempt by the agent to use a secondary path is rejected with a structured error.

CLI commands

CLI referencebash

# Core commands
bee worker start          # Start the runtime
bee worker stop           # Graceful shutdown
bee worker status         # Show runtime status
bee agent run             # Execute an agent
bee agent list            # List registered agents
bee agent validate        # Validate an agent spec

# Utility commands
bee init <name>           # Create new agent project
bee tool list             # List available tools
bee version               # Show version info

Observability

Bee Worker emits structured events for every agent execution. Events include: agent start/stop, tool invocations (with inputs/outputs), memory reads/writes, errors, and execution timing.

Structured eventjson

{
  "event": "tool_call",
  "agent": "market-research-agent",
  "tool": "web_search",
  "input": { "query": "distributed systems papers 2024" },
  "output": { "results": [...] },
  "duration_ms": 342,
  "timestamp": "2025-05-24T10:30:00Z"
}