search
Go to website

hammerAgent Forge SDK

Release history for the Agent Forge SDK (configuration management tooling).

circle-info

Current Version: v0.3.0 | Compatibility: Amigo API v0.6.0+

chevron-rightv0.3.0 - Schema Migration System (January 16, 2026)hashtag

Agent Forge v0.3.0 introduces a schema migration system for handling entity schema evolution. When local entity JSON files use an older schema format but the Forge code expects the new format, the migration system automatically detects and handles these differences.

Why This Matters: Entity schemas evolve over time as features are added or fields are restructured. Previously, schema mismatches between local files and the current Forge version caused validation errors that required manual intervention. The new migration system provides automated detection, clear visibility into what needs updating, and safe migration with backup options.

New Commands

Command
Description

forge migrate status

Check which files need migration without making changes

forge migrate run

Migrate files to the latest schema version

forge migrate run --apply

Apply migrations (creates .bak backup files)

forge migrate run --apply --no-backup

Apply migrations without creating backups

Checking Migration Status

# Check migration status for dynamic behavior sets
poetry run forge migrate status --entity-type dynamic_behavior_set --env dogfood

# Example output:
# Checking schema versions in local/dogfood/entity_data/dynamic_behavior_set...
# Current schema version: v2
#
# ┌──────────────────────┬──────────────────┬────────┐
# │ File                 │ Current Version  │ Target │
# ├──────────────────────┼──────────────────┼────────┤
# │ my_behavior.json     │ v1 (inferred)    │ v2     │
# │ other_behavior.json  │ v2 (inferred)    │ v2     │  ← needs normalization
# └──────────────────────┴──────────────────┴────────┘

Running Migrations

# Dry-run (default) - shows what would be migrated
poetry run forge migrate run --entity-type dynamic_behavior_set --env dogfood

# Apply migrations (creates .bak backup files)
poetry run forge migrate run --entity-type dynamic_behavior_set --env dogfood --apply

# Apply without creating backups
poetry run forge migrate run --entity-type dynamic_behavior_set --env dogfood --apply --no-backup

Example Migration Output

┌───┬──────────────────────┬──────────────────┬──────┬────────────┐
│   │ File                 │ From Version     │ To   │ Status     │
├───┼──────────────────────┼──────────────────┼──────┼────────────┤
│ ✓ │ my_behavior.json     │ v1 (inferred)    │ v2   │ Migrated   │
│ ✓ │ other_behavior.json  │ v2 (inferred)    │ v2   │ Normalized │
└───┴──────────────────────┴──────────────────┴──────┴────────────┘

Complete: 2 succeeded, 0 failed
Backup files (.bak) were created for updated files.

Automatic Migration During Sync

When running sync-to-local or sync-to-remote commands, the system automatically checks for files needing migration and prompts you:

poetry run forge sync-to-remote --entity-type dynamic_behavior_set --env dogfood --apply

# If migrations are needed, you'll see:
# ⚠ Some local files need schema migration before syncing.
#
# Files needing migration: 2
# Files needing normalization: 1
#
# Would you like to apply migrations now? [y/N]:

Affected Existing Commands

Command
Change

forge sync-to-local

Now checks for files needing migration after sync and prompts to apply

forge sync-to-remote

Now checks for files needing migration before sync and prompts to apply

Both sync commands will detect outdated schema versions and prompt you to migrate before proceeding. You can choose to apply migrations immediately or run forge migrate commands separately.

Key Features

  • Version detection: Automatically detects schema versions using heuristics for files without explicit schema_version fields (shown as "v1 (inferred)" in output)

  • Normalization: Files at current version but missing explicit schema_version field are normalized

  • Safe migrations: Creates .bak backup files by default when applying changes

  • Sync integration: Automatically prompts during sync commands when migrations are needed

  • Dry-run by default: All migration commands preview changes before applying

How to Get It

  1. Check out main and git pull to pick up the latest CLI.

chevron-rightv0.2.25 - Dynamic Behaviors as First-Class Assets (January 11, 2026)hashtag

Agent Forge v0.2.25 integrates dynamic behaviors into the service-asset hierarchy, providing full CLI discovery and management capabilities for behavioral configurations.

Why This Matters: Previously, dynamic behaviors existed as standalone entities without proper CLI discovery or service integration. Services couldn't display their applied behaviors, and there was no way to manage behavior versions through the CLI. This update brings behaviors to feature parity with other assets (agents, context graphs), enabling consistent management across all service components.

New Asset Discovery Commands

# List all dynamic behaviors with active status
forge asset behavior list -e production

# Show behavior version history
forge asset behavior version-list "Emergency Response Protocol" -e production

# Inspect specific behavior version
forge asset behavior version-show "Emergency Response Protocol" 3 -e production

Service Integration

Services now display applied dynamic behaviors:

$ forge service show MyService -e production

Service: MyService
  ID: 6618791275130b73714e8d1c
  Description: Health coaching service
  Active: Yes

Linked Assets:
  Agent: HealthCoach (66e0d996...)
  Context Graph: health_flow (66e0d830...)
  Dynamic Behaviors: 3 applied
    - Emergency Response Protocol (689f93e4...) ✓
    - Calorie Target Guidance (689f93ed...) ✓
    - Safety Screening (689f93e0...) ✗

