Agent Forge SDK

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

Current Version: v0.3.22 | Compatibility: Amigo API v0.7.0+

---

v0.3.22 - Temporary Conversation Access & AgentEngineerRole Removal (March 3, 2026)

Agent Forge v0.3.22 replaces the overly-permissive AgentEngineerRole with per-conversation, time-limited access grants. Engineers now request temporary access to specific conversations instead of having blanket org-wide visibility.

Why This Matters: The AgentEngineerRole granted full conversation visibility across the entire organization -- far more access than needed for debugging a single conversation. The new temporary access system enforces least-privilege: engineers request access to a specific conversation with a justification, and the grant expires automatically (default: 2 hours).

New Commands

Command	Description
forge conversation request-access	Request time-limited access to a specific conversation
forge conversation list-access	List active and expired temporary access grants

Example: Request Conversation Access

# Request access to a conversation (default: 2 hours)
forge conversation request-access https://org.amigo.ai/admin/conversation/abc123 \
    -j "Debugging reported issue #42"

# Custom duration
forge conversation request-access abc123def456abc123def456 -e production \
    -j "Reviewing feedback" -d PT4H

# Grant access to a colleague
forge conversation request-access https://org.amigo.ai/admin/conversation/abc123 \
    -j "Pair debugging session" --user-email [email protected]

Example: List Active Grants

# List your active grants
forge conversation list-access -e production

# Show all users' grants including expired
forge conversation list-access -e production --all --show-expired

# JSON output for scripting
forge conversation list-access -e production --json

Command Options: forge conversation request-access

Option	Required	Default	Description
CONVERSATION	Yes	--	Conversation URL or 24-char ID
--env / -e	Conditional	From URL	Environment name
--justification / -j	Yes	--	Reason for access (min 10 chars)
--duration / -d	No	PT2H	ISO 8601 duration (e.g., PT2H, PT30M, P1D)
--user-email	No	Self	Grant access to another user by email
--json	No	false	JSON output

Command Options: forge conversation list-access

Option	Required	Default	Description
--env / -e	Yes	--	Environment name
--all	No	false	Show grants for all users
--show-expired	No	false	Include expired grants
--json	No	false	JSON output

Breaking Change: AgentEngineerRole Removed

The AgentEngineerRole predefined role has been removed from forge role list and forge role provision. If you were using this role:

1. Use forge conversation request-access to get per-conversation access as needed

2. The underlying platform admin role (DefaultAmigoAdministratorRole) remains unchanged

3. Existing AgentEngineerRole assignments in organizations are not affected (the role still exists remotely if previously provisioned)

Key Behaviors

• Each request-access call creates 3 permission grants: GetConversation, GetMessage, GetInteractionInsights

• Grants are scoped to the specific conversation's owner and organization

• Grants auto-expire after the specified duration

• All grants are tagged with source: forge-cli and the conversation ID for auditability

• Partial failures are reported (e.g., if 2 of 3 grants succeed)

Related Pull Request

• agent-forge#294 - Add temporary conversation access CLI and remove 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.

v0.3.21 - User Management & Impersonation (February 20, 2026)

Agent Forge v0.3.21 adds a full forge user command group for user CRUD operations and a --user impersonation flag on conversation commands, enabling developers to run conversations as any existing user without creating ephemeral test accounts.

Why This Matters: Testing user-specific agent behaviors (personalized context, memory, conversation history) previously required either creating disposable test users or manually calling the API. The new forge user commands provide first-class user management, and the --user flag lets you run smoke tests or simulations as any real user via API key impersonation.

New Command Group: forge user

Command	Description
forge user list	List users with search, email filter, and pagination
forge user get	Get user details by ID or email (shows conversation and memory counts)
forge user create	Create a new user with optional initial context
forge user update	Update user context entries
forge user delete	Remove a user from the organization

New Flag: --user / -u on Conversation Commands

Command	Description
forge conversation smoke-test --user	Run smoke test as an existing user
forge conversation simulate --user	Run simulation as an existing user
forge conversation simulate-step --user	Run step-by-step simulation as an existing user

Example: User Management

# List users with search
forge user list -e myorg --search "john"

# Get user by email
forge user get -e myorg --email "[email protected]"

# Create user with context
forge user create -e myorg --first-name John --last-name Doe --email "[email protected]" \
  -c "Care Recipient: Bella, Age 5"

# Update user context
forge user update -e myorg -u USER_ID -c "New context entry"

# Delete user
forge user delete -e myorg -u USER_ID

Example: Impersonation

# Smoke test as a specific user
forge conversation smoke-test -s "My Service" -e myorg --user USER_ID -m "Hello"

# Smoke test with email lookup
forge conversation smoke-test -s "My Service" -e myorg --user "[email protected]" -m "Hello"

# Simulate as a specific user with temporary context
forge conversation simulate -s "My Service" -e myorg --user USER_ID \
  --additional-context "Temporary test context" --max-turns 5

Command Options: forge user list

Option	Description
--env / -e	Environment name (required)
--search / -q	Search by name or email
--email	Filter by exact email
--limit	Maximum results to show
--json	JSON output for scripting

Command Options: forge user create

Option	Description
--env / -e	Environment name (required)
--first-name	User's first name (required)
--last-name	User's last name (required)
--email	User's email (required)
--role	Role to assign (default: DefaultUserRole)
--context / -c	Context string to add (repeatable)
--file / -f	File containing context entries

Key Behaviors

• --user accepts either a user ID or email address (auto-resolves email to ID)

• Impersonation requires API key authentication (Firebase auth does not support impersonation)

• When --user is combined with --additional-context, the user's original context is saved, temporarily replaced, and restored after the test

• forge test-user set-context is deprecated in favor of forge user update -c

• forge user manages real accounts; forge test-user manages ephemeral simtest_* accounts for parallel testing

Related Pull Request

• agent-forge#268 - Add forge user commands and --user impersonation flag

How to Get It

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

2. Run poetry install to refresh dependencies.

v0.3.20 - Version List Pagination & Sorting (February 20, 2026)

Agent Forge v0.3.20 adds a --newest-first flag and automatic pagination to all version-list commands, overcoming the API's 10-item-per-page limit and enabling developers to quickly find recent versions.

Why This Matters: When agents or context graphs have many versions, the default oldest-first ordering buries the latest versions at the end. The API also returns at most 10 items per page, requiring manual pagination. This release adds descending sort and transparent multi-page fetching so --limit 50 actually returns 50 results.

Enhanced Commands

Command	Change
forge asset agent version-list	Added --newest-first / -d flag and pagination
forge asset context-graph version-list	Added --newest-first / -d flag and pagination
forge asset behavior version-list	Added --newest-first / -d flag and pagination

Example: Find Recent Versions

# Show newest versions first
forge asset agent version-list MyAgent -e production --newest-first

# Get the 50 most recent versions (fetches multiple API pages automatically)
forge asset agent version-list MyAgent -e production --newest-first --limit 50

# Works for all asset types
forge asset context-graph version-list MyGraph -e production -d --limit 20
forge asset behavior version-list "My Behavior" -e production -d

New Options

Option	Description
--newest-first / -d	Sort by version descending (newest first). Default: ascending
--limit	Maximum results to return (pagination fetches up to this count automatically)

