Agent Forge CLI

Release history for the Agent Forge CLI. Commands, authentication, entity sync, simulation, and tool development updates.

Release history for the Agent Forge CLI (configuration management and deployment tooling). Latest release: v0.1.74 (September 2026).

Installation

Install the latest macOS release from the public release channel:

curl -fsSL https://forge.platform.amigo.ai/install.sh | sh

The public installer and built-in forge update command currently support macOS on Intel and Apple Silicon. For an overview of the CLI and its command groups, see the Agent Forge CLI reference.

Releases

The current CLI uses the v0.1.x release line. The v0.2.x-v0.4.x entries below describe the previous CLI generation; their larger version numbers do not make them newer. Use the current CLI reference when writing commands.

Current CLI Generation

v0.1.71 - v0.1.74 - Simulation Authoring and Intake Source Operations (August-September 2026)

Simulation Authoring and Intake Source Operations

Forge can now create simulation cases and suites and inspect or safely remove dataset intake-source registrations. The obsolete workspace provisioning command has been removed.

What changed:

• forge platform simulation case create. Creates one case object or an API-native batch of up to 100 cases from --file or --body. --json returns the created case records.
• forge platform simulation suite create. Creates a suite selected by case IDs, required tags, or both. A suite must have a name and at least one selector.
• forge platform intake-source list. Lists all registered intake sources for the configured or explicitly selected workspace, following pagination and exposing safe source metadata only.
• forge platform intake-source delete. Removes one registration after a default-no confirmation. It requires explicit source and workspace UUIDs, supports --dry-run inspection and --yes, and does not automatically retry failures.
• Workspace provisioning command removed. forge platform workspace provision is no longer registered. Workspace provisioning is not part of the current Forge command surface.

What you need to do:

• Review before deleting an intake source. Deletion removes only the registration. Upstream files, imported tables or data, credentials, and history remain. Use --dry-run first and inspect source state before explicitly retrying an uncertain failure.
• Update scripts that invoke workspace provision. Remove that command from Forge-based workspace setup flows.

v0.1.68 - v0.1.70 - Workspace Contract Alignment and Release Distribution (August 2026)

Workspace Contract Alignment and Release Distribution

Workspace commands now match the current Platform API model, and Forge releases are distributed through the public GitHub Pages-backed release channel.

What changed:

• Workspace environment fields removed. Workspace list and get no longer display an environment property, and workspace create no longer accepts --env-type. Environment is a deployment concern rather than stored workspace data.
• Connector field corrected. Workspace responses and updates use connector_type; the obsolete ehr_type and default_fhir_store_url fields are no longer presented by Forge.
• Latest-only self-update. forge update installs the latest published macOS release. The former --version and --yes options and downgrade flow have been removed; --check and --force remain.
• Public release path updated. The installer and updater use the GitHub Pages-backed forge.platform.amigo.ai release channel and verify the checksum published alongside the latest archive.

What you need to do:

• Remove retired flags from automation. Stop passing --env-type, forge update --version, or forge update --yes.
• Use the current workspace schema. Read and write connector_type where applicable.

v0.1.66 - v0.1.67 - Binding Test Values and Targeted Realtime Voice Selection (July 2026)

Binding Test Values and Targeted Realtime Voice Selection

Forge adds safer test-time authoring for authorization-bound tool parameters and a targeted way to change an OpenAI Realtime voice.

What changed:

• function binding-test-value get|set|clear. Reads, writes, or clears the playground test value for an authorization_binding parameter on a platform function.
• data-query binding-test-value get|set|clear. Provides the same lifecycle for workspace data-query parameters. set and clear support --dry-run on both tool families.
• service voice-config --realtime-voice. Preserves the current service voice configuration while updating voice_config.realtime.voice. The service must already use session_provider: gpt_realtime.
• gpt_live preset removed. The current preset list is ultra_low_latency, balanced, quality, and gpt_realtime.

What you need to do:

• Keep live authorization authoritative. Binding test values are fallbacks for trusted function tests and developer-playground conversations, not general SQL defaults. Live authorization overrides them.
• Avoid concurrent service edits during a targeted voice update. Forge reads the current service and then writes the complete voice configuration.
• Replace --preset gpt_live. Use --preset gpt_realtime for the supported OpenAI Realtime configuration.

v0.1.55 - Conversation Replay (July 2026)

Conversation Replay

Forge can replay structured caller turns from an existing text conversation into a new conversation for controlled comparison.

What changed:

• forge platform conversation replay. Builds a replay plan from the source transcript and is dry-run by default. Pass --apply --yes to create the target conversation and execute its turns.
• Replay edits. Mode-specific flags can replace, insert, or truncate at a selected turn before continuing the replay.
• Safe transcript output. Results are redacted by default. Raw transcript text requires both --unredacted and --i-understand-pii.

What you need to do:

• Review the plan before applying it. Replayed messages can invoke side-effecting tools. Replay currently supports text conversations with structured transcripts.

v0.1.51 - v0.1.52 - Agent Definition Management and Framework Guidance (July 2026)

Agent Definition Management and Framework Guidance

Forge can now validate, register, inspect, and archive customer-authored framework agent definitions from the command line.

What changed:

