Documentation

Everything you need to define, validate, and deploy AI workflows with b2agent.

Install

b2agent requires Node.js ≥ 20. Install globally via npm:

terminal

npm install -g b2agent

Or run directly without installing:

terminal

npx b2agent

Quick Start

Create a process file, validate it, compile, and simulate — in four commands.

1. Create a process file

classify.yaml

b2agent: "1.0"

process:
  id: classify
  name: Classify Request
  version: "1.0.0"

triggers:
  - event: request.received

steps:
  - id: classify
    name: Classify
    action: llm
    prompt: |
      Classify this request: {{input.data}}
    output:
      schema:
        category:
          type: string
    constraints:
      max_tokens: 500
      max_cost_usd: 0.01

2. Validate

terminal

b2agent validate classify.yaml

3. Compile

terminal

# Compile to MCP tool server
b2agent compile classify.yaml --target mcp

# Compile to system prompt
b2agent compile classify.yaml --target prompt

4. Simulate

terminal

# Mock LLM (no API key needed)
b2agent sim classify.yaml --mock-llm

# Real provider
b2agent sim classify.yaml -p deepseek -m deepseek-chat
b2agent sim classify.yaml -p ollama -m llama3

YAML DSL Overview

Every process file has four top-level sections: metadata, triggers, steps, and optional security.

structure

b2agent: "1.0"            # DSL version

process:                   # Identity
  id: my-process
  name: My Process
  version: "1.0.0"
  description: "..."
  tags: [tag-a, tag-b]

triggers:                  # What starts the process
  - event: request.received

steps:                     # Workflow steps
  - id: step-1
    action: llm

security:                  # Optional security policy
  data_classification: internal

Triggers

Triggers define what starts a process. At least one trigger is required.

triggers

triggers:
  - event: request.received   # required
    condition: "..."            # optional filter
    schedule: "0 9 * * *"      # optional cron
    webhook:                    # optional
      path: /hook
      method: POST
      secret: WEBHOOK_SECRET

Steps

Steps are the building blocks of a workflow. Each step has a unique ID, an action type, and optional constraints, guardrails, and error handling.

step schema

steps:
  - id: my-step              # required, unique
    name: My Step            # required
    action: llm              # required: llm|api|transform|human|route|plugin
    depends_on: []          # step IDs this depends on
    on_error: fail           # fail|skip|retry|escalate|fallback

    constraints:
      max_tokens: 1000
      timeout_ms: 10000
      max_cost_usd: 0.05
      max_retries: 3

    guardrails:
      - type: budget
        action: block

Action Types

Action	Required Fields	Purpose
`llm`	`prompt`	Send a prompt to a language model. Use `{{input.field}}` for interpolation. Set `output.schema` for structured output.
`api`	`url`	HTTP request. Optional `method` and `body`.
`transform`	`transform`	Expression that produces a new object.
`human`	`config.assignee`	Pause for human review/approval.
`route`	`rules`	Conditional branching with `if`/`else` + `goto`.
`plugin`	`plugin`	Delegate to a named external plugin.

Route Rules

Route steps use conditional rules to branch the workflow. Each rule has an if or else condition and a goto target.

route

rules:
  - if: "priority == 'urgent'"
    goto: escalate
  - if: "category == 'billing'"
    goto: billing-team
  - else: true
    goto: default-handler

Error Handlers

Global error handlers catch failures across the workflow.

error_handlers

error_handlers:
  - match: StepFailure
    action: retry
  - match: BudgetExceeded
    action: escalate
  - match: "*"
    action: abort

CLI Commands

Command	Description
`b2agent init`	Interactive project scaffolding. Creates config, directory, and process YAML from a starter template.
`b2agent validate <file>`	Parse and validate a YAML against the full schema. Exit 0 = valid, 1 = errors, 2 = warnings.
`b2agent compile <file>`	Compile to MCP tool server or system prompt markdown. Validates first, then outputs to `./dist`.
`b2agent sim <file>`	Simulate execution with mock or real LLM providers. Test before you deploy.
`b2agent serve <file>`	Start a live MCP server exposing process steps as callable tools.

Compile Options

Flag	Default	Description
`--target, -t`	`all`	Target format: `mcp`, `prompt`, or `all`
`--output, -o`	`./dist`	Output directory
`--dry-run`	`false`	Print output to stdout without writing files