Key Behaviors

• Pagination is transparent: the CLI automatically follows continuation_token to fetch subsequent pages up to the requested --limit

• Safety limit of 100 API pages prevents infinite loops

• Page size is optimized on the last page to fetch only remaining items

• Default sort order (ascending) is unchanged for backward compatibility

Related Pull Request

• agent-forge#269 - Add --newest-first flag and pagination to version-list 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.

v0.3.19 - Ergonomic Update Diffs (February 19, 2026)

Agent Forge v0.3.19 introduces type-aware diff formatting for entity updates, making it much easier to review what actually changed when syncing entities.

Why This Matters: Entity updates often involve nested JSON structures (agent backgrounds, context graph states, behavior triggers). Previously, diffs showed raw before/after values that were difficult to parse. The new system adapts formatting based on value type -- simple strings stay inline, long text uses unified diffs, and complex objects show semantic change summaries.

Improved Diff Display

The diff system now uses three tiers:

Value Type	Display Style	Example
Simple values (<=100 chars)	Inline in summary table	"old value" -> "new value"
Long strings (>100 chars)	Unified text diff (---/+++)	Like git diff output
Dicts/lists	Semantic DeepDiff summary	~ ['expertise'][2]: "old" -> "new"

Example: Semantic Diff Output

Field: background
  ~ ['expertise'][2]: "old text" -> "new text"
  + ['references']: list with 3 item(s)
  - ['deprecated_field']: removed
  ... and 5 more change(s)

Key Behaviors

• Inline values truncated to 120 characters for readability

• Up to 20 changes displayed per field before showing ... and N more change(s)

• Works across all entity types (agents, behaviors, context graphs, services)

• Applies to forge str and any command that shows update diffs

Related Pull Request

• agent-forge#266 - Implement more ergonomic update diffs

How to Get It

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

2. Run poetry install to refresh dependencies.

v0.3.18 - Tool Scaffold Install (February 12, 2026)

Agent Forge v0.3.18 adds a forge tool-scaffold install command that automates installation of the amigo_tool_scaffold package into tool directories using uv, streamlining the tool development setup process.

Why This Matters: Tool developers previously had to manually configure package manager authentication and run uv add commands in each tool directory. This command handles authentication, uv version validation, and package installation in a single step.

New Command

Command	Description
forge tool-scaffold install	Install amigo_tool_scaffold in tool directories

Example: Install Tool Scaffold

# Interactive tool selection (prompts for which tool to install in)
forge tool-scaffold install -e myorg

# Install in a specific tool
forge tool-scaffold install -e myorg --tool my_tool

# Install in all tools
forge tool-scaffold install -e myorg --all

# Verbose output for debugging
forge tool-scaffold install -e myorg --all --verbose

Command Options

Option	Required	Description
--env / -e	Yes	Environment name
--tool / -t	No	Install in a specific tool directory
--all	No	Install in all tool directories
--verbose / -v	No	Enable verbose output

Key Behaviors

• Requires uv >= 0.10.2 (validated at startup with a clear error message if missing)

• Discovers tools by scanning local/{env}/tools-{org_id}/ for pyproject.toml files

• Authenticates via the configured auth method (API key or Firebase)

• Runs uv auth login followed by uv add amigo_tool_scaffold for each target tool

• If neither --tool nor --all is specified, presents an interactive selection menu

Related Pull Request

• agent-forge#263 - Add tool-scaffold install command

How to Get It

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

2. Run poetry install to refresh dependencies.

v0.3.17 - Firebase Authentication (February 12, 2026)

Agent Forge v0.3.17 migrates authentication from API keys to Firebase-based Google Sign-In using the OAuth 2.0 device authorization flow (RFC 8628). Existing API key authentication remains fully supported for backward compatibility.

Why This Matters: API key management creates operational overhead -- keys must be generated, distributed securely, and rotated periodically. Firebase authentication provides a more ergonomic flow: developers sign in with their Google account once, and tokens refresh automatically. This also aligns Forge CLI authentication with the web platform's auth model.

New Authentication Method

Method	When Used	Setup
API Key (existing)	API_KEY, API_KEY_ID, API_KEY_USER_ID all present in .env	No changes needed
Firebase (new default)	API key fields absent, GOOGLE_TENANT_ID present	One-time forge auth login

New Command

Command	Description
forge auth login	Authenticate via Google Sign-In device code flow

Example: Firebase Authentication

# One-time login (opens browser prompt)
forge auth login -e myorg

# Output:
# Visit: https://www.google.com/device
# Enter code: ABCD-EFGH
# Waiting for authentication...
# Authenticated as [email protected]

Environment Configuration

# Option A: API Key Auth (unchanged)
API_KEY=your-api-key
API_KEY_ID=your-key-id
API_KEY_USER_ID=your-user-id

# Option B: Firebase Auth (new)
GOOGLE_TENANT_ID=your-tenant-id

Key Behaviors

• Auth method is selected automatically based on which environment variables are present

• Firebase tokens are cached in the system keyring for persistent, secure credentials

• Tokens refresh silently on subsequent commands (no repeated login prompts)

• Keyring save failures are non-fatal -- commands continue to work even if the system keyring is unavailable

• The --user impersonation flag (v0.3.21) requires API key auth; Firebase does not support impersonation

Related Pull Request

• agent-forge#251 - Migrate Amigo API auth to Firebase-based auth

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. Add GOOGLE_TENANT_ID to your .env.{env} file (get the tenant ID from your org admin).

4. Run forge auth login -e <env> to authenticate.

v0.3.16 - Auto-Finish for Simulations (February 11, 2026)

Agent Forge v0.3.16 adds smart conversation lifecycle management: conversations auto-finish when the agent marks them complete, and the simulate command always finishes conversations in its cleanup path to prevent orphaned sessions.

Why This Matters: Open conversations that are never finished don't trigger post-processing (memory extraction, metric evaluation). Previously, simulate-step users had to manually finish conversations, and error paths in simulate could leave conversations dangling. This release ensures conversations are always properly closed.

Enhanced Commands

Command	Change
forge conversation simulate-step	Auto-finishes when agent marks is_finished=true; new --finish flag
forge conversation simulate	Always finishes conversations in finally block; new --stop-on-finished flag

Example: Auto-Finish in Step Mode

# Start a simulation
forge conversation simulate-step --start -s "My Service" -e myorg

# Send a message -- if agent finishes the conversation, it auto-closes
forge conversation simulate-step CONV_ID -e myorg --send "Goodbye, thanks for your help"
# Output: Conversation finished (agent marked as complete)

# Explicitly finish a conversation
forge conversation simulate-step CONV_ID -e myorg --finish

Example: Stop-on-Finished in Simulate

# Stop simulation when agent finishes the conversation naturally
forge conversation simulate -s "My Service" -e myorg --stop-on-finished --max-turns 20

New Options

Command	Option	Description
simulate-step	--finish	Explicitly finish the conversation
simulate	--stop-on-finished	Stop when agent marks conversation as finished

Key Behaviors

• simulate-step: Checks is_finished in the API response; auto-finishes and includes "finished": true in JSON output

• simulate: Finishes conversations in the finally block regardless of success/error (not just for --test-user + --analyze-wait)