• forge platform agent-definition validate. Checks a framework-native definition without storing it. Supply the definition name and exactly one JSON source through --file or --body.
• forge platform agent-definition register. Registers a definition for claude-agent-sdk or openai-agents. Re-registering an identical body reports it as unchanged; registering a changed body creates an immutable version.
• Definition discovery and lifecycle commands. list retrieves all active definitions across paginated results, get <definition-id> returns one definition and its version metadata, and archive <definition-id> soft-archives it after confirmation so the name can be reused.
• OpenAI Realtime voice preset. forge platform service voice-config <service-id> --preset gpt_realtime selects the OpenAI Realtime speech-to-speech provider. The existing gpt_live preset remains available.
• Clearer agent-run help. The CLI now names claude-agent-sdk and openai-agents explicitly and explains which SDK each framework identifier selects.

What you need to do:

• No action required. Upgrade to v0.1.52 to manage native agent definitions or use the gpt_realtime preset.

v0.1.43 - v0.1.50 - Unified Runs, Background Reply Polling, and Command Cleanup (July 2026)

Unified Runs, Background Reply Polling, and Command Cleanup

Forge now mirrors the platform's unified Runs surface and provides a protocol-safe way to claim completed background replies.

What changed:

• forge platform run list|summary|get. Lists conversation and framework runs together, summarizes them, and opens a single run by its channel-neutral run ID. List filters cover live status, run kind, and channel.
• Inline conversation evaluation. conversation send-message accepts repeatable --must-contain, --must-not-contain, and --judge-criteria checks. LLM-judge checks require the explicit PII acknowledgement flag.
• forge platform conversation poll. Claims completed background work for a conversation. Forge prints the idempotency key needed to replay an ambiguous claim and acknowledges the result only after successful output.
• Retired commands removed. The review-queue command group and service escalation-policy subcommand are no longer registered because their Platform API endpoints were retired.

What you need to do:

• Use platform run for cross-channel run listings. Conversation-specific commands remain available for opening transcripts and sending turns.
• Update scripts that call retired commands. Remove service escalation-policy invocations. For workspaces enrolled in the private preview, replace legacy review-queue workflows with the platform's external-write proposal review flow.

v0.1.39 - v0.1.40 - Full-Duplex Voice Preset and Per-Model Judge Pricing (July 2026)

Full-Duplex Voice Preset and Per-Model Judge Pricing

Voice configuration and regression evaluation now recognize the latest runtime options.

What changed:

• gpt_live voice preset. Forge accepts the full-duplex gpt_live session-provider family when pushing voice configuration.
• Per-model judge pricing. Regression evaluation selects pricing for the configured judge model rather than applying a single shared estimate.

What you need to do:

• No action required. Upgrade to use the gpt_live preset or the updated regression cost reporting.

v0.1.38 - Conversation Close Command (July 2026)

Conversation Close Command

Text conversations are durable and stay open until explicitly closed, which previously meant a contact on a text channel could never start a fresh conversation from the CLI. A new command closes a conversation directly.

What changed:

• forge platform conversation close <conversation-id> closes a text conversation. The command asks for confirmation before closing; pass --yes / -y to skip the prompt. --json emits a structured receipt with the conversation ID. If the conversation does not exist or is already closed, the command reports that clearly instead of a raw error.
• sms and imessage accepted as channel values. The --channel option on forge platform use-case commands now accepts sms and imessage alongside the existing voice and email values.

What you need to do:

• No action required. These are additive changes.

v0.1.37 - Voice Settings Field Removal (July 2026)

Voice Settings Field Removal

The correction_categories field has been removed from workspace voice settings.

What changed:

• correction_categories removed. forge platform voice-settings get no longer displays a Correction Categories row, and the field is no longer part of the voice-settings payload.

What you need to do:

• Update any scripts that read this field. JSON output from voice-settings get no longer includes correction_categories.

v0.1.35 - Integration Endpoint Commands (July 2026)

Integration Endpoint Commands

Integration endpoints can now be created and listed from the CLI, and endpoints defined inline in an integration file are created together with the integration.

What changed:

• forge platform integration endpoint-create <integration-id> adds one endpoint (or a JSON list of endpoints) to an existing integration via --file / --body. A leading / on an endpoint path is stripped automatically, and failures are reported per endpoint without aborting the batch.
• Inline endpoints on integration create. When an integration definition includes endpoints, forge platform integration create now creates those endpoints too, so one file can define the integration and its endpoints together. Previously the inline endpoints were silently dropped and the created integration had no callable endpoints.
• forge platform integration endpoint-list <integration-id> lists an integration's endpoints, with --json output for scripting.
• forge platform integration test now resolves endpoint names, so you can refer to an endpoint by name when testing an integration.

What you need to do:

• Re-check integrations created with inline endpoints on older versions. If you previously ran integration create with endpoints in the body, those endpoints were not created. Use endpoint-list to verify and endpoint-create to add any that are missing.

v0.1.34 - CLI Self-Update on macOS (July 2026)

CLI Self-Update on macOS

forge update now updates the CLI in place on macOS (Intel and Apple Silicon). It downloads the requested release, verifies its SHA256 checksum, sanity-checks the new binary, and atomically swaps the running install.

What changed:

• forge update installs the latest release. --check reports whether an update is available without installing anything.
• --version <ver> pins an exact release and installs it even if it is older than the current install. Downgrades prompt for confirmation; --yes / -y skips the prompt for scripted use.
• --force reinstalls the current version and is required to overwrite a development build.
• Clear permission errors. If the install location is not writable, the command fails with guidance to re-run with elevated permissions instead of escalating on its own.
• Release notes after updating. After a successful update, forge update prints the release notes for every version the update spans (newest first), so a multi-version jump shows everything you skipped. Fetching notes is best effort and never fails the update.