Version Sets:
  Name       Agent Ver    CG Ver    Behaviors    LLM Config
  release           2         5    3 behaviors   defaults
  preview           3         6    4 behaviors   claude-sonnet

Version Set Enhancement

Version sets now track behavior configurations:

$ forge version-set show release -s MyService -e production

Version Set 'release' - MyService

  Agent Version: 2
  Context Graph Version: 5

  Applied Behaviors:
    - Emergency Response Protocol (689f93e4...)
    - Calorie Target Guidance (689f93ed...)
    - Safety Screening (689f93e0...)

  LLM Preferences: using system defaults

Key Features

  • Complete asset parity: Behaviors now have the same discovery and version management as agents and context graphs

  • Service visibility: forge service show displays all applied behaviors with active/inactive status

  • Version control: Behaviors can be versioned with deployments through version sets

  • Cross-env sync: Proper ID mapping ensures behavior associations are maintained across environments

  • Type safety: Full pyright compliance with new applied_behavior_ids field

How to Get It

  1. Check out main and git pull to pick up the latest CLI.

  2. Run poetry install to refresh dependencies.

Related Documentation

chevron-rightv0.2.24 - Service Status Command (January 11, 2026)hashtag

Agent Forge v0.2.24 introduces the forge service status command for organization-wide service health monitoring, focusing on active services by default.

Why This Matters: Organizations need to quickly identify configuration issues across their services. The new status command detects version set drift, missing configurations, and unpinned versions. By default, it only shows active services (skipping disabled/archived ones), reducing noise and focusing on what matters.

New Command: forge service status

# Check status of active services only (default behavior)
forge service status -e production

# Include inactive/disabled services in the analysis
forge service status -e production --include-inactive

# Focus on production-tagged services only
forge service status -e production --production

# Show only services with issues
forge service status -e production --issues

# Filter by tag
forge service status -e production --tag phone

# JSON output for monitoring/alerting
forge service status -e production --json

Detected Issues

  • Version set drift - Preview and release configurations differ

  • Missing version sets - Production services missing preview or release

  • Unpinned versions - Production services with non-edge version sets using latest

Example Output

Service Status in production

Summary:
  Total services: 8  # Only active services by default
  Production services: 3
  Services with issues: 2
    - With preview/release drift: 2

Services Needing Attention:

Name           ID          Active  Prod   Preview  Release  Issues
MyService      507f1f7...  Yes     Yes    Yes      Yes      preview/release drift
OtherService   508f2a8...  Yes     Yes    No       Yes      missing preview

Key Features

  • Active-by-default: Only shows active services unless --include-inactive is used

  • Smart filtering: Combine filters like --production --issues to focus on what needs attention

  • JSON output: Full support for scripting and monitoring integrations

  • Issue detection: Automatically identifies drift, missing configs, and unpinned versions

How to Get It

  1. Check out main and git pull to pick up the latest CLI.

  2. Run poetry install to refresh dependencies.

Related Documentation

chevron-rightv0.2.23 - JSON Output Consistency (January 11, 2026)hashtag

Agent Forge v0.2.23 adds --json output flags to commands that were missing them, ensuring consistent scripting support across all list/show/diff operations.

Why This Matters: CI/CD pipelines and automation scripts need machine-readable output. Previously, some commands like service list and version-set list only had human-readable table output. Now all discovery and comparison commands support --json for consistent scripting.

New --json Flags

Command
Description

forge service list -e <env> --json

List services as JSON array

forge version-set list <service> -e <env> --json

List version sets as JSON array (includes name in each entry)

forge version-set diff <set1> <set2> -s <service> -e <env> --json

Output structured diff with both configs and identical flag

Example: Scripting with JSON Output

# Get all services and pipe to jq
$ forge service list -e production --json | jq '.[].name'
"Customer Support"
"Sales Assistant"

# Check if two version sets are identical
$ forge version-set diff preview release -s MyService -e production --json | jq '.identical'
false

# Get version set configs for comparison
$ forge version-set list MyService -e production --json | jq '.[] | select(.name == "release")'
{
  "name": "release",
  "agent_version_number": 28,
  "service_hierarchical_state_machine_version_number": 4,
  "llm_model_preferences": {}
}

How to Get It

  1. Check out main and git pull to pick up the latest CLI.

  2. Run poetry install to refresh dependencies.

Related Documentation

chevron-rightv0.2.22 - Asset List Commands (January 11, 2026)hashtag

Agent Forge v0.2.22 adds top-level asset discovery commands, completing the Service → Assets → Version Sets navigation story.

Why This Matters: Previously, users could only discover asset versions if they already knew the asset name. Now you can list all agents and context graphs in an environment, enabling full asset discovery without going through services first.

New Commands

Command
Description

forge asset agent list -e <env>

List all agents with latest version numbers

forge asset context-graph list -e <env>

List all context graphs with latest version numbers

forge asset agent list -e <env> --json

JSON output for scripting

forge asset context-graph list -e <env> --json

JSON output for scripting

Also Added: --json flag to existing version-list commands for consistency:

  • forge asset agent version-list <agent> -e <env> --json

  • forge asset context-graph version-list <cg> -e <env> --json