• Keyring save failures are now non-fatal (graceful degradation on broken macOS keychains)

Related Pull Request

• agent-forge#255 - Add auto-finish for simulation conversations and make keyring non-fatal

How to Get It

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

2. Run poetry install to refresh dependencies.

v0.3.15 - Additional Context for Test Users (February 10, 2026)

Agent Forge v0.3.15 adds first-class support for setting additional_context on test users during CLI-based agent testing. This enables testing agents that depend on user context (care recipient profiles, ages, person IDs) without manually configuring test users.

Why This Matters: Many agents rely on additional_context to personalize conversations -- for example, knowing a care recipient's name, age, or medical profile. Previously, testing these agents required manually creating users and setting context through the API. Now, smoke-test handles the full lifecycle automatically: create an ephemeral test user, set context, run the test, and clean up.

New Command

Command	Description
forge test-user set-context	Set additional context entries on a user

Command Options

Option	Description
--user-id / -u	The user ID to set context for
--context / -c	Context string to add (repeatable)
--file / -f	File containing context entries (one per line)
--env / -e	Environment name

Enhanced Command: forge conversation smoke-test

Option	Description
--additional-context / -ac	Context string for the test user (repeatable)
--additional-context-file / -acf	File containing context entries (one per line)

When either flag is provided, smoke-test auto-creates an ephemeral test user, sets the context, runs the test as that user, and cleans up afterward.

Example: Smoke Test with Context

# Test with context from a file
forge conversation smoke-test -s "My Service" -e myorg \
  -m "Bella has been having trouble sleeping" \
  --additional-context-file context.txt

# Test with inline context strings
forge conversation smoke-test -s "My Service" -e myorg \
  -m "Bella has been having trouble sleeping" \
  --additional-context "Care Recipient Profile for person named 'Bella' | Age: 5 years old" \
  --additional-context "User ID: xyz789"

Example: Standalone Context Management

# Set context from a file
forge test-user set-context -u USER_ID -e myorg -f context.txt

# Set context with inline strings
forge test-user set-context -u USER_ID -e myorg \
  -c "Care Recipient Profile for person named 'Bella' | Age: 5 years old" \
  -c "User ID: xyz789"

Key Behaviors

• When --additional-context or --additional-context-file is provided, an ephemeral test user is created automatically

• The test user is cleaned up after the test completes (including on error paths)

• JSON output includes additional_context_entries count when context was provided

• The standalone set-context command works on any existing user

Related Pull Request

• agent-forge#252 - Add additional_context support for test users

How to Get It

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

2. Run poetry install to refresh dependencies.

v0.3.14 - Interaction-Level Insights & Smoke Test (February 10, 2026)

Agent Forge v0.3.14 adds two features for faster debugging and verification: an --interaction flag on forge conversation insights for drilling into a single interaction, and a new forge conversation smoke-test command for one-shot agent verification.

Why This Matters: When debugging a conversation with dozens of interactions, fetching insights for all of them is slow and noisy. The --interaction flag lets you focus on the exact turn that has the issue. The smoke-test command fills the gap between manual start/send/finish chaining and full simulate runs -- a single command to verify an agent responds correctly after deploying changes.

New Command

Command	Description
forge conversation smoke-test	Quick one-shot test: create conversation, show response, finish

Enhanced Command

Command	Change
forge conversation insights	Added --interaction / -i flag for single-interaction deep dive

Example: Interaction-Level Insights

# Full conversation insights (existing behavior)
forge conversation insights https://org.amigo.ai/admin/conversation/abc123

# Drill into a single interaction
forge conversation insights https://org.amigo.ai/admin/conversation/abc123 -i 6943165ad1441af6f6fd1f70

# Combine with JSON output
forge conversation insights https://org.amigo.ai/admin/conversation/abc123 -i 6943165ad1441af6f6fd1f70 --json

When --interaction is provided:

• Only messages from that interaction are displayed

• Insights are fetched for that single interaction only

• Summary reflects the filtered view

• JSON output includes an interaction_id field showing the active filter

Example: Quick Smoke Test

# Test agent greeting only (does the agent boot?)
forge conversation smoke-test -s "My Service" -e myorg

# Test with a specific message
forge conversation smoke-test -s "My Service" -e myorg -m "Hello, I need help"

# JSON output for scripting / CI
forge conversation smoke-test -s "My Service" -e myorg -m "Hello" --json

Smoke Test Command Options

Option	Required	Description
--service / -s	Yes	Service name or ID
--env / -e	Yes	Environment name
--message / -m	No	User message to send. If omitted, only the agent greeting is shown
--version-set / -v	No	Version set to use (default: release)
--json	No	Output as JSON for programmatic use

Key Behaviors

• Smoke test always finishes (cleans up) the conversation after the test

• Without --message: creates conversation, shows agent greeting, finishes

• With --message: creates conversation with initial message, shows agent response, finishes

• Conversation URL is displayed for follow-up investigation with forge conversation insights

Related Pull Request

• agent-forge#249 - Add --interaction flag to insights and conversation smoke-test command

How to Get It

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

2. Run poetry install to refresh dependencies.

v0.3.13 - Dynamic Behavior Invocation History (February 9, 2026)

Agent Forge v0.3.13 adds a new forge asset behavior invocations command that retrieves the invocation history of a dynamic behavior set, showing when, where, and how many times a behavior was triggered via the GET /dynamic_behavior_set/{id}/invocation/ backend endpoint.

Why This Matters: When debugging dynamic behaviors, developers need to verify that triggers are firing correctly and understand activation frequency across conversations. Previously, this required querying Databricks tables directly or navigating the web UI. This command provides quick CLI access to invocation records for rapid iteration and troubleshooting.

New Command

Command	Description
forge asset behavior invocations	List invocation history for a dynamic behavior set

Example: Check Behavior Invocation History

# List recent invocations by behavior name
forge asset behavior invocations "Dosing Schedule - Mounjaro" -e myorg

# Limit results
forge asset behavior invocations "Dosing Schedule - Mounjaro" -e myorg -n 10

# JSON output for scripting
forge asset behavior invocations "Dosing Schedule - Mounjaro" -e myorg --json

# Using behavior ID instead of name
forge asset behavior invocations 689f93f87ef28baa00461eee -e myorg

Command Options

Option	Required	Description
BEHAVIOR	Yes	Behavior name or ID (positional)
--env / -e	Yes	Environment name
--limit / -n	No	Maximum invocations to show (default: 30)
--json	No	Output as JSON (includes conversation_id, service_id, user_id, version info)

Key Behaviors

• Shows invoked_at timestamp, conversation ID, service ID, user ID, and behavior version for each trigger

• Accepts behavior name (resolved via API) or direct 24-char hex ID

• Results sorted by most recent first (-invoked_at)

• JSON output enables cross-referencing with Databricks dynamic_behavior_invocations table

Related Pull Request

• agent-forge#248 - Add behavior invocations command

How to Get It

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

2. Run poetry install to refresh dependencies.

v0.3.12 - Message Source Retrieval (February 9, 2026)

Agent Forge v0.3.12 adds a new forge conversation message-source command that retrieves the raw source of non-text messages (e.g., audio recordings from voice channels) via the GET /conversation/{id}/messages/{msg_id}/source backend endpoint.