What you need to do:

• No action required. Once on a version with this command, you can update with forge update instead of downloading a new build manually.

v0.1.30 - Platform Function Register and Test Fixes (July 2026)

Platform Function Register and Test Fixes

What changed:

• forge platform function register now upserts. Registering a function name that already exists updates it in place.
• Manifest input on register. The command accepts a complete function manifest via --file / --body (name, description, function type, parameters, body, timeout, examples). The existing individual flags still work for sql and ai functions; python and udtf functions require a manifest. With manifest input, an optional --name asserts that it matches the manifest's name.
• forge platform function test sends your input. The sample JSON passed with --input is now delivered to the function under test. Previously it was sent under a field the service ignored, so tests executed without the provided input.

What you need to do:

• No action required. Existing register invocations continue to work.

v0.1.28 - Agent Run Commands (July 2026)

Agent Run Commands

A new forge platform agent-run command group creates, monitors, and inspects agent runs.

What changed:

• forge platform agent-run create submits a run for a service with --service-id, --framework <claude-agent-sdk|openai-agents>, and --message, plus optional --version-set (default release) and --timeout-s. --wait polls until the run reaches a terminal status (succeeded, failed, or timed_out) and prints the final result. Framework values are validated before the request is sent.
• Native agent-definition runs. create can also run an agent definition directly: --definition-id (optionally --definition-version; latest when unpinned) runs a registered definition, and --native-config <file> runs an inline definition from a JSON file. Exactly one run source is allowed per invocation.
• forge platform agent-run get --run-id <id> fetches a single run.
• Cache token accounting. Run usage output now includes cached and cache_write token counts. input_tokens excludes cached tokens, so a cache-heavy run can legitimately report near-zero input tokens.
• forge platform agent-run harness-context --service-id <id> [--version-set] shows the context a service provides to an agent run: identity and instructions, world scope, tool descriptors, guardrails, the enforced write floor, and runtime details. The default output is a concise summary; --json prints the full payload.

What you need to do:

• No action required. These are additive commands; all support --json.

v0.1.24 - Session Fleet Status and Conversation Detail (July 2026)

Session Fleet Status and Conversation Detail

What changed:

• forge platform session fleet-status [--fleet voice|tool-runner] reports live session capacity: ready, allocated, and total counts, the maximum-replica ceiling and remaining headroom when configured (rendered - when not), and a per-state breakdown. Omitting --fleet uses the server default (voice).
• forge platform conversation get <conversation-id> fetches a single conversation: a metadata block and the turn transcript. --include-tool-calls adds per-turn tool calls (name, status, call ID), including background completion records. --json outputs the full conversation detail.

What you need to do:

• No action required. These are additive commands.

v0.1.23 - Platform Command Removals (June 2026)

Platform Command Removals

Two forge platform command groups have been removed.

What changed:

• forge platform persona removed. The persona command group (list, get, create, update, delete) is no longer available. The persona entity type used by forge validate and entity sync is unaffected and continues to work.
• forge platform ses-setup removed. The email SES setup command group is no longer available. The forge platform use-case commands (including email use cases and service bindings) and the conversation --channel-kind filter are unchanged.

What you need to do:

• Update scripts that call these commands. Invocations of forge platform persona ... or forge platform ses-setup ... now fail with an unknown-command error.

v0.1.20 - Tool Dispatch Validation (June 2026)

Tool Dispatch Validation

Pre-push validation of tool dispatch settings in a context graph's tool_call_specs is now aligned with what the platform accepts.

What changed:

• result_persistence accepted. Configurations that set result_persistence on a tool call spec no longer fail push validation. This is a live platform field that was previously rejected by mistake, so any configuration setting it could not be pushed.
• Dispatch axis values validated locally. Each axis is checked before the push: execution must be blocking or background, delivery must be interrupt or queue, and lifecycle must be coupled or independent. A typo now fails fast with a clear message instead of being sent to the server.
• execution=background with delivery=queue rejected. The platform does not accept this combination, and the CLI now rejects it locally for faster feedback.
• version_constraint still rejected. This field is not part of the API and remains invalid.
• Dispatch axes in function register output. forge platform function register now prints the optional dispatch axes and their defaults next to the tool_call_specs example.

What you need to do:

• Retry configurations that set result_persistence. If a push previously failed validation because of this field, it now succeeds.

v0.1.18 - Trigger Management, Voice Check, and Voice Config Push Fix (June 2026)

Trigger Management, Voice Check, and Voice Config Push Fix

What changed:

• Full forge platform triggers command group. create, update, pause, resume, fire, and delete join the existing read-only list, get, and runs commands. create, update, and fire accept JSON via --file / --body; delete asks for confirmation unless --yes is passed; pause and resume echo the trigger's is_active state so a no-op is visible rather than silent.
• forge platform voice-check run --spans <file> runs per-call voice-isolation checks over an exported call-trace span file and exits with code 5 on failure, so it can gate CI pipelines.
• Voice config push fix. The session_provider and tts_provider fields in a service voice config are now included when pushing. Previously they were silently dropped, so provider selections never reached the platform.

What you need to do:

• Re-push voice configs that set session_provider or tts_provider. If you pushed these fields with an earlier version, push again so they take effect.

