AgentBase v0.1-alpha

Unified AI agent configuration, observability, and model management for production multi-agent systems.

AgentBase is a lightweight, framework-agnostic control plane that standardizes how AI-heavy products configure models, register agents, and emit observability metadata. No framework dependencies. No vendor lock-in. Just YAML + Python.

Status

✅ v0.1-alpha — Core library complete. 96 tests passing. First projects integrated (Writerverse, Skill-Deck pipeline).

What It Does

import agentbase
from langchain_openai import ChatOpenAI

# Load configuration
agentbase.load_config("agentbase.yaml", "agents.yaml")
agentbase.init_tracing()

# Resolve an agent
resolved = agentbase.resolve("my_analyzer")

# Construct LLM with AgentBase config
llm = ChatOpenAI(model=resolved.model_id, **resolved.default_params)

# Enable LangSmith tracing
result = llm.invoke(messages, config=resolved.langchain_config())

Returns:

• model_id: Resolved model name (e.g., gpt-4o, claude-sonnet-4-20250514)
• default_params: Model config (temperature, max_tokens, etc.)
• langchain_config(): LangSmith trace metadata (tags, generation_name, metadata)

Core Features

• YAML Config — Single source of truth for all model aliases and agent definitions
• Model Aliases — fast, smart, creative that resolve to provider-specific IDs per environment
• Agent Registry — Centralized agent metadata (owner, version, prompt location, status)
• LangSmith Integration — Automatic trace metadata in every chain/workflow
• Environment Switching — Dev/prod model aliases in one config file
• Zero Framework Dependencies — Works with LangChain, Anthropic SDK, OpenAI SDK, etc.
• CLI Validation — agentbase validate checks config and resolves all agents

Installation

pip install agentbase==0.1.0a1

Quick Start

1. Create config files:

agentbase.yaml:

project: my-project

models:
  fast:
    dev: gpt-4o-mini
    production: gpt-4o
  smart:
    dev: gpt-4o
    production: claude-sonnet-4-20250514

defaults:
  environment: dev
  model_alias: smart

tracing:
  backend: langsmith
  enabled: true

agents.yaml:

agents:
  - agent_name: analyzer
    model_alias: fast
    owner: team
    status: active
    agent_version: "0.1.0"
    prompt_ref: "git:backend/prompts/analyze.py"
    description: "Analyzes input data"

2. Set environment variables:

LANGCHAIN_API_KEY=lsv2_pt_xxxxx
OPENAI_API_KEY=sk-xxxxx

3. Initialize in your app:

import agentbase

agentbase.load_config(config_path="agentbase.yaml", registry_path="agents.yaml")
agentbase.init_tracing()

4. Use in your chains:

resolved = agentbase.resolve("analyzer")
llm = ChatOpenAI(model=resolved.model_id, **resolved.default_params)
result = chain.invoke(input, config=resolved.langchain_config())

See QUICKSTART.md for full setup instructions.

Architecture

agentbase.load_config()
  ├─ Loads agentbase.yaml (project, models, defaults, tracing)
  ├─ Loads agents.yaml (agent registry)
  └─ Validates all required fields

agentbase.init_tracing()
  └─ Sets LANGCHAIN_TRACING_V2 and LANGCHAIN_PROJECT env vars
     (if LangSmith backend is enabled)

agentbase.resolve(agent_name)
  ├─ Looks up agent in registry
  ├─ Resolves model_alias → model_id (using defaults.environment)
  ├─ Returns ResolvedAgent with:
  │  ├─ model_id (e.g., "gpt-4o")
  │  ├─ default_params (temperature, max_tokens, etc.)
  │  ├─ langchain_config() → LangSmith metadata
  │  └─ trace_metadata → raw metadata dict
  └─ (Throws ConfigValidationError if not found or invalid)

API

Core Functions

agentbase.load_config(config_path: str, registry_path: str) → None
  # Load and validate agentbase.yaml and agents.yaml
  # Raises ConfigValidationError if validation fails

agentbase.init_tracing() → None
  # Set up LangSmith tracing if enabled in config
  # Requires LANGCHAIN_API_KEY env var if using LangSmith

agentbase.resolve(agent_name: str) → ResolvedAgent
  # Resolve agent and return config
  # Returns ResolvedAgent with model_id, default_params, langchain_config()
  # Raises ConfigValidationError if agent not found

agentbase.validate(config_path: str, registry_path: str) → None
  # Validation-only mode (no tracing setup)
  # Used by CLI and tests

ResolvedAgent

@dataclass
class ResolvedAgent:
    model_id: str | None          # "gpt-4o", "claude-sonnet-4-20250514", None for workflows
    default_params: dict[str, Any] # {"temperature": 0.7, "max_tokens": 4096}
    
    def langchain_config(self) -> dict[str, Any]:
        # Returns LangSmith-compatible config for chain.invoke(config=...)
        # Fields: generation_name, trace_name, tags, metadata

CLI

# Validate config (exit 0 if valid, 1 if errors)
agentbase validate agentbase.yaml agents.yaml

# Resolve an agent (pretty-print)
agentbase resolve agent_name --config agentbase.yaml --registry agents.yaml

# Version
agentbase --version

Configuration Reference

agentbase.yaml

project: <string>              # Project name (used in LangSmith traces)

models:
  <alias>:                      # e.g., "fast", "smart", "creative"
    dev: <model_id>             # e.g., "gpt-4o-mini"
    production: <model_id>      # e.g., "gpt-4o"

defaults:
  environment: <env>            # "dev" or "production"
  model_alias: <alias>          # Default model alias
  [other defaults...]

tracing:
  backend: langsmith | none     # "langsmith" or "none"
  enabled: true | false         # Enable/disable tracing

agents.yaml

agents:
  - agent_name: <string>        # Unique agent identifier
    model_alias: <string>       # References models.* in agentbase.yaml
    owner: <string>             # Team or person responsible
    status: active | inactive   # Status
    agent_version: <semver>     # e.g., "0.1.0"
    prompt_ref: <string>        # Reference to prompt (e.g., "git:path/to/file.py")
    description: <string>       # Human-readable description

Environment Variables

Variable	Required	Purpose
LANGCHAIN_API_KEY	If tracing enabled	LangSmith API key
OPENAI_API_KEY	If using gpt-* models	OpenAI API key
ANTHROPIC_API_KEY	If using claude-* models	Anthropic API key

Why AgentBase?

Before AgentBase:

• Each project had its own config system (get_ai_config, hardcoded model names)
• LLM setup was duplicated across chains
• No unified observability or cost tracking
• Difficult to switch models for A/B testing

With AgentBase:

• One config file per project, YAML-based
• Agents registered once, resolved anywhere
• Automatic LangSmith integration
• Model switching via defaults.environment
• Cost visibility per agent per environment

For Projects Using AgentBase

• Writerverse — 35 agents + 7 LangGraph workflows (scene generation, consistency analysis, chat, supervisor)
• Skill-Deck — Q&A system with dynamic model routing
• Shivam Portfolio — Proof-of-concept (first integration)

See QUICKSTART.md for project integration steps.

For Publishing

See PUBLISH.md for detailed steps to publish to PyPI.

Development

# Install dev dependencies
pip install -e .[dev]

# Run tests
pytest tests/ -v

# Lint
ruff check agentbase/ tests/

# Format
ruff format agentbase/ tests/

License

MIT — see LICENSE

Author

Shivam Srivastava — GitHub

---

Questions? Open an issue on GitHub