search
Go to website

hammerAgent Forge SDK

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

circle-info

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

chevron-rightv0.3.7 - Simulation Loop CLI Commands (January 26, 2026)hashtag

Agent Forge v0.3.7 introduces comprehensive simulation loop commands for automated end-to-end conversation testing. These commands enable coding agents (Claude Code, Cursor, etc.) to drive conversations programmatically via the CLI.

Why This Matters: Testing agent conversations previously required manual interaction or custom scripts. Now you can run full automated simulations with configurable personas, scenarios, and temperaments directly from the CLI. The simulate-step command enables coding agents to drive conversations step-by-step, choosing which recommended response to send.

New Commands

Command
Description

forge conversation list-personas

List available personas (local files or API)

forge conversation list-scenarios

List available scenarios (local files or API)

forge conversation start

Start a new conversation with a service

forge conversation send

Send a message to an existing conversation

forge conversation finish

Mark a conversation as finished

forge conversation simulate

Run full automated conversation simulation

forge conversation simulate-batch

Run multiple simulations from config file

forge conversation simulate-step

Agent-driven step-by-step conversation steering

Example: Full Automated Simulation

# Run simulation with persona and scenario
forge conversation simulate --service "My Service" --env dogfood \
  --persona "Amanda Foster" \
  --scenario "Billing Inquiry" \
  --max-turns 10 \
  --json

# User speaks first (instead of agent greeting)
forge conversation simulate --service "My Service" --env dogfood \
  --initial-message "I need help with my bill" \
  --persona "Amanda Foster" \
  --json

# With exit conditions
forge conversation simulate --service "My Service" --env dogfood \
  --persona "Amanda Foster" \
  --stop-on-finished \
  --stop-on-pattern "goodbye|thank you" \
  --json

Example: Agent-Driven Step-by-Step Testing

The simulate-step command is designed for coding agents to drive conversations with precise control:

# Start a new conversation and get initial state with recommendations
forge conversation simulate-step --start -s "My Service" -e dogfood

# Get current state of existing conversation (no message sent)
forge conversation simulate-step CONV_ID -e dogfood

# Send a message and get updated state with new recommendations
forge conversation simulate-step CONV_ID -e dogfood --send "I'd like to cancel"

# With persona/scenario context for better recommendations
forge conversation simulate-step CONV_ID -e dogfood \
  --send "Yes, please proceed" \
  --persona "Amanda Foster" \
  --scenario "Billing Inquiry" \
  --temperament frustrated

Example: Batch Simulations

Run multiple simulations from a configuration file:

# Create config file
cat > simulations.json << 'EOF'
{
  "simulations": [
    {
      "name": "billing_cooperative",
      "service": "Customer Service",
      "persona": "Amanda Foster",
      "scenario": "Billing Inquiry",
      "temperament": "cooperative",
      "max_turns": 10
    },
    {
      "name": "billing_frustrated",
      "service": "Customer Service",
      "persona": "Amanda Foster",
      "scenario": "Billing Inquiry",
      "temperament": "frustrated",
      "max_turns": 10
    }
  ]
}
EOF

# Run batch simulations
forge conversation simulate-batch simulations.json -e dogfood -o ./results

Example: Deterministic Workflows

Use --save and --pick-from for reproducible testing:

# Save recommended responses to a file
forge conversation recommend-responses CONV_URL --save responses.txt

# Later, pick a specific response
forge conversation send CONV_ID -e dogfood --pick-from responses.txt --index 1

Enhanced Commands

  • recommend-responses: Added --save and --pick options for deterministic workflows

Key Features

  • JSON-first output: All commands support --json for scripting and automation

  • Flexible input: Accept conversation ID + --env or full Amigo URL

  • Agent-driven steering: simulate-step enables coding agents to drive conversations step-by-step

  • Deterministic workflow: recommend-responses --save then send --pick-from --index

  • Temperament options: cooperative, neutral, frustrated, confused, skeptical

  • Response modes: production, test, edge_cases, exit_conditions

  • User-first simulations: --initial-message option for user-speaks-first scenarios

Exit Reasons

Simulations track why they ended via typed ExitReason enum:

Exit Reason
Description

max_turns_reached

Reached the maximum turn limit

conversation_finished