v0.1.15 - Version Set Upsert JSON Body (June 2026)

Version Set Upsert JSON Body

forge platform version-set upsert now accepts a full JSON configuration body.

What changed:

• --body / -b and --file / -f on version-set upsert. The supplied JSON becomes the version-set configuration, which is how you set fields that have no dedicated flags, such as llm_model_preferences and turn_runtime. The existing -a / -g version-pinning flags still apply on top of the body.
• --copy-from and --body / --file are mutually exclusive. Passing both fails fast instead of silently dropping the body.
• Dry-run preview shows the body's effect. The dry-run output includes the llm_model_preferences and turn_runtime values the body sets.

What you need to do:

• No action required. Existing flag-only invocations are unchanged.

v0.1.13 - Surfaces, Audit, and Access Control Commands (June 2026)

Surfaces, Audit, and Access Control Commands

Several new forge platform command groups, plus an STT provider field in voice settings.

What changed:

• forge platform surface covers the full surface lifecycle: list (with --status, --channel, --entity-id, and --limit filters), get, create (--file / --body JSON), deliver (--channel-address), progress, approve, reject (--reason), reshape, and archive (confirmation prompt, --yes to skip).
• forge platform audit provides read-only access-audit commands: list, summary, phi-access, exports, and entity-log <id>.
• forge platform triggers provides read-only trigger commands: list, get <id>, and runs <id> for scheduled trigger configuration and run history.
• forge platform review-queue provides list, dashboard, stats, history, and my-queue for the human-review queue.
• External principals authoring commands. New forge platform external-role (list, get, create, delete), forge platform role-assignment (upsert, list, get, delete), and forge platform role-grant (list, get, create, delete) command groups.
• stt_provider in voice settings. forge platform voice-settings get now shows an STT Provider row (- when unset), and the field can be set with voice-settings update --body '{"stt_provider":"..."}'.

What you need to do:

• No action required. All new commands support --env and --json.

v0.1.5 - Email Channel Commands (June 2026)

Email Channel Commands

New command groups for enabling the email channel on a workspace from the CLI.

What changed:

• forge platform ses-setup: list, create, get, verify, and delete manage email sending setups. create and verify render the DNS records you must publish as a copy-friendly, untruncated table.
• forge platform use-case: list, create, get, and delete manage channel use cases, and bind, unbind, and binding manage a use case's service binding.
• Explicit email consent flags. Creating an email use case requires explicit --unsubscribable and --accepts-cold-inbound values (no silent defaults), and a marketing use case must be unsubscribable - validated before the request is sent.
• --setup-id list filter requires --channel, enforced client-side with a friendly error.

What you need to do:

• No action required. These are additive commands.

v0.1.3 - External Integrations and Workspace-Scoped Authentication (June 2026)

External Integrations and Workspace-Scoped Authentication

This release added external integration credential management and completed workspace scoping for Platform Identity device-code authentication.

What changed:

• forge platform external-integration list (with --search / -q, --sort-by, --limit / -n, and --continuation-token), get <integration-id>, and create (--file / --body JSON).
• Credential subcommands. credential list, credential create (--file / --body JSON), credential rotate, and credential delete (confirmation prompt, --yes to skip) manage an integration's credentials.
• One-time secrets. credential create and credential rotate print the client_secret once. It cannot be retrieved again, so store it securely when shown.
• Device code includes workspace scope. When you run forge auth login --platform, the CLI now sends the workspace ID (from PLATFORM_WORKSPACE_ID in your environment file) as part of the device code request. The identity service binds the device code to that workspace - the person approving in the browser must hold a session scoped to the same workspace, and the token issued to the CLI is scoped to it.
• No change to login flow. The user experience is identical - Forge displays a code, you approve in the browser, and the CLI receives tokens automatically. The workspace scoping happens behind the scenes.
• A workspace ID is always required. Platform authentication is always bound to a workspace: PLATFORM_WORKSPACE_ID must be set in your environment file (a per-command --workspace <id> can override it). There is no unscoped device code flow - platform commands fail with a configuration error when no workspace ID is available.
• workspace create works with workspace-pinned authentication. For forge platform workspace create, the configured workspace ID (or --workspace <id>) identifies the existing workspace you authenticate against as the creator - not the workspace being created. Cached tokens are keyed per workspace, so tokens for different workspaces never collide.

What you need to do:

• No action required. The external integration commands support --env and --json, and the device-code flow automatically uses the required PLATFORM_WORKSPACE_ID.

v0.1.1 - Workspace Command Fixes (May 2026)

Workspace Command Fixes

The forge platform workspace create command now sends workspace creation requests to the correct endpoint. Previously, the command targeted a workspace-creation route that had been removed from the API, so it always failed with 405 Method Not Allowed. The command now creates workspaces under the authenticated user's account scope, which matches the current API.

What changed:

• Correct endpoint for workspace creation. forge platform workspace create now creates workspaces under the authenticated user's account scope. Users who previously saw 405 Method Not Allowed when creating workspaces through the CLI should retry with this version.
• --region removed from workspace create. The workspace's region is determined server-side, so the flag is no longer accepted.
• workspace archive requires --slug <slug>. Archiving confirms the destructive operation with the workspace slug; the flag is validated before any network call.
• New --workspace <id> flag on workspace subcommands. Overrides the environment's workspace binding for a single command, so you can operate on a freshly created workspace without editing your environment file.
• workspace update help corrected. The help text now names connector_type as the accepted field (previously it listed ehr_type, which the API does not accept).