Example: Complete Asset Discovery Workflow

# 1. List all agents in the environment
$ forge asset agent list -e dogfood --limit 5

Agents in dogfood

┏━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┓
┃ Name                     ┃ ID          ┃ Latest Version ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━┩
│ Customer Support Agent   │ 66e0d996... │             28 │
│ Sales Assistant          │ 66e0d757... │              7 │
│ Onboarding Coach         │ 6732b1fb... │             11 │
└──────────────────────────┴─────────────┴────────────────┘

# 2. List versions for a specific agent
$ forge asset agent version-list "Customer Support Agent" -e dogfood

# 3. Pin to a version set
$ forge version-set upsert preview -s MyService -e dogfood -a 28 -g 4 --apply

How to Get It

  1. Check out main and git pull to pick up the latest CLI.

  2. Run poetry install to refresh dependencies.

Related Documentation

chevron-rightv0.2.21 - Quick Rollback Command (January 11, 2026)hashtag

Agent Forge v0.2.21 adds a dedicated forge version-set rollback command for quickly reverting release to its previous configuration.

Why This Matters: When a release causes issues, time is critical. Previously, users had to remember the promote release-previous release syntax. Now there's a single, intent-clear command that shows exactly what will change before executing.

New Command

Command
Description

forge version-set rollback -s <service> -e <env>

Preview rollback (dry-run)

forge version-set rollback -s <service> -e <env> --apply

Execute the rollback

Example: Rollback Workflow

Notes

  • The release-previous version set is created automatically when promoting to release

  • If release-previous doesn't exist, the command provides a helpful error message

  • The command warns if release and release-previous are identical (nothing to roll back)

  • Runs mutation validation like other version-set commands

How to Get It

  1. Check out main and git pull to pick up the latest CLI.

  2. Run poetry install to refresh dependencies.

Related Documentation

chevron-rightv0.2.20 - Service Discovery CLI (January 11, 2026)hashtag

Agent Forge v0.2.20 adds forge service commands for discovering and inspecting services directly from the CLI. This is foundational for the CLI workflow - users can now discover available services before using version-set or asset commands.

Why This Matters: Previously, users had to know service names upfront or run sync-to-local first to see what services existed. Now the CLI is self-discoverable, enabling a complete workflow without leaving the terminal.

New Commands

Command
Description

forge service list -e <env>

List all services with tags and version set counts

forge service list -e <env> --tag <tag>

Filter services by tag (e.g., production, phone)

forge service show <service> -e <env>

Show service details including linked assets

forge service show <service> -e <env> --json

JSON output for scripting

Example: Complete Discovery Workflow

How to Get It

  1. Check out main and git pull to pick up the latest CLI.

  2. Run poetry install to refresh dependencies.

Related Documentation

chevron-rightv0.2.19 - Version Existence Validation (January 11, 2026)hashtag

Agent Forge v0.2.19 adds version existence validation to the forge version-set upsert command. When pinning specific agent or context graph versions, the CLI now validates that those versions actually exist before applying the change.

Why This Matters: Previously, users could accidentally pin non-existent versions (e.g., typos like -a 55 instead of -a 5), causing runtime failures when the service was invoked. Now these errors are caught immediately with helpful guidance.

Example: Validation in Action

New Flag: --skip-version-check

For advanced users who need to bypass validation (e.g., in automation scripts where versions may be created in parallel), use the --skip-version-check flag:

Validation Behavior

Scenario
Behavior

Explicit versions (-a 5 -g 3)

Validates both versions exist

Only agent version (-a 5)

Validates agent version only

Only context graph version (-g 3)

Validates context graph version only

No versions (unpinned/latest)

Skips validation

--latest flag

Skips validation (resolved versions always exist)

--skip-version-check flag

Skips validation entirely

How to Get It

  1. Check out main and git pull to pick up the latest CLI.

  2. Run poetry install to refresh dependencies.

Related Documentation

chevron-rightv0.2.18 - Asset Version Discovery CLI (January 11, 2026)hashtag

Agent Forge v0.2.18 adds forge asset commands for discovering agent and context graph versions. This enables users to see what versions exist before pinning them in version sets.

Why This Matters: Previously, users had to use the API directly or guess version numbers when pinning specific versions in a version set. Now you can easily list all versions with timestamps and details, making version management more discoverable and less error-prone.

New Commands

Command
Description

forge asset agent version-list <agent> -e <env>

List all versions of an agent

forge asset agent version-show <agent> <version> -e <env>

Show details of a specific agent version

forge asset context-graph version-list <cg> -e <env>

List all versions of a context graph

forge asset context-graph version-show <cg> <version> -e <env>

Show details of a specific context graph version

Example: Discover Versions Before Pinning

Additional Features

  • Look up assets by name or ID (24-character hex)

  • --json flag for machine-readable output

  • --limit flag to control number of versions shown (default: 10)

  • Detailed version-show includes persona info (agents) and state breakdown (context graphs)

How to Get It

  1. Check out main and git pull to pick up the latest CLI.

  2. Run poetry install to refresh dependencies.

Related Documentation

chevron-rightv0.2.17 - Pre-flight Validation for Version Set CLI (January 11, 2026)hashtag