Why This Matters: When debugging voice conversations, developers previously had no CLI way to access the original audio recordings -- they had to navigate the web UI or call the API directly. This command returns a signed URL to the source data, enabling quick access for quality review, debugging, and archival.

New Command

Command	Description
forge conversation message-source	Retrieve raw source of a non-text message (audio URL)

Example: Retrieve Audio Source

# Get message source (short-lived signed URL)
forge conversation message-source CONV_ID MSG_ID -e myorg

# Using conversation URL (env inferred)
forge conversation message-source https://myorg.amigo.ai/admin/conversation/abc123 MSG_ID

# Long-lived URL (12 hours) for sharing
forge conversation message-source CONV_ID MSG_ID -e myorg --long-lived

# JSON output for scripting
forge conversation message-source CONV_ID MSG_ID -e myorg --json

Command Options

Option	Required	Description
CONVERSATION	Yes	Conversation ID or full Amigo URL (positional)
MESSAGE_ID	Yes	Message ID -- 24 hex characters (positional)
--env / -e	Conditional	Environment name (required when using ID, inferred from URL)
--long-lived	No	Generate a 12-hour URL instead of short-lived (default: false)
--json	No	Output as JSON

Key Behaviors

• Returns a signed URL to the original message source (audio file, etc.)

• Only works for non-text messages; text messages return an informative error

• Short-lived URLs by default for security; use --long-lived for 12-hour URLs

• Accepts conversation as URL (env inferred) or ID (requires --env)

Also in this release: Replaced customer-specific org names in documentation with generic placeholders.

Related Pull Request

• agent-forge#247 - Add message-source command

How to Get It

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

2. Run poetry install to refresh dependencies.

v0.3.11 - Conversation Starter Generation (February 9, 2026)

Agent Forge v0.3.11 adds a new forge conversation starter command that generates contextually appropriate conversation starters for a service using its agent configuration and the POST /conversation/conversation_starter backend endpoint.

Why This Matters: Building effective conversation starters previously required manual authoring or starting throwaway conversations to see what the agent would say. This command generates facet-targeted starters in seconds, useful for populating UI widgets, seeding test scenarios, and exploring how an agent introduces itself across different topics.

New Command

Command	Description
forge conversation starter	Generate conversation starters for a service based on facets and instructions

Example: Generate Starters

# Single facet
forge conversation starter -s "My Service" -e dogfood \
  --instructions "Generate friendly greeting prompts" \
  --facet "scheduling"

# Multiple facets
forge conversation starter -s "My Service" -e dogfood \
  --instructions "Generate prompts about common issues" \
  --facet "billing" --facet "technical support"

# Control count and get JSON output
forge conversation starter -s "My Service" -e dogfood \
  --instructions "Generate onboarding prompts" \
  --facet "onboarding" --min-count 5 --max-count 10 --json

Command Options

Option	Required	Description
--service / -s	Yes	Service name or ID
--env / -e	Yes	Environment name
--instructions	Yes	Instructions for starter generation
--facet	Yes (1+)	Facet to focus starters on (repeatable)
--min-count	No	Minimum starters to generate, 1-10 (default: 3)
--max-count	No	Maximum starters to generate, 1-10 (default: 5)
--version-set / -v	No	Version set to use (default: release)
--json	No	Output as JSON

Key Features

• Facet-based generation: each starter is tagged with which facets it relates to

• Rich terminal output with numbered panels, or JSON for scripting

• Client-side validation of count ranges (1-10) before API call

• Service name resolution (accepts name or ID)

Related Pull Request

• agent-forge#245 - Add conversation starter command

How to Get It

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

2. Run poetry install to refresh dependencies.

v0.3.10 - Section-Aware Prompt Diff and Mutation Chain (February 9, 2026)

Agent Forge v0.3.10 adds two commands for understanding how system prompts evolve during conversations: forge prompt-log diff for comparing two interactions, and forge prompt-log chain for viewing prompt evolution across an entire conversation.

Why This Matters: System prompts for engage_user interactions are 80-100K characters and change between interactions as context updates, state transitions occur, and dynamic behaviors trigger. Previously, comparing prompts required downloading full text files and manually diffing. These commands parse the 13 XML sections defined by the backend Jinja2 template, classify each section by its change behavior, and surface only meaningful differences.

New Commands

Command	Description
forge prompt-log diff	Section-aware diff between two interactions' system prompts
forge prompt-log chain	Show prompt mutation chain across an entire conversation

Section Classification

Each section is classified by how it changes, derived from the chat_agent_engage_user.jinja2 template variables:

Classification	Sections	Changes When
static	PERSONA, SERVICE_DESCRIPTION, INTERACTION_LOG_FORMAT, BEHAVIORAL_GUIDELINES, COMMUNICATION_GUIDELINES	Never (within a conversation)
tool-dependent	CORE_AGENT_INSTRUCTIONS, CAPABILITIES_AND_CONSTRAINTS, TASK	has_tools flips between states
per-interaction	CONTEXT, DYNAMIC_BEHAVIORS, ACTION_GUIDELINES	Every interaction
state-transition	OBJECTIVE, CURRENT_ACTION	Context graph state changes

Example: Diff Two Interactions

# Section-aware diff (downloads both prompts, compares by section)
forge prompt-log diff -e dogfood -c CONV_ID \
  --int1 INT_ID_1 --int2 INT_ID_2

# Diff local files (previously saved with 'show --system-only > file')
forge prompt-log diff --file1 /tmp/prompt1.txt --file2 /tmp/prompt2.txt

# Include unchanged static sections in output
forge prompt-log diff --file1 /tmp/p1.txt --file2 /tmp/p2.txt --all

Output shows a summary of which sections changed (with classification) followed by unified diffs for each changed section. Unchanged static and tool-dependent sections are hidden by default.

Example: Mutation Chain

# Summary table -- which sections changed at each step
forge prompt-log chain -e dogfood -c CONV_ID

# Full diffs for each step
forge prompt-log chain -e dogfood -c CONV_ID --verbose

# JSON output for programmatic analysis
forge prompt-log chain -e dogfood -c CONV_ID --json

Example Output (Summary)

=== Prompt Mutation Chain (6 interactions) ===

    #  Interaction     Type           State                         Changed Sections
  ---  --------------  -------------  ----------------------------  ------------------------------
    1  698a8f465fbc..  (baseline)     call_intake_triage            --
    2  698a8f4e5fbc..  (dynamic)      call_intake_triage            CONTEXT
    3  698a8f565fbc..  (state+tools)  retrieve_existing_visit       CORE_AGENT_INSTRUCTIONS, ...
    4  698a8f655fbc..  (dynamic)      retrieve_existing_visit       CONTEXT
    5  698a8f6e5fbc..  (dynamic)      retrieve_existing_visit       CONTEXT
    6  698a8f775fbc..  (dynamic)      retrieve_existing_visit       CONTEXT

Transition Type Annotations

Type	Meaning
(baseline)	First interaction (no comparison)
(state)	Context graph state changed (OBJECTIVE/CURRENT_ACTION)
(tools)	has_tools flipped (CORE_AGENT_INSTRUCTIONS/CAPABILITIES_AND_CONSTRAINTS/TASK)
(state+tools)	Both state and tools changed simultaneously
(dynamic)	Only per-interaction sections changed (typical noise)