Previous CLI Generation

These entries preserve the earlier CLI commands and their release context. Check the current reference before using them in a new integration.

v0.4.14 - Text Conversation Smoke Commands (April 2026)

Text Conversation Smoke Commands

Agent Forge now includes CLI commands for smoke-testing text conversation endpoints, covering both the REST interact path and the WebSocket streaming path.

New commands:

• forge platform conversation send-message - Send a single user message through the text conversation REST endpoint. Specify a service ID and message text; optionally pass a conversation ID to resume a durable conversation. The command displays the agent's response, conversation ID, and status. Use the returned conversation ID with subsequent calls to continue the same conversation.
• forge platform conversation text-ws-smoke - Open a WebSocket text-stream connection, wait for session initialization, send one message, and verify the agent responds. The command reports pass/fail, the conversation ID, and the agent's response text. Configurable timeouts control how long to wait for session start and agent response. An optional greeting drain window allows initial greeting events to arrive before the test message is sent.

Both commands support --json output for CI integration and --env for environment selection.

Usage examples:

Command	Key Options
forge platform conversation send-message	--service-id, --message, --conversation-id, --entity-id, --env, --json
forge platform conversation text-ws-smoke	--service-id, --message, --conversation-id, --entity-id, --ws-url, --timeout, --greeting-drain, --env, --json

No breaking changes. These are additive commands under the new forge platform conversation subgroup.

v0.4.13 - Platform Identity Authentication (April 2026)

Platform Identity Device Code Authentication

Agent Forge now supports Platform Identity authentication using the RFC 8628 device code flow. This is the recommended authentication method for interactive CLI use, replacing the need for static API keys during development.

What changed:

• Device code login - forge auth login now initiates a device code flow when the environment is configured with a Platform Identity URL. The CLI requests a device code, opens the browser to an approval page, and polls for authorization. Once approved, the access token and refresh token are cached in the system keyring.
• Silent token refresh - Subsequent CLI commands use the cached token. When the access token expires, the CLI silently refreshes it using the stored refresh token without requiring re-authentication.
• Auth status and logout - forge auth status shows the current authentication state (authenticated, expired, or not logged in). forge auth logout clears cached tokens from the keyring.
• Automatic method selection - The CLI automatically selects the authentication method based on the environment configuration: Platform Identity when an identity URL is configured, API key when a bearer token is present.

No breaking changes. Existing API key authentication continues to work. Environments without Platform Identity configuration are unaffected.

v0.4.12 - Canonical Value Lint for Context Graphs (May 2026)

Pre-Sync Validation for Inline Canonical Values

The sync-to-remote pipeline now detects canonical values - phone numbers, email addresses, and URLs - inlined directly into context graph state prose. Inline canonical values are a common authoring mistake that causes silent data drift: when a graph is cloned or updated, hardcoded values like phone numbers can be accidentally mutated, and the agent reads incorrect information to callers without any visible error.

The validator scans prose fields (descriptions, instructions, boundary constraints, exit conditions, and action descriptions) in every context graph state. When an inline canonical value is found, Forge emits a warning identifying the state, field, and matched value, along with guidance to move the value into structured context (such as world model entities or workspace settings) and reference it abstractly in the prose.

This check runs automatically during pre-sync validation alongside existing checks. No configuration is required. The validator catches:

• Phone numbers in digit form - patterns like 555-010-1234, [phone], or 555.010.1234
• Phone numbers in spelled-out form - sequences of seven or more number words (e.g., "five five five zero one zero one two three four"), which appear in TTS-optimized prose
• Email addresses - standard email patterns
• URLs - bare http and https links

Canonical values should live in structured context that the runtime injects at render time - for example, location or insurance entities in the world model, or workspace-level settings. State prose should reference these values abstractly (e.g., "provide the clinic's returning-patient line from your context") rather than hardcoding the digits.

v0.4.11 - Caller ID for Simulation Commands (May 2026)

Simulated Caller ID in Platform Simulation Commands

The forge platform sim session-create, forge platform sim smoke-test, and forge platform sim bridge commands now accept a --caller-id flag that sets a simulated caller phone number for the session. When provided, the agent resolves the number as a known caller, so the session starts with full patient context - useful for testing caller-specific flows like greeting a known patient by name or loading their clinical history.

The flag requires E.164 format: a + followed by 2-15 digits with the first digit 1-9 (e.g. [phone]). Invalid values are rejected before the request is sent.

Command	New Flag
forge platform sim session-create	--caller-id <E.164 number>
forge platform sim smoke-test	--caller-id <E.164 number>
forge platform sim bridge	--caller-id <E.164 number>

Omit the flag to simulate an unknown caller (the default behavior).

Examples:

v0.4.10 - Platform Insights and Call Trace Analysis (May 2026)

Platform Insights Commands

New forge platform insights command group for querying workspace data and discovering schema metadata through the platform insights service:

Command	Description
forge platform insights sql	Execute a read-only SQL query against the workspace data warehouse
forge platform insights schema	List available tables, columns, and functions in the workspace schema
forge platform insights digest	Get a cached workspace health digest with entity counts, data quality signals, and suggested questions
forge platform insights suggestions	Get contextual starter questions for exploring workspace data