Agent Forge v0.2.17 adds pre-flight validation to version set CLI commands (upsert, promote, delete). Previously, these commands bypassed validation that runs during forge sync-to-remote, allowing invalid configurations to be pushed directly to the remote API.

Why This Matters: Without validation, users could accidentally push non-voice-optimized LLMs to voice services, create unpinned version sets on production services, or violate preset cost tier constraints. Now these issues are caught before any mutation reaches the API.

Validation Rules Enforced

Rule
Scope
Behavior

Pinned versions required

Production services

Error if agent/HSM version is null

Cannot delete preview/release

Production services

Error blocks deletion

Preview required for release promotion

Production services

Error if preview doesn't exist

Voice-optimized LLMs only

Voice channels

Error if using GPT-5, Claude, etc.

Empty LLM prefs warning

Voice channels

Warning (non-blocking)

Cost tier constraints

Economy presets

Error if using premium LLMs

Example: Blocked Mutation

Example: Warning (Non-blocking)

How to Get It

  1. Check out main and git pull to pick up the latest CLI.

  2. Run poetry install to refresh dependencies.

Related Documentation

chevron-rightv0.2.16 - Auto-Backup for Release Promotions (January 10, 2026)hashtag

Agent Forge v0.2.16 adds automatic backup when promoting version sets to release, providing a safety net for production deployments without requiring users to remember the --backup flag.

Why This Matters: Previously, users had to explicitly pass --backup to create a rollback point before promoting to release. This was easy to forget, potentially leaving teams without a quick rollback option if issues were discovered after promotion. Now, backup is automatic for the most critical promotion target.

What Changed

Before (v0.2.15)
After (v0.2.16)

--backup flag required for backups

Auto-backup when promoting to release

Easy to forget safety step

Safe by default

N/A

--no-backup flag to skip if needed

New Behavior

When promoting any version set to release, a backup is automatically created as release-previous:

Skip Auto-Backup

Use --no-backup to explicitly skip the automatic backup:

Important Notes

  • Auto-backup only applies when target is release

  • Promoting to other targets (test, preview, custom) is unchanged

  • If release doesn't exist yet, no backup is needed (and none is created)

  • The --backup flag has been removed in favor of --no-backup

How to Get It

  1. Check out main and git pull to pick up the latest CLI.

  2. Run poetry install to refresh dependencies.

Related Documentation

chevron-rightv0.2.15 - Audio Filler Delay Validation (January 10, 2026)hashtag

Agent Forge v0.2.15 adds validation warnings for audio_filler_triggered_after configurations in Context Graphs and Dynamic Behaviors. The delay value should be as close to zero as possible (e.g., 0.0001) to minimize perceived latency.

Why This Matters: The audio_filler_triggered_after field delays the audio filler from playing until the specified time has elapsed. While this can prevent fillers from playing for very fast operations, any delay adds directly to perceived latency for users. Since most operations complete quickly (short-tail distribution), adding delays hurts the majority of interactions.

Recommended Configuration

Delay Value
Recommendation

< 0.001s (< 1ms)

✅ Good - Effectively zero, no warning

≥ 0.001s (≥ 1ms)

⚠️ Warning - Adds to perceived latency

Example Warning

Best Practice

Set audio_filler_triggered_after to a very small value like 0.0001 (0.1ms). The schema requires > 0, so you cannot use exactly 0, but values below 1ms are effectively instantaneous and won't trigger warnings.

How to Get It

  1. Check out main and git pull to pick up the latest CLI.

  2. Run poetry install to refresh dependencies.

  3. Run forge validate --entity-type context_graph --env <env> to check your configurations.

chevron-rightv0.2.14 - LLM Preferences Validation (January 10, 2026)hashtag

Agent Forge v0.2.14 adds comprehensive validation for version set LLM preferences against channel and preset constraints. This ensures your LLM configurations are appropriate for your deployment channel before sync.

Why This Matters: Previously, you could configure GPT-5.1 for a voice service and only discover latency issues in production. Now, the validation system catches misconfigurations early—ensuring voice channels use voice-optimized LLMs (GPT-4.1 series) and that cost tier expectations match your preset.

Validation Hierarchy

Tag Type
Validation

Voice channel (phone, web_voice, mobile_voice)

LLMs must be voice-optimized

Voice preset (voice, voice_premium, etc.)

LLMs must be voice-optimized

Economy preset (*_economy)

Premium-tier LLMs not allowed

Premium preset (*_premium)

Economy-only LLMs not allowed

No channel/preset tags

Warning if LLM preferences configured

Voice-Optimized LLMs

Voice channels require low Time-To-First-Token (TTFT) for real-time conversation. Only these LLMs are voice-optimized:

LLM
Voice Optimized
Cost Tier

azure_gpt-4.1-2025-04-14

Yes

Standard

azure_gpt-4.1-mini-2025-04-14

Yes

Economy

azure_gpt-5-*

No

Varies

azure_gpt-5.1-*

No

Premium

Cost Tier Classifications

LLMs are classified into cost tiers for validation:

Tier
LLMs
Price (per 1M input)

Economy

GPT-5-nano, GPT-4.1-mini, Gemini 2.5 Flash

$0.05-$0.40

Standard

GPT-5-mini, GPT-4.1

