Navigation
smf-forge CLI
Lightweight multi-agent orchestration — define, compose, and run AI agent pipelines from the terminal.
Installation
Quickstart
CLI Reference
smf-forge init
Initialize a new project with a forge.yaml template.
smf-forge run
Execute a named pipeline.
smf-forge agents
List configured agents and their types.
smf-forge pipelines
List configured pipelines and their step dependencies.
smf-forge validate
Validate forge.yaml without running anything. Checks agent types, pipeline DAGs, dependency cycles, and duplicate step names.
Built-in Agent Types
| Type | Description | Key Config |
|---|---|---|
| echo | Returns the input prompt. Useful for testing pipelines. | — |
| http | Calls an OpenAI-compatible chat completions endpoint. | model, base_url, api_key |
| shell | Runs a shell command and returns stdout/stderr. | options.command |
| transform | Applies a Jinja2 template to context data. | options.template |
Configuration Reference
forge.yaml Structure
project: my-project
version: "0.1.0"
agents:
researcher:
type: http
model: gpt-4
base_url: ${OPENAI_BASE_URL:https://api.openai.com/v1}
api_key: ${OPENAI_API_KEY}
system_prompt: "You are a research assistant."
temperature: 0.3
max_tokens: 4096
summarizer:
type: http
model: gpt-4
base_url: ${OPENAI_BASE_URL:https://api.openai.com/v1}
api_key: ${OPENAI_API_KEY}
system_prompt: "Summarize the following text concisely."
pipelines:
research-summarize:
name: research-summarize
steps:
- name: research
agent: researcher
prompt: "{{ prompt }}"
- name: summarize
agent: summarizer
prompt: "Summarize this research:\n{{ research.response }}"
depends_on:
- researchEnvironment Variables
Use ${VAR} to resolve from environment (raises error if not set), or ${VAR:default} to provide a fallback value.
api_key: ${OPENAI_API_KEY} # Required — raises if not set
base_url: ${OPENAI_BASE_URL:https://api.openai.com/v1} # Optional — defaultsPipeline Execution Model
Pipelines execute as DAGs. Steps with no dependencies run in parallel. Step outputs are available as template variables in downstream steps via Jinja2 rendering.
# Parallel execution:
# research ──┐
# ├──→ summarize
# validate ──┘
steps:
- name: research
agent: researcher
prompt: "{{ prompt }}"
- name: validate
agent: echo
prompt: "{{ prompt }}"
- name: summarize
agent: summarizer
prompt: "Research: {{ research.response }}\nValidation: {{ validate.echo }}"
depends_on:
- research
- validateError Handling
Fail-fast (default): When a step fails, all remaining steps are marked SKIPPED and the pipeline exits with code 1.
Continue-on-error: All steps attempt to run regardless of prior failures. Use --continue-on-error flag.