The sql command accepts inline SQL or reads from a file with --sql-file. Results render as a formatted table by default, or as structured JSON with --json. Common SQL errors include targeted hints for discovering queryable objects.

Call Trace Analysis Commands

New forge platform trace command group for accessing deep call understanding from the intelligence pipeline:

Command	Description
forge platform trace list	List call trace analyses with optional outcome filtering and pagination
forge platform trace get	Get detailed trace analysis for a specific call

Trace analysis surfaces:

• Emotional arc - How caller sentiment evolved across the conversation
• Key decision moments - Critical points with causal attribution and quality assessment
• Coaching recommendations - Actionable improvements tied to specific moments in the call
• Counterfactuals - Alternative actions that could have changed the outcome
• Emotional shifts - State changes detected in the caller with trigger identification
• Signal-response alignment - Whether the agent responded appropriately to caller signals
• Interaction dynamics - Turn-taking quality, information density, rapport trajectory, and repair effectiveness
• Missed opportunities and emergent patterns - Behavioral patterns the agent could act on

The list command supports filtering by outcome (succeeded, partially, failed, abandoned), lookback window (--days), and pagination (--limit, --continuation-token).

All commands support --json for structured output and --env for environment selection.

Improved API Error Messages

Platform API error responses (401, 403, 422) now include the specific error detail returned by the server, making authentication and permission issues easier to diagnose.

v0.4.9 - Simulation Run Tracking, Schema Validation (April 16, 2026)

Simulation Runs Now Tracked and Preserved

All simulation conversations created by forge platform sim commands are now tagged with simulation at creation time, so they show up in the Agent Performance dashboard's simulation filter and remain queryable by tag after the run completes. Platform simulation sessions are no longer deleted once a smoke test or bridge run finishes. Sessions persist so tagged analytics and post-hoc inspection keep working.

The Classic API equivalent (forge sim simulate, simulate-step, simulate-batch, bridge runs) now emits the same simulation=true tag on the underlying conversation, giving both API surfaces consistent tracking.

Platform Command Schema Validation

Query parameters on every forge platform ... command are now validated against the live Platform API OpenAPI spec before the request is sent, and JSON responses are validated against the published response schema after the request returns. Schema drift surfaces as a clear error rather than a silent mismatch.

Platform CLI Parity Close-Out

Remaining gaps in Platform API coverage were closed. Every endpoint exposed under api.platform.amigo.ai now has a corresponding forge platform ... command, bringing the CLI to parity with the API surface.

v0.4.8 - Trigger Management (April 14, 2026)

Trigger CLI Commands

New forge platform trigger command group for managing scheduled action triggers:

Command	Description
forge platform trigger create	Create a trigger with cron schedule and action binding
forge platform trigger list	List triggers with active/inactive filtering
forge platform trigger get	Get trigger details including next fire time
forge platform trigger update	Update trigger configuration
forge platform trigger delete	Delete a trigger
forge platform trigger pause	Pause a trigger's schedule
forge platform trigger resume	Resume a paused trigger
forge platform trigger fire	Manually fire a trigger for testing
forge platform trigger runs	View trigger execution history

All commands support --json for structured output and --env for environment selection.

v0.4.6 - Simulation Bridge Persistence & CLI Alignment (April 13, 2026)

Simulation Bridge Persistence & Reports

The simulation bridge now persists test results across runs, enabling trend analysis and regression detection. New capabilities:

• Run reports - Generate summary reports after simulation runs with pass/fail counts, score distributions, and failure breakdowns
• Tag-based test library - Tag simulation scenarios for selective execution (e.g., forge sim run --tag scheduling to run only scheduling-related tests)
• Result persistence - Test outcomes are stored locally, so you can compare current results against previous runs

CLI Alignment with Live API

Seven schema and path fixes verified against the staging API:

• Voice settings URL path corrected to include workspace segment
• Billing, simulation, and world model schemas updated to match current API responses
• Phone number schema field alignment

v0.4.5 - Platform Functions & Simulation Coverage (April 8, 2026)

Platform Function Commands

New forge platform function command group for managing platform functions: declarative SQL, Python, and AI functions that agents call mid-conversation.

Command	Description
forge platform function register	Register a new platform function
forge platform function list	List all registered functions
forge platform function test	Execute a function with test parameters
forge platform function delete	Remove a function registration
forge platform function query	Run an open-scope SQL query against workspace data
forge platform function catalog	Display the full function catalog offline
forge platform function sync	Sync function definitions between local files and the platform

Simulation Coverage Commands

New forge platform simulation command group for branch-and-bound simulation coverage runs.

Command	Description
forge platform simulation create	Create a new coverage run for a service
forge platform simulation session	Create a session within a coverage run
forge platform simulation step	Step a session forward with a simulated user message
forge platform simulation fork	Fork a session into N children at a decision point
forge platform simulation score	Score a session against configured metrics
forge platform simulation graph	Retrieve the coverage knowledge graph
forge platform simulation complete	Complete a run and clean up ephemeral branches

Vendor-Neutral Function Naming

Platform function identifiers renamed from uc_ prefix to fn_ prefix for vendor-neutral naming. Existing references are automatically migrated.

Platform CLI Parity

New command groups closing remaining CLI-to-API coverage gaps:

• forge platform persona - CRUD for cross-channel agent identities
• forge platform billing - Workspace billing and usage information
• forge platform settings - Workspace configuration (environments, workflows, branding)
• forge platform network - Egress IP listing for firewall allowlisting