$0.25-$2

Premium

GPT-5, GPT-5.1, Claude Sonnet 4.5, Gemini 2.5 Pro

$1.25-$15

Example Validation Output

How to Get It

  1. Check out main and git pull to pick up the latest CLI.

  2. Run poetry install to refresh dependencies.

Related Documentation

chevron-rightv0.2.13 - Version Set CLI & Environment Tags (January 10, 2026)hashtag

Version Set CLI (forge version-set)

Agent Forge v0.2.13 introduces a complete CLI for managing service version sets, enabling the documented developer workflow (personal → test → preview → release) directly from the command line.

Why This Matters: Previously, version set management required direct API calls or manual JSON manipulation. Now you can manage the entire version set lifecycle—creating personal branches, promoting through stages, comparing configurations, and rolling back—using simple CLI commands.

Commands

Command
Description

list

Show all version sets for a service

upsert

Create or update a version set (supports --latest to pin current versions)

promote

Copy configuration from one version set to another (auto-backup when promoting to release)

diff

Compare two version sets side-by-side

show

Display detailed version set configuration

delete

Remove a custom version set

Key Features:

  • --latest flag: Resolves current agent/context graph versions and pins to actual numbers (required for production validation)

  • Auto-backup: Automatically creates release-previous backup when promoting to release (use --no-backup to skip)

  • Dry-run by default: All mutating commands require --apply to execute

  • Service lookup by name or ID: Use human-readable service names instead of MongoDB ObjectIds

Example Workflow

Example Output

Service Environment Tags

Services can now be tagged as dev or production to enforce different validation rules for version set pinning.

Why This Matters: Production services need stricter controls to prevent accidental deployment of untested configurations. Dev services need flexibility for rapid iteration. The new environment tags let you enforce appropriate guardrails for each.

Environment Tags

Tag
Validation Rules

dev

No version pinning required. Can push directly to release.

production

Must have preview version set defined. release must match preview. All non-edge version sets must have pinned versions.

Tag Format

Add environment tags to your service alongside channel tags:

Production Validation Rules

When a service is tagged production:

  1. Preview required: A preview version set must be defined

  2. Release matches preview: release configuration must match preview exactly

  3. Versions pinned: All version sets (except edge) must have explicit version numbers (no latest)

Example Validation Error

How to Get It

  1. Check out main and git pull to pick up the latest CLI.

  2. Run poetry install to refresh dependencies.

Related Documentation

chevron-rightv0.2.12 - Validate Command & Dependency Checking (January 10, 2026)hashtag

New forge validate Command

Agent Forge v0.2.12 introduces a new forge validate command that validates local entity data without syncing to remote. This allows you to catch configuration issues early, before they reach your remote environment.

Why This Matters: Previously, validation only occurred during forge sync-to-remote, meaning you had to attempt a sync to discover issues. Now you can validate locally first, catching problems like missing channel tags, invalid presets, or broken references before starting the sync process.

Usage

Key Features:

  • Validates entities against channel constraints and best practices

  • Reports errors and warnings without making any changes

  • Returns non-zero exit code on errors (CI/CD friendly)

  • Optional --check-references flag fetches remote entities for reference validation

  • Optional --check-dependencies flag validates service dependencies against channel constraints

  • Works with all entity types: agent, service, context_graph, etc.

Example Output

Service Dependency Validation (--check-dependencies)

The new --check-dependencies flag validates that a service's linked assets (context graphs, dynamic behaviors) are compatible with its channel constraints. This is critical for voice services which have strict latency requirements.

Usage

What Gets Validated

Check
Voice Channels
Severity

Context graph state count ≤ 5

✓

Warning

No decision/reflection/recall states

✓

Error

No active memory retrieval

✓

Warning

No dynamic behaviors applied

✓

Error

Single-state for ultra-low presets

✓

Error

Example Output

Why This Matters: Voice channels have strict latency requirements that limit what context graphs can do. Previously, you could deploy a voice service with an incompatible context graph and only discover the issue at runtime. Now, --check-dependencies validates these constraints before deployment.

How to Get It

  1. Check out main and git pull to pick up the latest CLI.

  2. Run poetry install to refresh dependencies.

Related Documentation

Post-Sync Summary

Sync operations now display a summary after completion, showing the count of entities created, updated, and deleted.

Why This Matters: Previously, sync operations completed silently with only individual operation logs. Now you get a clear summary that makes it easy to verify large sync operations completed as expected.

Example Output

This summary appears for both sync-to-remote and sync-to-local operations after successful completion.

chevron-rightv0.2.11 - Flexible Service Tag Format (January 10, 2026)hashtag

Agent Forge v0.2.11 simplifies service tag configuration by supporting simple string arrays in local JSON/YAML files, in addition to the existing object format.

Why This Matters: Previously, services required verbose object-format tags ([{"key": "phone", "value": null}]), while agents used simple string arrays (["phone"]). This inconsistency made manual editing error-prone and confusing. Now both formats work for services.

Before (required):

After (recommended):

Or in YAML:

Key Changes:

  • ServiceLocalSchema.tags now accepts Union[List[str], List[TagSchema]]

  • New get_tags_as_strings() helper method for normalized tag access

  • map_local_tags_to_create_update_request_tags() handles string, TagSchema, and dict formats

  • Both formats are automatically converted to API format during sync

  • Legacy object format continues to work (backward compatible)