Command Options

Command	Option	Description
diff	-c / --conversation-id	Conversation ID
diff	--int1, --int2	First and second interaction IDs
diff	--file1, --file2	Diff local prompt files instead of downloading
diff	--all	Include unchanged static sections
diff	-t / --type	Prompt log type (default: engage_user)
chain	-c / --conversation-id	Conversation ID
chain	--verbose / -v	Show full unified diffs for each step
chain	--all	Include unchanged static sections in verbose output
chain	--json	JSON output for programmatic use

Rate Limiting: The prompt log download endpoint is limited to 5 requests/minute. The chain command handles this automatically with 12-second delays between requests and a progress bar showing elapsed time. A 10-interaction conversation takes ~2 minutes.

New Skill Documentation: Added Workflow 6 ("What Changed Between Interactions?") to prompt-log-analyst skill with four approaches: section-aware diff (A), manual full-text diff (B), Databricks SQL discovery (C), and full conversation mutation chain (D).

Related Pull Request

• agent-forge#243 - Add section-aware prompt log diff and mutation chain 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.

v0.3.9 - On-Demand Metric Evaluation (February 9, 2026)

Agent Forge v0.3.9 adds forge conversation evaluate -- a new composable command that calls POST /metric/evaluate synchronously against any conversation, at any interaction point. Previously, metric results were only available via the post-session async pipeline (--analyze-wait). Now you can evaluate specific metrics on-demand.

Why This Matters: The existing --analyze-wait flow requires the conversation to finish, evaluates all service-configured metrics, and waits for async processing. The new evaluate command is synchronous, lets you choose which metrics (1-10 per call), and works mid-conversation -- enabling quality gates during step-by-step simulations, targeted debugging of reported issues, and A/B comparison at different interaction points.

New Command

Command	Description
forge conversation evaluate	Evaluate specific metrics against a conversation on-demand

Command Options

Option	Description
--metric / -m	Metric name to evaluate (repeatable). Resolved from local files, then API search.
--metric-id	Metric ID to evaluate directly (repeatable). Skips name resolution.
--interaction / -i	Evaluate up to this interaction ID (mid-conversation scoping).
--env / -e	Environment name (inferred from URL if using conversation URL).
--json	Output as JSON for programmatic use.

Example: Evaluate by Metric Name

# Evaluate a single metric
forge conversation evaluate \
  https://org.amigo.ai/admin/conversation/abc123 \
  --metric "Safety Compliance"

# Evaluate multiple metrics
forge conversation evaluate abc123 -e dogfood \
  --metric "Tone of Voice" \
  --metric "Conversation Structure"

Example: Mid-Conversation Evaluation

# During a step-by-step simulation, evaluate at a specific interaction
forge conversation evaluate abc123 -e dogfood \
  --metric "Safety Compliance" \
  --interaction 68daffb7650ee7f69bb01d5e \
  --json

Example: JSON Output

{
  "conversation_id": "abc123",
  "evaluate_to_interaction_id": null,
  "metrics": [
    {
      "metric_id": "689f92caa97815bce9f39899",
      "name": "Tone of Voice",
      "value": 5.5,
      "references": ["6867eec192db41d81013a364"],
      "justification": "Warm and approachable but overuses slang..."
    }
  ]
}

Post-Session vs On-Demand Evaluation

	Post-Session	On-Demand
Command	simulate --analyze-wait 30	conversation evaluate
When	After conversation finishes	Any time, including mid-conversation
Which metrics	All configured on service	You choose (1-10 per call)
Scope	Entire conversation	Any interaction via --interaction
Use case	Automated test suites	Debugging, quality gates, comparison