All commands support --json for structured output and --env for environment selection.

v0.4.4 - Surface E2E Testing (April 6, 2026)

Surface End-to-End Testing

New forge platform surface e2e command for testing the full surface lifecycle from the CLI: create a surface, deliver it, render the patient-facing form, and submit data, all in one command.

The command exercises the complete flow: surface creation via Platform API, spec retrieval, form rendering, and submission. It validates that branding settings are applied correctly and that submitted data flows through to the world model. Useful for verifying surface configuration changes before deploying to production.

Uses Pydantic models for request/response validation, matching the Platform API schemas.

v0.4.3 - Context Graph Rename & Voice Configuration (April 5, 2026)

HSM → Context Graph Rename

All CLI commands and API paths now use the "context graph" terminology consistently:

• API paths renamed: hsms/ → context-graphs/, sims/ → simulations/
• CLI flags renamed: --hsm-id → --context-graph-id
• Entity type selector: -e hsm → -e context-graph
• All user-facing output now says "Context Graph" instead of "HSM"

Voice Configuration Command

New forge platform service voice-config command for per-service voice tuning:

Three presets available: ultra_low_latency (demos, coaching), balanced (default), quality (complex healthcare). Configures filler style, barge-in sensitivity, response limits, and TTS model selection.

Bug Fixes

• Service list now correctly shows Context Graph ID (was blank due to field rename)
• Version set commands now read context_graph_version_number (was silently reading None)
• apply-policy limit corrected from 50 → 20 (matches API constraint)

v0.4.2 - Conversation Quality Check (April 3, 2026)

Quality Check Command

New forge quality check command for scanning workspace conversations against 5 behavioral detectors:

Detector	What It Finds
Character degeneration	Repeated characters, low entropy output, stuttering patterns
Stuck agent loops	Agent repeats the same response while the caller changes topics
Repetitive patterns	High similarity across sliding message windows
Word salad	Incoherent output patterns like or-chains and excessive word repetition
Phantom success	Agent claims a tool call succeeded when the tool actually returned an error

Queries production conversation data directly. Supports configurable lookback windows, verbose mode with message excerpts, and JSON output for scripting.

v0.4.1 - VoiceSim CLI & Tool Testing Commands (April 2, 2026)

Voice Simulation Commands

New forge platform sim commands for managing VoiceSim runs from the CLI:

Command	Description
forge platform sim create	Create a new simulation run
forge platform sim list	List simulation runs for the workspace
forge platform sim sample	Sample and evaluate N configuration points
forge platform sim evaluate	Evaluate a specific configuration point against a scenario
forge platform sim get	Get run status and best results
forge platform sim summary	Get aggregated summary with best-per-scenario and penalty frequency
forge platform sim points	List scored points (by score or chronologically)
forge platform sim complete	Mark a run as finished

Tool Testing Commands

New forge platform tool-test commands for testing HSM tools without phone calls:

Command	Description
forge platform tool-test resolve	List available tools for a service with schemas
forge platform tool-test execute	Execute a tool with custom parameters and dry run mode

v0.4.0 - Platform API CLI, Simulation Engine & Changelog (April 1, 2026)

Major release. Agent Forge now provides full CLI coverage for the Platform API, a dedicated simulation engine, cross-entity change traceability, and bulk sync from local files.

Platform API CLI (73 Endpoints)

forge platform commands now cover all Platform API resources: agents, services, skills, context graphs, integrations, phone numbers, data sources, FHIR, pipeline, operators, surfaces, analytics, safety, and workspaces. Every read, create, update, and delete operation available through the Platform API can be performed from the CLI.

Simulation Engine

New forge simulation command group for coverage-optimized testing against context graphs:

Command	Description
forge simulation run	Execute a simulation run against a target context graph with configurable personas and scenarios
forge simulation plan	Generate a test plan that maximizes state and transition coverage across the context graph
forge simulation evaluate	Score simulation results against quality metrics and expected outcomes
forge simulation cleanup	Remove simulation artifacts (test users, conversations, recordings) from a workspace

The simulation engine analyzes context graph structure to generate test plans that exercise every reachable state and transition, identifying untested paths and edge cases. Key capabilities include parallel execution with ephemeral test users, atomic budget enforcement across concurrent sessions, a batched classifier for state transition prediction, and composable pipelines (plan --json | run -t -).

Simulation Bridge

forge simulation bridge provides a higher-level simulation workflow that generates scenario variations from a natural-language objective and runs them against a service. Unlike simulation run (which requires explicit state targets), the bridge uses an LLM to create realistic test scenarios and runs them with platform interaction insights for state and tool coverage tracking. Supports pass^k consistency testing (--runs flag) to measure scenario reliability across repeated runs.

Interaction Insights on simulate-step

forge conversation simulate-step now returns an interaction_insights object in its JSON output: current state, action, objective, behaviors triggered, tools called, and state transitions. Gives coding agents (Claude Code, Cursor) visibility into what the agent did internally at each turn.

Cross-Environment Permissions Fix

Simulation test users are now created with DemoProspectRole instead of DefaultUserRole, fixing permission errors when running simulations in non-dogfood environments. Provision with forge role provision --role DemoProspectRole --env [ORG_ID].

Changelog Command

forge changelog provides cross-entity change traceability: view a chronological log of all configuration changes (agent updates, context graph versions, service deploys, integration edits) across a workspace. Filterable by entity type, date range, and actor.