How to Get It

  1. Check out main and git pull to pick up the latest CLI.

  2. Run poetry install to refresh dependencies.

Related Documentation

chevron-rightv0.2.10 - Regional LLM Availability (January 10, 2026)hashtag

Agent Forge v0.2.10 introduces region-based LLM availability validation, ensuring that presets are only deployed to regions where their underlying LLMs are available.

Why This Matters: Not all LLMs are deployed in every region. GPT-5.1 is only available in US and EU regions (not CA or AU). Deploying a preset that uses GPT-5.1 to an unsupported region would cause runtime failures. This validation catches these issues before deployment.

LLM Regional Availability

LLM
US
CA
EU
AU

GPT-4.1, GPT-4.1-mini

✓

✓

✓

✓

GPT-5, GPT-5-mini, GPT-5-nano

✓

✓

✓

✓

GPT-5.1

✓

✗

✓

✗

Claude Sonnet 4.5 (Google/AWS)

✓

✓

✓

✓

Gemini 2.5 Pro/Flash

✓

✓

✓

✓

Affected Presets

Presets using GPT-5.1 will fail regional validation in CA and AU regions:

  • text_premium

  • async

  • async_premium

CLI Validation

Use the forge channel validate-preset command with the --region flag to check preset compatibility:

How to Get It

  1. Check out main and git pull to pick up the latest CLI.

  2. Run poetry install to refresh dependencies.

Related Documentation

chevron-rightv0.2.9 - Channel-Based Tagging System (January 10, 2026)hashtag

Agent Forge v0.2.9 introduces a channel-based tagging system for configuring services based on deployment channel (voice, text, async) with validation integrated into the sync workflow.

Why This Matters: Different deployment channels have distinct latency requirements, feature constraints, and LLM optimization needs. The channel tagging system enables teams to configure services appropriately for each channel and validate configurations before sync, preventing misconfigurations that could impact user experience.

Supported Channels

Channel
Type
Use Case

phone

voice

Telephony (PSTN/VoIP)

web_voice

voice

Browser WebRTC

mobile_voice

voice

Mobile app voice

sms

text

SMS messaging

whatsapp

text

WhatsApp

web_chat

text

Web chat widget

mobile_chat

text

Mobile app chat

email

async

Email

api

async

Direct API

Version Set Presets

Tier
Voice
Text
Async

Standard

voice (GPT-4.1-mini)

text (GPT-5-mini)

async (GPT-5 + GPT-5.1)

Premium

voice_premium (GPT-4.1)

text_premium (GPT-5.1)

async_premium (GPT-5.1)

Economy

voice_economy (GPT-4.1-mini)

text_economy (GPT-5-nano)

async_economy (GPT-5-nano)

Ultra-Low

voice_ultra_low (GPT-4.1-mini)

—

—

Ultra-Low Premium

voice_ultra_low_premium (GPT-4.1)

—

—

Ultra-Low Latency Presets

The voice_ultra_low and voice_ultra_low_premium presets are designed for single-state context graphs:

  • All action states must have exactly 1 action

  • All action states must have 0 exit conditions

  • Skips select_next_action LLM call entirely (backend fast path)

  • Saves 100-500ms latency per turn

Tag Format

Services use tags in key-only format:

Sync Validation Integration

  • Services with channel tags are validated before syncing to remote

  • Validates that preset tags match the channel type (e.g., voice presets only for voice channels)

  • Voice services warn if missing keyterms (for transcription accuracy)

  • Validation errors block sync, warnings prompt confirmation

New CLI Commands (forge channel)

Command
Description

list-channels

Show all supported channels with profiles

list-presets

Show version set presets with LLM configurations

show-profile <channel>

Show channel profile and constraints

show-tags <channel>

Show tags for a channel/preset combination

validate-preset <preset> <channel>

Validate preset compatibility

validate-context-graph

Validate context graph for channel constraints

llm-info

Show LLM catalog with voice-optimized recommendations

interactions

List backend LLM interaction types

Example Usage

How to Get It

  1. Check out main and git pull to pick up the latest CLI.

  2. Run poetry install to refresh dependencies.

Related Documentation

chevron-rightv0.2.8 - Role Provisioning CLI (January 9, 2026)hashtag

Agent Forge v0.2.8 introduces role provisioning capabilities, enabling organizations to create and manage predefined roles for sandbox and development environments.

Why This Matters: Platform administrators with DefaultAmigoAdministratorRole cannot view client conversations in sandbox environments due to production security restrictions. The new AgentEngineerRole addresses this limitation for development and testing workflows.

New CLI Commands

Predefined Roles

Role Name
Frontend View
Use Case

AgentEngineerRole

admin

Sandbox role for agent engineers with platform admin privileges and full org-scoped conversation visibility

DemoProspectRole

client

Restricted role for demo/prospect users with self-scoped permissions and read-only access

AgentEngineerRole vs DefaultAmigoAdministratorRole

The key difference is conversation visibility:

Permission
DefaultAmigoAdministratorRole
AgentEngineerRole

Conversation:GetConversation