Sim Options

Flag	Default	Description
`--provider, -p`	`anthropic`	LLM provider
`--model, -m`	per provider	Model name
`--data, -d`	—	Path to JSON input data fixture
`--mock-llm`	`false`	Use deterministic mock responses (no API calls)
`--base-url`	per provider	Override the provider's API endpoint
`--verbose, -v`	`false`	Show full prompts, responses, and timing
`--step-by-step`	`false`	Pause after each step

Serve Options

Flag	Default	Description
`--transport`	`stdio`	Transport: `stdio`, `sse`, `streamable-http`
`--port`	`3100`	Port for SSE/HTTP transport
`--provider, -p`	`anthropic`	LLM provider
`--model, -m`	per provider	Model name
`--mock-llm`	`false`	Use mock responses
`--hot-reload`	`false`	Watch file and reload on changes

Cloud Providers

Provider	API Key Env	Example Models
`anthropic`	`ANTHROPIC_API_KEY`	claude-sonnet-4-20250514, claude-haiku-4-5-20251001
`openai`	`OPENAI_API_KEY`	gpt-4o, gpt-4o-mini, o3, o4-mini
`deepseek`	`DEEPSEEK_API_KEY`	deepseek-chat, deepseek-reasoner
`qwen`	`DASHSCOPE_API_KEY`	qwen-max, qwen-plus, qwen-turbo
`moonshot`	`MOONSHOT_API_KEY`	moonshot-v1-8k, moonshot-v1-128k
`yi`	`YI_API_KEY`	yi-large, yi-medium, yi-spark
`zhipu`	`ZHIPU_API_KEY`	glm-4, glm-4-flash, glm-4-plus

Local Providers

No API key needed. Models run on your machine.

Provider	Default Port	Use Case
`ollama`	11434	Ollama local models
`lmstudio`	1234	LM Studio
`vllm`	8000	vLLM server

Per-step override: You can set provider and model on individual steps to mix providers within a single workflow.

Security Policy

Every process carries a declarative security policy. Permissions restrict network access, filesystem operations, and subprocess execution to explicit allowlists.

security

security:
  secrets:
    - name: API_KEY
      source: env           # env | vault | prompt
  permissions:
    network: ["api.example.com"]
    filesystem: read      # none | read | write | read-write
    subprocess: false
  data_classification: confidential
  pii_handling: redact    # redact | mask | encrypt | reject
  audit_level: full      # minimal | standard | full

Never hardcode secrets. Use secrets references with source: env or source: vault. The validator will flag hardcoded API keys.

Validation Rules

The validator checks for common issues automatically:

Code	Level	Rule
`DUPLICATE_STEP_ID`	Error	All step IDs must be unique
`UNDEFINED_REFERENCE`	Error	`depends_on` and route `goto` must reference existing step IDs
`CIRCULAR_DEPENDENCY`	Error	Step dependency graph must be acyclic
`INVALID_EXPRESSION`	Error	Route `if` expressions must be valid
`UNREACHABLE_STEP`	Warning	Steps not referenced by any `depends_on` or `goto`
`GUARDRAIL_MISSING`	Warning	LLM steps without `max_tokens` or `max_cost_usd`
`HARDCODED_SECRET`	Warning	Strings matching `sk-`, `Bearer `, `ghp_*`, etc.
`PERMISSIVE_NETWORK`	Warning	API steps with empty `security.permissions.network`

Templates & Examples

b2agent ships with starter templates and production-ready examples.

Templates

basic.yaml — Simple LLM classification with routing
approval-flow.yaml — Multi-step approval workflow with human review
classification.yaml — Text classification pipeline

Examples

email-triage.yaml — Email urgency classification and auto-reply
content-moderation.yaml — Content moderation with prompt injection defense
customer-onboarding.yaml — KYC verification with confidential data handling
data-pipeline.yaml — Scheduled data processing with quality validation
invoice-processing.yaml — Invoice extraction and routing
support-ticket-router.yaml — Support ticket classification and assignment
code-review-assistant.yaml — Automated code review workflow
lead-scoring.yaml — Lead scoring with CRM integration
compliance-check.yaml — Regulatory compliance verification