Metric Name Resolution: --metric resolves names by scanning local entity files (local/{env}/entity_data/metric/*.json) first, falling back to API search. Use --metric-id for scripts or when you already have the ID.

Rate Limit: 20 requests/minute, max 10 metrics per call.

New Skill Documentation: Added conversation-analyst skill for quality diagnosis workflows using evaluate alongside insights, transcript, and simulate-step.

Related Pull Request

• agent-forge#233 - Add forge conversation evaluate for on-demand metric evaluation

How to Get It

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

2. Run poetry install to refresh dependencies.

v0.3.8 - Ephemeral Test User Lifecycle (February 3, 2026)

Agent Forge v0.3.8 introduces ephemeral test user support for running parallel conversation simulations without conflicts. This enables isolated testing with automatic cleanup and post-processing analysis.

Why This Matters: Running multiple simulations in parallel previously caused "unfinished conversation" conflicts when using the same user. Now you can create ephemeral test users that are automatically cleaned up after simulation, with support for analyzing post-processing results (memory extraction, metrics computation).

New Commands

Command	Description
forge test-user create	Create a persistent test user for manual testing
forge test-user cleanup	Clean up orphaned test users matching a pattern

New Simulate Options

Option	Description
--test-user	Create an ephemeral test user for isolated simulation
--keep-test-user	Don't delete test user after simulation (for debugging)
--analyze-wait <seconds>	Wait for post-processing completion (memories, metrics)

Example: Parallel Simulations with Test Users

# Run simulation with ephemeral test user (auto-created, auto-deleted)
forge conversation simulate --service "My Service" --env dogfood \
  --test-user \
  --max-turns 10

# With post-processing analysis (waits for memories/metrics extraction)
forge conversation simulate --service "My Service" --env dogfood \
  --test-user \
  --analyze-wait 30 \
  --max-turns 10 \
  --json

# Keep test user for debugging after simulation
forge conversation simulate --service "My Service" --env dogfood \
  --test-user \
  --keep-test-user \
  --max-turns 10

Example: Manual Test User Management

# Create a test user for manual testing
forge test-user create -e dogfood

# Clean up orphaned test users (from failed simulations)
forge test-user cleanup -e dogfood

# Clean up with custom email pattern
forge test-user cleanup -e dogfood -p "mytest_"

JSON Output with Test User

When using --test-user --json, the output includes test user and analysis information:

{
  "conversation_id": "...",
  "conversation_url": "...",
  "test_user": {
    "id": "user_id_here",
    "email": "[email protected]",
    "kept": false
  },
  "analysis": {
    "memories": [...],
    "memory_count": 3,
    "metrics": [...],
    "metric_count": 2,
    "completed_post_processings": ["extract-memories", "compute-metrics"]
  }
}

Key Features

• Parallel execution: No more "unfinished conversation" conflicts

• Isolated testing: Each test user has their own conversation history and memory

• Post-processing analysis: Test memory extraction and metrics computation

• Clean teardown: Automatic cleanup when simulation completes

• Debugging support: --keep-test-user preserves user for investigation

Related Pull Request

• agent-forge#227 - Add ephemeral test user lifecycle for parallel simulations

How to Get It

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

2. Run poetry install to refresh dependencies.

v0.3.7 - Simulation Loop CLI Commands (January 26, 2026)

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

• Automated Simulation Guide - Claude orchestration patterns

v0.3.6 - Tool Version Schema Cleanup (January 25, 2026)

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

• agent-forge#205 - Remove tool_repo field from tool version schemas

How to Get It

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

2. Run poetry install to refresh dependencies.

v0.3.5 - Databricks MCP Integration (January 23, 2026)

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.

v0.3.4 - Prompt Template Linting (January 22, 2026)

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.

v0.3.3 - Recommended Responses for Conversation Testing (January 21, 2026)

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.

v0.3.2 - Conversation Commands (January 20, 2026)

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:

# Standard admin URL
forge conversation get https://dogfood.amigo.ai/admin/conversation/6943164fd1441af6f6fd1f64

# Sessions URL format (also supported)
forge conversation get https://dogfood.amigo.ai/admin/sessions/6943164fd1441af6f6fd1f64

Example: View Conversation

# Fetch and display a conversation
forge conversation get https://dogfood.amigo.ai/admin/conversation/6943164fd1441af6f6fd1f64

# Include agent inner thoughts
forge conversation get https://dogfood.amigo.ai/admin/conversation/6943164fd1441af6f6fd1f64 --include-thoughts

# Limit messages returned
forge conversation get https://dogfood.amigo.ai/admin/conversation/6943164fd1441af6f6fd1f64 --limit 50

# Output as JSON for programmatic use
forge conversation get https://dogfood.amigo.ai/admin/conversation/6943164fd1441af6f6fd1f64 --json

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

forge conversation insights https://dogfood.amigo.ai/admin/conversation/6943164fd1441af6f6fd1f64

# Drill into a single interaction (added in v0.3.14)
forge conversation insights https://dogfood.amigo.ai/admin/conversation/6943164fd1441af6f6fd1f64 -i INTERACTION_ID

# Output:
# ━━━ Interaction 6943165c... ━━━
#   State: handle_pricing_inquiry
#   Action: Provide pricing information...
#   ⚡ Dynamic Behavior Triggered: 68f123abc... (v3)
#   🔧 Tool: get_pricing_data (0.45s)

Example: Batch Processing

Process multiple conversations from a file containing URLs:

# Create a file with conversation URLs (one per line)
echo "https://dogfood.amigo.ai/admin/conversation/abc123" > urls.txt
echo "https://dogfood.amigo.ai/admin/conversation/def456" >> urls.txt

# Process all conversations with progress bar
forge conversation batch urls.txt --env dogfood --output-dir ./conversations --limit 100

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.

v0.3.1 - Prompt Log Retrieval (January 20, 2026)

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.

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

# List available prompt types
forge prompt-log types

# View engage_user prompt for an interaction
forge prompt-log show -e dogfood \
  -c 696ff9b33ef6a7824dbb3e7f \
  -i 0195e64c-b058-7945-93cb-6d8be26f3b66 \
  -t engage_user

# View only the system prompt
forge prompt-log show -e dogfood \
  -c 696ff9b33ef6a7824dbb3e7f \
  -i 0195e64c-b058-7945-93cb-6d8be26f3b66 \
  -t engage_user \
  --system-only

Example: Download Prompts for Analysis

# Download to ZIP file
forge prompt-log download -e dogfood \
  -c 696ff9b33ef6a7824dbb3e7f \
  -i 0195e64c-b058-7945-93cb-6d8be26f3b66 \
  -t engage_user \
  -o ./prompt_logs.zip

# Download and extract to directory
forge prompt-log download -e dogfood \
  -c 696ff9b33ef6a7824dbb3e7f \
  -i 0195e64c-b058-7945-93cb-6d8be26f3b66 \
  -t engage_user \
  -o ./prompt_logs/ \
  --extract

Advanced: Raw Prefix

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

forge prompt-log show -e dogfood \
  --prefix "backend.chat_agent_engage_user/myorg/conv123/int456"

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.

v0.3.0 - Schema Migration System (January 16, 2026)

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.

v0.2.25 - Dynamic Behaviors as First-Class Assets (January 11, 2026)

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

• Dynamic Behaviors - Service integration with behaviors

• Dynamic Behavior Tables - CLI management and data access

v0.2.24 - Service Status Command (January 11, 2026)

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

• Version Sets & Promotion - Updated with service status monitoring

v0.2.23 - JSON Output Consistency (January 11, 2026)

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

• Version Sets & Promotion - Updated with JSON output examples

v0.2.22 - Asset List Commands (January 11, 2026)

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

• Asset Discovery - Full asset discovery documentation

v0.2.21 - Quick Rollback Command (January 11, 2026)

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

# Preview what would be rolled back
$ forge version-set rollback -s "Customer Support" -e production

Rollback 'release' to 'release-previous'
  Service: Customer Support (686d598b1234567890abcdef)
                         Configuration Comparison
┏━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┓
┃ Field                 ┃ Previous (release-previous) ┃ Current (release) ┃
┡━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━┩
│ agent_version         │ 27                          │ 28                │
│ context_graph_version │ 3                           │ 4                 │
│ llm_preferences       │ 2 configured                │ 2 configured      │
└───────────────────────┴─────────────────────────────┴───────────────────┘

Dry-run mode. Use --apply to execute.

# Execute the rollback
$ forge version-set rollback -s "Customer Support" -e production --apply

Successfully rolled back 'release' to 'release-previous'

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

• Version Sets & Promotion - Full CLI documentation including rollback

v0.2.20 - Service Discovery CLI (January 11, 2026)

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

# 1. Discover services
$ forge service list -e production --tag phone

Services in production
Filtered by tag: phone

┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┓
┃ Name                ┃ ID          ┃ Tags            ┃ Version Sets ┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━┩
│ Customer Support    │ 686d598b... │ phone, voice    │            3 │
│ Sales Assistant     │ 68bb4c7f... │ phone, prod     │            2 │
└─────────────────────┴─────────────┴─────────────────┴──────────────┘

# 2. Inspect a service (resolves agent/CG names from IDs)
$ forge service show "Customer Support" -e production

Service: Customer Support
  ID: 686d598b1234567890abcdef
  Active: Yes

Tags:
  - phone
  - voice

Linked Assets:
  Agent: support_agent (66e0d996f5a09fb3cf18ea73)
  Context Graph: support_hsm (66e0d575f5a09fb3cf18ea5e)

Version Sets:
  Name       Agent Ver    CG Ver    LLM Config
  edge          latest    latest    defaults
  preview           28         4    2 set
  release           28         4    2 set

Related commands:
  forge version-set list Customer Support -e production
  forge asset agent version-list support_agent -e production

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

• Version Sets & Promotion - Full CLI documentation including service discovery

v0.2.19 - Version Existence Validation (January 11, 2026)

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

$ forge version-set upsert preview -s MyService -e production -a 999 -g 888 --apply

Error: Agent version 999 does not exist. Use 'forge asset agent version-list' to see available versions.
Error: Context graph version 888 does not exist. Use 'forge asset context-graph version-list' to see available versions.

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:

forge version-set upsert preview -s MyService -e production -a 5 -g 3 --skip-version-check --apply

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

• Version Sets & Promotion - Full CLI documentation including validation rules

v0.2.18 - Asset Version Discovery CLI (January 11, 2026)

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

# List agent versions
$ forge asset agent version-list MyAgent -e production

Versions for Agent: MyAgent (507f1f77bcf86cd799439011)

┏━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┓
┃ Version ┃ Created          ┃ Description ┃
┡━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━┩
│       1 │ 2024-04-11 23:52 │ —           │
│       2 │ 2025-01-30 19:38 │ —           │
│       3 │ 2025-01-30 19:51 │ —           │
└─────────┴──────────────────┴─────────────┘

# List context graph versions (includes state count)
$ forge asset context-graph version-list MyGraph -e production

Versions for Context Graph: MyGraph (66997b4d40fe08f84ba0d1d1)

┏━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━┓
┃ Version ┃ Created          ┃ States ┃ Description      ┃
┡━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━┩
│       1 │ 2024-07-18 20:45 │     21 │ Initial version  │
│       2 │ 2024-08-07 17:06 │     22 │ Added new state  │
└─────────┴──────────────────┴────────┴──────────────────┘

# Now pin specific versions in a version set
$ forge version-set upsert preview -s MyService -e production -a 3 -g 2 --apply

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

• Version Sets & Promotion - Full CLI documentation including asset discovery

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

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

$ forge version-set upsert preview -s "Voice Service" -e production --apply

Error: Version set 'preview' uses non-voice-optimized LLM 'azure_gpt-5-2025-08-07'.
Voice preset 'voice' requires voice-optimized LLMs. Valid: ['azure_gpt-4.1-2025-04-14',
'azure_gpt-4.1-mini-2025-04-14']

Validation failed. Fix errors before proceeding.

Example: Warning (Non-blocking)

$ forge version-set upsert test -s "Voice Service" -e dogfood --apply

Warning: Version set 'test' has empty llm_model_preferences. System defaults may
include non-voice-optimized LLMs.

Create version set 'test'
  ...

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

• Version Sets & Promotion - CLI validation documentation

• Channel Tagging - Channel and preset constraints

v0.2.16 - Auto-Backup for Release Promotions (January 10, 2026)

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:

# Auto-backup enabled (no flag needed)
forge version-set promote preview release -s MyService -e production --apply
# Output: Created backup 'release-previous'
#         Successfully promoted 'preview' to 'release'

Skip Auto-Backup

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

forge version-set promote preview release -s MyService -e production --no-backup --apply

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

• Version Sets & Promotion - Updated CLI documentation

v0.2.15 - Audio Filler Delay Validation (January 10, 2026)

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

~~ CHANNEL VALIDATION WARNINGS ~~

  Entity: My Context Graph (68bb4c46ec4b2186ff4d2042)
    ⚠ WARNING: Audio filler delay of 5.0s configured for tool 'calendar_tool'
      in state 'booking'. This delay adds directly to perceived latency.
      Audio filler delays should generally be as close to zero as possible
      (e.g., 0.0001s). Only use larger delays if you have specific evidence
      that immediate fillers cause issues for very fast operations.

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.

{
  "audio_fillers": ["Let me check that...", "One moment..."],
  "audio_filler_triggered_after": 0.0001
}

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.

v0.2.14 - LLM Preferences Validation (January 10, 2026)

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

!! CHANNEL VALIDATION ERRORS !!

  Entity: Cardi (68bb4c7fb3c5a689980b217f)
    ✗ ERROR: Version set 'release' uses non-voice-optimized LLM
      'azure_gpt-5.1-2025-11-13' for 'backend.chat_agent_engage_user'.
      Voice preset 'voice' requires voice-optimized LLMs for low latency.
      Valid LLMs: ['azure_gpt-4.1-2025-04-14', 'azure_gpt-4.1-mini-2025-04-14']

~~ CHANNEL VALIDATION WARNINGS ~~

  Entity: SDK Test Service (689b81e7afdaf934f4b48f81)
    ⚠ WARNING: Version sets ['edge', 'preview'] have llm_model_preferences
      but service has no channel or preset tag.

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

• Channel Tagging System - Updated with LLM validation section

v0.2.13 - Version Set CLI & Environment Tags (January 10, 2026)

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

# Create personal version set pinned to latest versions
forge version-set upsert personal-alex -s MyService -e dogfood --latest --apply

# Compare before promoting
forge version-set diff personal-alex test -s MyService -e dogfood

# Promote through stages
forge version-set promote personal-alex test -s MyService -e dogfood --apply
forge version-set promote test preview -s MyService -e dogfood --apply

# Promote to release (auto-backup creates release-previous)
forge version-set promote preview release -s MyService -e dogfood --apply

Example Output

Comparing version sets for MyService (689b81e7afdaf934f4b48f81)

┏━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━┳━━━━━━━┓
┃ Field                 ┃ preview ┃ release ┃ Match ┃
┡━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━╇━━━━━━━┩
│ agent_version         │ 5       │ 4       │ ✗     │
│ context_graph_version │ 3       │ 3       │ ✓     │
│ llm_preferences       │ default │ default │ ✓     │
└───────────────────────┴─────────┴─────────┴───────┘

Version sets differ.

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:

tags:
  - phone
  - voice_premium
  - production  # or 'dev'

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

Service: Production Voice Service
  ! Production service missing required 'preview' version set.
  ! Release version set does not match preview configuration.
  ! Version set 'release' must have pinned agent version for production services.

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

• Version Sets & Promotion - CLI commands and workflow guide

• Channel Tagging System - Environment tag configuration

v0.2.12 - Validate Command & Dependency Checking (January 10, 2026)

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

# Validate a specific entity type
forge validate --entity-type service --env production

# Validate all entity types
forge validate --all --env production

# Also validate references against remote entities
forge validate --entity-type service --env production --check-references

# Validate service dependencies against channel constraints
forge validate --entity-type service --env production --check-dependencies

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

── Validating service ──
  Found 62 local entities

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~ CHANNEL VALIDATION WARNINGS ~
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  Entity: My Voice Service (abc123)
    ⚠ WARNING: Voice service missing 'keyterms'. Configure keyterms for better transcription accuracy.

============================================================
Validation complete: 1 warning(s), no errors

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

forge validate --entity-type service --env production --check-dependencies

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

── Validating service dependencies ──
  Loaded 12 context graphs
  Loaded 148 dynamic behaviors

  Service: Cardi
    Context graph: Cardi POC Check In
    ! Context graph 'Cardi POC Check In' contains state types not allowed
      for phone channel: decision (1), reflection (1).
      Allowed types: action, annotation, tool-call
    ~ Context graph 'Cardi POC Check In' has 10 states, exceeds recommended
      max of 5 for phone channel.

  Service: Reactive Support
    Dynamic behaviors applied: 145
    ! Voice channel 'phone' does not support dynamic behaviors,
      but 145 behavior(s) are applied.

============================================================
Validation complete: 3 error(s), 28 warning(s)

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

• Channel Tagging System - Updated with standalone validation section

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

============================================================
Sync complete: local → remote
============================================================
  Entity type: service
  Created: 5
  Updated: 10
  Deleted: 0
============================================================

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

v0.2.11 - Flexible Service Tag Format (January 10, 2026)

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):

{
  "tags": [
    {"key": "phone", "value": null},
    {"key": "voice_premium", "value": null}
  ]
}

After (recommended):

{
  "tags": ["phone", "voice_premium"]
}

Or in YAML:

tags:
  - phone
  - voice_premium

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

• Channel Tagging System - Updated tag format documentation

v0.2.10 - Regional LLM Availability (January 10, 2026)

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:

# Validate a preset for a specific region
forge channel validate-preset text_premium phone --region ca

# Example output for incompatible region:
# Error: Preset 'text_premium' uses LLMs not available in ca-central-1: azure_gpt-5.1-2025-11-13

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

• Regions & Endpoints - Regional LLM availability details

• Channel Tagging System - Preset validation for regions

v0.2.9 - Channel-Based Tagging System (January 10, 2026)

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:

{
  "tags": [
    {"key": "phone", "value": null},
    {"key": "voice_premium", "value": null}
  ]
}

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

# List available channels
forge channel list-channels

# Show preset details
forge channel list-presets --type voice --verbose

# Validate a context graph for ultra-low latency
forge channel validate-context-graph phone \
  --state-type action \
  --state-count 1 \
  --single-state-eligible \
  --preset voice_ultra_low

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

• Channel Tagging System - Configuration guide and best practices

v0.2.8 - Role Provisioning CLI (January 9, 2026)

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

# List available predefined roles
poetry run forge role list

# Show role details with all permissions
poetry run forge role show --role AgentEngineerRole

# Provision a role to an organization
poetry run forge role provision --role AgentEngineerRole --env [ORG_ID]

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:

   poetry run forge role provision --role AgentEngineerRole --env [ORG_ID]

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.

v0.2.7 - Dynamic Behavior Actions Array (January 7, 2026)

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:

{
  "actions": [
    {
      "type": "inject-instruction",
      "instruction": "Your instruction text here",
      "overrides_instructions": false
    }
  ]
}

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

{
  "actions": [
    {
      "type": "change-tool-candidates",
      "tool_call_specs": [
        {
          "tool_id": "my-tool-id",
          "tool_name": "My Tool",
          "version_constraint": ">=1.0.0",
          "additional_instruction": "Tool-specific guidance",
          "audio_fillers": ["Processing..."],
          "audio_filler_triggered_after": 2.0,
          "result_persistence": "persisted-preferred"
        }
      ],
      "overrides_existing_tool_call_specs": false
    }
  ]
}

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:

rm -rf local/*/entity_data/dynamic_behavior_set/
poetry run forge sync-to-local --entity-type dynamic_behavior_set --env staging
poetry run forge sync-to-local --entity-type dynamic_behavior_set --env production

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.

v0.2.6 - Continuation Token Fix (December 3, 2025)

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.

v0.2.5 - Improved Logline Formatting (December 2, 2025)

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

[2025-12-02T19:47:10.092-05:00] INFO sync_module.sync: Syncing remote to local

How to Get It

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

v0.2.4 - Null Field Update Fix (November 28, 2025)

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.

v0.2.3 - Versioned Entity Rollbacks (November 24, 2025)

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

forge version rollback --entity-type <entity-type> --id <entity-id> --env <env>

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

forge version rollback --entity-type context_graph --id 6888ff11f1ce1f648bb293b8 --env dogfood
INFO ... ContextGraphEntityService – Found 79 context graphs, 15 active (non-deprecated)
Available versions (newest first):
│ 9 ✅ │ 28 days ago — 2025-10-26 13:55:36 │
│ 8     │ a month ago — 2025-10-13 17:17:21 │
...
Version number: 8
INFO sync_module.diff – States differ ... {"audio_filler_triggered_after": {"new_value": 0.1, "old_value": 5.0}}
Preview of changes between the current remote version and the selected version:
... (table of fields slated for rollback) ...
Continue with rollback and local sync? [y/N]: y
Creating rollback version on remote...
INFO sync_module.sync – Remote → local sync complete
Rollback complete and local files updated.

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.

v0.2.2 - Automatic Tool Version Deprecation (November 22, 2025)

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:

forge action publish --id 690e6188fc31264e555ff5ff --env production
Enter repo (main, team) [team]:
Enter project path (directory containing pyproject.toml) [tool_path]:
Enter version bump type (major, minor, patch) [patch]:

Action Publish Data
===================
repo: 'team'
project_path: 'tool_path'
bump_type: 'patch'
Do you want to publish this action version? [Y/n]:

Checking tool versions before publishing...
Tool currently has 3 active version(s). Preparing to deprecate 1 version(s) to keep the latest 2 before publishing a new version (limit 3 after publishing).

Proposed versions to deprecate (oldest ➜ newest):
  - 1.0.5 – created 2025-11-21T19:47:03.253000+00:00 (repo=team, lambda=6)
Deprecate the versions listed above to continue with publishing? [Y/n]:
Deprecating version ==1.0.5...
Deprecated tool version ==1.0.5.
Successfully deprecated 1 old version(s). Tool now has capacity for the new version.
Publishing action version... This may take up to 10 minutes.

Action version published successfully!
New version: 1.0.9

Skipping Auto-Deprecation:

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

forge action publish --id <tool-id> --env production --skip-auto-deprecate

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:

# Before (v0.2.1)
forge action publish --env production
# ... prompted for ID ...

# After (v0.2.2)
forge action publish --id <your-tool-id> --env production

Related Commands:

• forge action version delete - Manually deprecate specific tool versions

v0.2.1 - ToolCallState Schema Support (November 20, 2025)

Agent Forge v0.2.1 (PR #133) 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.

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

v0.2.0 - Tool Call Result Persistence (November 13, 2025)

Agent Forge v0.2.0 (PR #132) 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.

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":

{
  "action_tool_call_specs": [
    {
      "tool_id": "search_knowledge_base",
      "version_constraint": ">=1.0.0",
      "additional_instruction": "Search for relevant articles",
      "audio_fillers": ["Let me check that..."],
      "audio_filler_triggered_after": 2.0
    }
  ]
}

After (v0.2.0) - Field required:

{
  "action_tool_call_specs": [
    {
      "tool_id": "search_knowledge_base",
      "version_constraint": ">=1.0.0",
      "additional_instruction": "Search for relevant articles",
      "audio_fillers": ["Let me check that..."],
      "audio_filler_triggered_after": 2.0,
      "result_persistence": "persisted-preferred"
    }
  ]
}

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.

# 1. Commit or stash any uncommitted local changes
git status
git stash  # If you have uncommitted changes

# 2. Remove local Context Graph files
rm -rf local/staging/entity_data/context_graph/
rm -rf local/production/entity_data/context_graph/

# 3. Re-sync from remote (gets backfilled values)
poetry run forge sync-to-local --entity-type context_graph --env staging
poetry run forge sync-to-local --entity-type context_graph --env production

# 4. Restore your stashed changes if needed
git stash pop

⚠️ 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:

# Dry-run to see what would change
poetry run forge sync-to-remote --entity-type context_graph --env staging

# If output looks correct, apply changes
poetry run forge sync-to-remote --entity-type context_graph --env staging --apply

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

• Context Graph Best Practices - Usage patterns, examples, and recommendations for result_persistence

• Agent Forge v0.2.0 Release - Full release notes and changes

• Agent Forge Repository - SDK documentation and setup instructions

---

Versioning

The Agent Forge SDK follows Semantic Versioning 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+