Text Agent & Outbound Triggers

New CLI commands for managing text (SMS) agent sessions and scheduling automated outbound messages:

Command	Description
forge platform session list-text	List active and recent text sessions, filterable by service, channel, and status
forge platform session create-outbound	Create an outbound text session that sends a greeting and conducts a multi-turn SMS conversation
forge platform outbound-trigger list	List outbound triggers (appointment-based SMS scheduling rules)
forge platform outbound-trigger get	Get details for a specific trigger
forge platform outbound-trigger create	Create a new trigger with cron schedule, appointment window, consent checks, and daily send limits

Platform Push

forge platform push enables bulk sync from local configuration files to a workspace. Define agents, context graphs, services, and skills as local files and push them in a single operation. Useful for promoting configurations across environments (staging to production) or restoring from version-controlled snapshots.

v0.3.25 - GWS CLI & Linear Integration Skills (March 9, 2026)

New skill documentation added:

• GWS CLI: Google Workspace CLI skill covering auth, multi-account, MCP setup, and operations for Drive/Sheets/Gmail/Calendar/Tasks (brew install googleworkspace/tap/gws)
• Linear Ticket Workflow: Documented Linear ticket lifecycle for customer workspace work
• Linear Ticket Script: New scripts/create_linear_tickets.py for creating parent Linear tickets

v0.3.24 - Tool Developer Breaking Changes (March 6, 2026)

Breaking change: run_tool() signature now requires a 6th parameter user_variables: UserVariables. Invocation mode conversation renamed to regular, and conversation-test removed.

Impact: High | Action Required: Yes, for all tool developers

The tool scaffold signature and project configuration have been updated.

run_tool() Signature Change

Invocation Mode Rename

Before	After
conversation	regular
conversation-test	(removed)

Only two modes remain: regular and conversation-simulation.

Updated pyproject.toml Requirements

Setting	Before	After
pyright	>=1.1.403,<2	>=1.1.407,<2
ruff	>=0.12.10,<0.15	>=0.14.6,<0.15
amigo-tool-scaffold source	path = "../amigo_tool_scaffold", editable = true	path = "../amigo_tool_scaffold.tar.gz"
extend-select	["I"]	["I", "SLF001"]

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

Example: List Active Grants

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 has been removed. Use forge conversation request-access for per-conversation temporary access instead.

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)

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, so developers can 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

Example: Impersonation

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

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 so developers can 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

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

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

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

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, reducing tool development setup to a single command.

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

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

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

Environment Configuration

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

Setup

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

Example: Stop-on-Finished in Simulate

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)

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 lets you test 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

Example: Standalone Context Management

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

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

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

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

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

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 analytics data

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, giving you 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

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.

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

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)

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 prompt's 13 sections, 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:

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

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

Example Output (Summary)

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), SQL discovery (C), and full conversation mutation chain (D).

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

Example: Mid-Conversation Evaluation

Example: JSON Output

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.

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 lets you run 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

Example: Manual Test User Management

JSON Output with Test User

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

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

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

Agent Forge v0.3.7 introduces full 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

Example: Agent-Driven Step-by-Step Testing

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

Example: Batch Simulations

Run multiple simulations from a configuration file:

Example: Deterministic Workflows

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

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

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

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

Agent Forge v0.3.5 introduces the forge databricks command group for configuring MCP integration with your data warehouse. This lets coding agents execute SQL queries directly against your workspace data.

New Commands

Command	Description
forge databricks setup	Generate MCP configuration from existing CLI profiles
forge databricks validate	Check configuration format and token presence
forge databricks status	Show configured and unconfigured workspaces

The setup command generates MCP server configuration from your existing CLI profiles, supporting multiple environments (staging, production) across regions. Existing non-data-warehouse MCP server configurations are preserved when updating.

Security Note

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

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

Example: Auto-fix Issues

What Gets Fixed

Banned Character	Replacement
' ' (smart quotes)	'
" " (smart quotes)	"
Unicode 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

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 lets you automate 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, making it easier to test 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

Example: With Persona and Scenario

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

Example: Configure Temperament and Response Mode

Example: Add Custom Observations

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

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 lets you debug and process feedback without leaving the terminal.

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

New Commands

Command	Description
forge conversation get	Fetch and display conversation messages with rich formatting
forge conversation transcript	Get a plain text transcript of the conversation
forge conversation insights	Debug view with states, dynamic behaviors, and tool calls
forge conversation batch	Process multiple conversations from a file

URL Format Support

The commands accept full conversation URLs in multiple formats:

Example: View Conversation

Example: Debug with Insights

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

• State: Which context graph state the agent was in
• Dynamic Behaviors: Which dynamic behavior was triggered (if any)
• Tool Calls: Which tools were called, their inputs, outputs, and duration
• State Transitions: How the agent navigated through the context graph

Example: Batch Processing

Process multiple conversations from a file containing URLs:

Key Features

• Rich console output: Messages displayed with timestamps, senders, and proper formatting
• Multiple output formats: Human-readable tables, plain text transcripts, or JSON
• Flexible filtering: Filter by message type, limit messages, include/exclude thoughts
• Batch processing: Process multiple conversations with progress tracking
• Debug insights: View context graph states, dynamic behaviors, and tool call details
• URL parsing: Automatically extracts org and conversation ID from URLs