Agent marked conversation as complete

pattern_matched

Agent response matched --stop-on-pattern regex

no_interaction_id

Could not retrieve interaction ID

no_recommended_responses

No responses generated

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.3.6 - Tool Version Schema Cleanup (January 25, 2026)hashtag

Agent Forge v0.3.6 removes the unused tool_repo field from the Tool Version schema, simplifying the data model and CLI output.

Why This Matters: The tool_repo field in Tool Version schemas was no longer being used. Removing it streamlines the schema definition and reduces unnecessary information in CLI tool version displays.

What Changed

  • Removed tool_repo field from ToolVersionSchema

  • Updated forge action publish output formatting to omit repository information

  • Removed validation tests for invalid repository values

Breaking Changes

  • Tool Version schemas no longer include the tool_repo field

  • CLI output for tool versions no longer displays repository information (now shows only lambda version: (lambda=...))

Migration Guide

No action required. This change only removes an unused field from the schema.

Related Pull Request

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.3.5 - Databricks MCP Integration (January 23, 2026)hashtag

Agent Forge v0.3.5 introduces the forge databricks command group for configuring Databricks MCP integration with Claude Code. This enables Claude Code to execute SQL queries directly against your Databricks workspaces.

Why This Matters: When working with data-intensive workflows, developers often need to query Databricks workspaces. Previously, this required manual configuration of MCP servers. Now you can automatically generate the required .mcp.json configuration from your existing Databricks CLI profiles, enabling seamless Claude Code integration with your data infrastructure.

New Commands

Command
Description

forge databricks setup

Generate .mcp.json from ~/.databrickscfg profiles

forge databricks validate

Check config format and token presence

forge databricks status

Show configured/unconfigured workspaces

Example: Quick Setup

# Generate .mcp.json from your existing Databricks CLI config
poetry run forge databricks setup

# Validate the configuration
poetry run forge databricks validate

# View configured workspaces
poetry run forge databricks status

Example: Setup with Options

# Specify output path
poetry run forge databricks setup --output ~/projects/my-project/.mcp.json

# Overwrite existing configuration
poetry run forge databricks setup --force

# Use custom Databricks config location
poetry run forge databricks setup --config /path/to/databrickscfg

Supported Workspaces

The following Databricks workspaces are preconfigured:

Profile Name
Host
MCP Server Name

staging-us-east-1

dbc-088d0a13-3db3.cloud.databricks.com

databricks-staging-sql

production-us-east-1

dbc-13c72ec4-a3aa.cloud.databricks.com

databricks-prod-us-east-sql

production-ca-central-1

dbc-3f59c474-ef79.cloud.databricks.com

databricks-prod-ca-sql

production-eu-central-1

dbc-869e9f5b-1095.cloud.databricks.com

databricks-prod-eu-sql

production-ap-southeast-2

dbc-c326181c-95de.cloud.databricks.com

databricks-prod-ap-sql

Merging with Existing MCP Configurations

If your .mcp.json already contains other (non-Databricks) MCP server configurations, running forge databricks setup --force will preserve them. Only Databricks-related servers (those with names starting with databricks-) will be updated.

Verifying the Integration

After running forge databricks setup:

  1. Restart Claude Code to load the new configuration

  2. Check MCP server status - Claude Code should show the connected Databricks servers

  3. Test with a simple query - Ask Claude to run SHOW CATALOGS on a Databricks workspace

Security Note

The .mcp.json file contains authentication tokens and is automatically added to .gitignore. Never commit this file to version control.

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.3.4 - Prompt Template Linting (January 22, 2026)hashtag

Agent Forge v0.3.4 introduces the forge prompt-lint command for detecting and fixing Unicode characters in entity data that cause LLM output degeneration.

Why This Matters: Unicode characters (smart quotes, em dashes, bullets) in prompt templates can shift token boundaries, causing repetitive loops, foreign character injection, and word fragments in LLM outputs. This linter catches these issues before they reach production.

New Commands

Command
Description

forge prompt-lint check

Lint entity data files for tokenization issues

forge prompt-lint fix

Auto-fix common Unicode issues

forge prompt-lint rules

Display lint rules reference

Example: Check for Issues

# Check all entity data
forge prompt-lint check

# Check specific environment
forge prompt-lint check -p ./local/dogfood