Role-restricted (admin roles only)

Org-scoped (all conversations)

Conversation:GetMessage

Role-restricted

Org-scoped

Conversation:GetInteractionInsights

Role-restricted

Org-scoped

User:GetUserModel

Role-restricted

Org-scoped

Usage

To enable AgentEngineerRole for a sandbox environment:

  1. Provision the role:

  2. Assign users to the role via Amigo platform UI:

    • Navigate to Settings > Users

    • Select the user

    • Change their role to AgentEngineerRole

How to Get It

  1. Check out main and git pull to pick up the latest CLI.

  2. Run poetry install to refresh dependencies.

chevron-rightv0.2.7 - Dynamic Behavior Actions Array (January 7, 2026)hashtag

Agent Forge v0.2.7 updates the dynamic behavior schema to support multiple actions per behavior, aligning with the backend schema migration where the action field has been renamed to actions and is now an array.

What Changed

  • The action field in DynamicBehaviorSetVersion has been renamed to actions and is now an array

  • Added support for new action types:

    • inject-instruction (existing) - Injects instruction text into the agent's context

    • change-tool-candidates (new) - Modifies available tool candidates with version constraints, audio fillers, and result persistence settings

  • Uses a discriminated union on the type field for type-safe action handling

Schema Changes

The actions array now accepts objects with a type discriminator:

New change-tool-candidates action type (for future use):

Migration Guide

If you have local dynamic behavior YAML files using the old action field:

  1. Re-sync from remote to get the updated schema:

  1. Or manually update your files to use actions: [...] instead of action: {...}

How to Get It

  1. Check out main and git pull to pick up the latest CLI.

  2. Run poetry install to refresh dependencies.

chevron-rightv0.2.6 - Continuation Token Fix (December 3, 2025)hashtag

Agent Forge v0.2.6 fixes a type mismatch in metric and persona entity pagination response schemas that caused Pydantic validation errors during sync operations for metrics and personas.

What Changed

Changed continuation_token from Optional[str] to Optional[Any] in the following response schemas:

  • MetricListResponseSchema

  • PersonaListResponseSchema

  • PersonaVersionListResponseSchema

How to Get It

  1. Check out main and git pull to pick up the latest CLI.

  2. Run poetry install to refresh dependencies.

chevron-rightv0.2.5 - Improved Logline Formatting (December 2, 2025)hashtag

Agent Forge v0.2.5 improves logline formatting to provide clearer, more structured log output with consistent timestamp and log level formatting.

What Changed

Loglines now follow a standardized format that is prefixed with the ISO 8601 timestamp in the local timezone.

Example Output

How to Get It

  1. Check out main and git pull to pick up the latest CLI.

chevron-rightv0.2.4 - Null Field Update Fix (November 28, 2025)hashtag

Agent Forge v0.2.4 addresses a regression where sync operations for certain context graph, persona, and unit test set silently skipped updates whenever the desired value for a field was null.

What Was Affected

  • forge sync-to-remote for context graphs, personas, and unit test set whenever a field needed to be explicitly cleared

How to Get It

  1. Check out main and pull the latest changes

Verification Tip

Use forge sync-to-remote --dry-run --entity-type <type> --env <env> to confirm that fields slated to become null now appear in the preview diff before applying changes.

chevron-rightv0.2.3 - Versioned Entity Rollbacks (November 24, 2025)hashtag

Bring remote entity histories into your workflow with an interactive rollback command that works for every versioned entity type except tools (agents, context graphs, dynamic behavior sets, personas, and scenarios).

How to Get It

  1. Check out main and git pull to pick up the latest CLI.

  2. Run poetry install to refresh dependencies.

How to Use

What Happens

  1. The CLI fetches remote versions for the target entity and renders them newest-first with relative and absolute timestamps (✅ highlights the current head).

  2. You select the desired version; the CLI diff engine compares it against the current remote version and previews the changed fields.

  3. After confirmation, a new version is created on the remote with the selected contents, then synced back to your local workspace. Any existing local changes for that entity will be overwritten without an extra prompt.

Example Session

Why It Matters

  • Provides a safe, auditable way to recover or inspect prior entity definitions without manual JSON surgery.

Operational Notes

  • Selecting the current version (empty diff) exits early to avoid no-op rollbacks.

  • Local sync runs immediately after the remote version is updated; ensure you have no unsaved local edits for that entity before confirming.

chevron-rightv0.2.2 - Automatic Tool Version Deprecation (November 22, 2025)hashtag

Agent Forge v0.2.2 introduces automatic tool version management to help maintain optimal performance and simplify version lifecycle management.

What Changed:

When publishing a new tool version with forge action publish, the CLI now automatically:

  1. First checks if 3 or more active tool versions exist

  2. Prompts to deprecate the oldest versions to ensure that there is capacity before attempting to publish the new version

  3. Provides clear visibility into which versions will be deprecated before proceeding

Why This Matters: Maintaining a focused set of active tool versions improves performance, simplifies version management, and encourages best practices for tool lifecycle management. Most teams only need to support the latest versions while maintaining backward compatibility for recent deployments.

How It Works:

Before attempting to publish a new tool version, if 3 or more active versions exist, the CLI will:

  1. Display the total count of active versions

  2. List the oldest versions proposed for deprecation, showing:

    • Version number

    • Creation timestamp

    • Repository and lambda version

  3. Prompt for confirmation (defaults to "Yes")

  4. Deprecate approved versions with individual success/failure reporting

Example Output:

Skipping Auto-Deprecation:

Use the --skip-auto-deprecate flag to bypass the automatic check:

Important Notes:

  • You can decline the deprecation prompt and manage versions manually

  • If any deprecations fail, the process aborts and the console will print the commands to manually retry the individual deprecations

  • Versions are sorted by semantic versioning (major.minor.patch) to ensure oldest versions are deprecated first

  • Context graphs referencing deprecated versions will experience the following behavior:

    • Tool-call state: The interaction will error out

    • Other states: The agent will proceed as if the tool isn't specified

Breaking Change:

The --id parameter is now required for forge action publish (previously optional). This change improves command clarity and prevents accidental publishes to the wrong tool.

Migration Guide:

If you previously relied on interactive prompts for the action ID, update your scripts:

Related Commands:

  • forge action version delete - Manually deprecate specific tool versions

chevron-rightv0.2.1 - ToolCallState Schema Support (November 20, 2025)hashtag

Agent Forge v0.2.1 (PR #133arrow-up-right) adds full schema support for the new ToolCallState type in Context Graph definitions, enabling local management and deployment of tool-call states through the Agent Forge CLI.

circle-info

This release accompanies API v0.6.1. See Amigo API changelog for backend changes.

chevron-rightv0.2.0 - Tool Call Result Persistence (November 13, 2025)hashtag

Agent Forge v0.2.0 (PR #132arrow-up-right) adds support for the result_persistence field in Context Graph tool call specifications. You can now control tool call result persistence directly in your local JSON files.

circle-exclamation

Breaking Change: The result_persistence field is now required in all tool call specifications.

TL;DR: Add "result_persistence": "persisted-preferred" to all tool_call_specs in your Context Graphs. See migration guide below

Use Cases:

Use Case
Recommended Mode
Why

General-purpose tools

"persisted-preferred"

Gracefully handles large outputs

Database queries, file reads

"ephemeral"

Results too large to persist efficiently

Critical decision data

"persisted"

Must always be available to agent

Before & After

Before (v0.1.x) - Field optional, defaulted to "persisted":

After (v0.2.0) - Field required:

Where It Applies

The result_persistence field is required in all tool call specifications within Context Graph state definitions. This includes:

  • ActionState: action_tool_call_specs[] and exit_condition_tool_call_specs[]

  • DecisionState: tool_call_specs[]

  • ReflectionState: tool_call_specs[]

For persistence mode details and character limits, see the Amigo API changelog.

Who This Affects

✅ Requires Action:

  • Developers creating new Context Graphs

  • Developers modifying existing Context Graphs

  • CI/CD pipelines that deploy Context Graph configurations

  • Teams using forge sync-to-remote to push local changes

⚠️ No Action Needed:

  • Already-deployed agents (backward compatible)

  • Users only reading Context Graphs

  • Users syncing from remote to local (remote backfilled automatically)

Migration Guide

Automatic Backfill: The platform automatically backfilled all remote Context Graphs with "result_persistence": "persisted" to maintain backward compatibility. Your local Context Graphs need to be updated to match.

Option 1: Re-sync from Remote (Recommended)

This is the fastest path and ensures your local files match the platform state.

⚠️ Warning: This deletes local Context Graph JSON files. Ensure you've committed or stashed any local modifications first.

Option 2: Manual Update

Update each tool call specification manually if you have extensive local changes:

  1. Open each Context Graph JSON file in local/*/entity_data/context_graph/

  2. Find all tool call specification objects

  3. Add "result_persistence": "persisted" to each specification

  4. Recommended: Change "persisted" to "persisted-preferred" for most tools

Validation: After migration, verify your changes:

Troubleshooting

Error: "result_persistence field is required"

  • Cause: Context Graph definition missing the result_persistence field

  • Fix: Follow the migration guide above to add the field

Error: "Field required" when syncing to remote

  • Cause: Local JSON files haven't been updated with the new field

  • Fix: Re-sync from remote (Option 1) or manually add the field (Option 2)

Unexpected diffs when running forge sync-to-remote

  • Cause: Local files still use old schema without result_persistence

  • Fix: Compare with remote using git diff after re-syncing to identify mismatches

Getting 400 errors when deploying Context Graphs

  • Cause: API now enforces result_persistence as required

  • Fix: Ensure all tool call specs include the field before deployment

Related Resources

hashtag
Versioning

The Agent Forge SDK follows Semantic Versioningarrow-up-right with the format MAJOR.MINOR.PATCH:

  • MAJOR version (currently 0): Pre-1.0 indicates active development. Breaking changes may occur between minor versions.

  • MINOR version: New features, enhancements, or significant changes. May include breaking changes during pre-1.0 development.

  • PATCH version: Bug fixes, documentation updates, and minor improvements without breaking changes.

Product
Version
Stage
Compatibility

Agent Forge SDK

v0.2.x

Early release

Compatible with API v0.6.0+

PreviousChange LogsNextAmigo API

Last updated

Was this helpful?