# Check specific entity types
forge prompt-lint check -t dynamic_behavior_set -t agent

# Strict mode (warnings become errors)
forge prompt-lint check --strict

Example: Auto-fix Issues

# Dry run - see what would be fixed
forge prompt-lint fix

# Apply fixes
forge prompt-lint fix --apply

# Fix specific entity types only
forge prompt-lint fix -t agent --apply

What Gets Fixed

Banned Character
Replacement

' ' (smart quotes)

'

" " (smart quotes)

"

— (em dash)

--

– (en dash)

-

• (bullet)

*

→ (arrow)

->

≥ ≤ (comparison)

>= <=

Zero-width chars

(removed)

Entity Fields Checked

The linter only checks fields that are injected into LLM prompts:

Entity Type
Fields

agent

background, behaviors, communication_patterns

dynamic_behavior_set

conversation_triggers, actions[*].instruction

context_graph

description, global_* guidelines, states[].

metric

description

persona

background

scenario

objective, instructions

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.3.3 - Recommended Responses for Conversation Testing (January 21, 2026)hashtag

Agent Forge v0.3.3 introduces the forge conversation recommend-responses command for generating synthetic user responses during conversation testing. This enables automated testing of agent behavior with configurable personas, temperaments, and scenarios.

Why This Matters: Testing agent conversations previously required manual input or custom scripts. Now you can generate realistic user responses based on personas and scenarios directly from the CLI, enabling systematic testing of edge cases, frustrated users, and various conversation flows.

New Command

Command
Description

forge conversation recommend-responses

Generate synthetic user responses for testing

Example: Basic Usage

# Get recommended responses for the latest interaction
forge conversation recommend-responses https://dogfood.amigo.ai/admin/conversation/6943164fd1441af6f6fd1f64

# Output:
# Recommended Responses
# ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
# ┃ Response                                              ┃
# ┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
# │ Yes, I'd like to schedule an appointment              │
# │ Can you tell me more about your services?             │
# │ What are your hours of operation?                     │
# └───────────────────────────────────────────────────────┘

Example: With Persona and Scenario

Load personas and scenarios from local entity files or the API:

# Load persona and scenario by name
forge conversation recommend-responses https://dogfood.amigo.ai/admin/conversation/6943164fd1441af6f6fd1f64 \
  --persona "Amanda Foster" \
  --scenario "Billing Inquiry"

# Or specify custom persona details
forge conversation recommend-responses https://dogfood.amigo.ai/admin/conversation/6943164fd1441af6f6fd1f64 \
  --persona-name "Busy Parent" \
  --persona-background "Working parent with limited time, prefers quick answers"

Example: Configure Temperament and Response Mode

# Generate frustrated user responses
forge conversation recommend-responses https://dogfood.amigo.ai/admin/conversation/6943164fd1441af6f6fd1f64 \
  --temperament frustrated

# Generate edge case responses for testing
forge conversation recommend-responses https://dogfood.amigo.ai/admin/conversation/6943164fd1441af6f6fd1f64 \
  --mode edge_cases

# Simulate voice channel input (transcribed speech patterns)
forge conversation recommend-responses https://dogfood.amigo.ai/admin/conversation/6943164fd1441af6f6fd1f64 \
  --input-channel voice

Example: Add Custom Observations

forge conversation recommend-responses https://dogfood.amigo.ai/admin/conversation/6943164fd1441af6f6fd1f64 \
  --observation "User seems impatient" \
  --observation "Previous call was dropped"

Options Reference

Option
Description

--persona

Load persona by name from local files or API

--persona-name

Custom persona name (overridden by --persona)

--persona-background

Custom persona background

--scenario

Load scenario by name from local files or API

--scenario-name

Custom scenario name

--scenario-objective

Custom scenario objective

--temperament

User temperament: cooperative, neutral, frustrated, confused, skeptical

--mode

Response mode: production, test, edge_cases, exit_conditions

--input-channel

Input channel: text, voice

--observation

Additional observations (repeatable)

--interaction-id

Specific interaction ID (defaults to latest)

--json

Output as JSON

--show-context

Display the context string sent to the API

Temperaments

Temperament
Description

cooperative

Helpful, clear, engaged user

neutral

Standard responses, neither positive nor negative

frustrated

Impatient, may express dissatisfaction

confused

Uncertain, may ask for clarification

skeptical

Doubtful, questions agent responses

Response Modes

Mode
Description

production

Realistic user responses

test

Standard test scenarios

edge_cases

Unusual or boundary condition responses

exit_conditions

Responses that might end the conversation

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.3.2 - Conversation Commands (January 20, 2026)hashtag

Agent Forge v0.3.2 introduces the forge conversation command group for fetching and analyzing conversation transcripts directly from the CLI. This enables debugging and feedback processing workflows without leaving the terminal.

Why This Matters: When processing user feedback that includes conversation URLs, developers previously had to navigate the web platform or make direct API calls to understand what happened. Now you can fetch, view, and analyze conversations directly from the CLI, with special support for debugging via the insights command.

New Commands

Command
Description

forge conversation get

Fetch and display conversation messages with rich formatting

forge conversation transcript

Get a plain text transcript of the conversation

forge conversation insights

Debug view with states, dynamic behaviors, and tool calls

forge conversation batch

Process multiple conversations from a file

URL Format Support

The commands accept full conversation URLs in multiple formats:

Example: View Conversation

Example: Debug with Insights

The insights command is powerful for debugging. It shows for each interaction:

  • State: Which context graph state the agent was in

  • Dynamic Behaviors: Which dynamic behavior was triggered (if any)

  • Tool Calls: Which tools were called, their inputs, outputs, and duration

  • State Transitions: How the agent navigated through the context graph

Example: Batch Processing

Process multiple conversations from a file containing URLs:

Key Features

  • Rich console output: Messages displayed with timestamps, senders, and proper formatting

  • Multiple output formats: Human-readable tables, plain text transcripts, or JSON

  • Flexible filtering: Filter by message type, limit messages, include/exclude thoughts

  • Batch processing: Process multiple conversations with progress tracking

  • Debug insights: View context graph states, dynamic behaviors, and tool call details

  • URL parsing: Automatically extracts org and conversation ID from URLs

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.3.1 - Prompt Log Retrieval (January 20, 2026)hashtag

Agent Forge v0.3.1 introduces the forge prompt-log command group for downloading and viewing rendered prompt logs from conversations. This enables debugging and analysis of LLM interactions without leaving the CLI.

Why This Matters: Understanding what prompts were sent to the LLM during a conversation is critical for debugging agent behavior. Previously, accessing prompt logs required navigating the web platform or making direct API calls. Now you can retrieve, view, and download prompt logs directly from the CLI.

circle-exclamation

30-Day Retention: Prompt logs are only available for conversations within the last 30 days.

New Commands

Command
Description

forge prompt-log types

List all prompt log types with required parameters

forge prompt-log download

Download prompt logs to ZIP file or extracted directory

forge prompt-log show

Display prompt log content directly in terminal

Supported Prompt Types

Type
Description
Required Parameters

engage_user

Main conversation prompt

conversation, interaction

dynamic_behavior

Behavior selection prompt

conversation, interaction

reflection

Agent reflection prompt

conversation, interaction, state_transition

action

Action selection prompt

conversation, interaction, state_transition

decision

Decision state prompt

conversation, interaction, state_transition

memory_check

Memory check prompt

conversation, interaction

memory_extract

Memory extraction prompt

conversation, interaction

memory_query

Memory query prompt

conversation, interaction

tool_params

Tool parameter generation

conversation, interaction, state_transition

compute_metrics

Post-session metrics computation

conversation, metric_index

Example: View Prompt for a Conversation

Example: Download Prompts for Analysis

Advanced: Raw Prefix

For advanced users, you can specify a raw S3 prefix directly:

Key Features

  • Type discovery: forge prompt-log types shows all types with required parameters

  • Flexible output: View in terminal, download as ZIP, or extract to directory

  • Filter options: --system-only or --history-only to view specific parts

  • Raw prefix support: Direct S3 prefix for advanced queries

  • Rate limit aware: Endpoint limited to 5 requests/minute

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.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

Running Migrations

Example Migration Output

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:

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

Service Integration

Services now display applied dynamic behaviors:

Version Set Enhancement

Version sets now track behavior configurations:

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

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

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

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

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?