# Agent Forge SDK
Release history for the Agent Forge SDK (configuration management tooling).
{% hint style="info" %}
**Current Version**: v0.4.9 | **Compatibility**: Requires Platform API v0.9.0+
{% endhint %}
***
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.7 - Platform CLI Parity, Simulation Testing & Function Management (April 14, 2026)
**Full Platform CLI Parity**
The Agent Forge CLI now covers the full Platform API surface. New command groups close all remaining gaps:
| Group | Commands | What It Covers |
| ------------- | -------- | ----------------------------------------------------------------------------------------------------------- |
| `persona` | 5 | Create, list, get, update, delete agent personas |
| `billing` | 18 | Usage summaries, invoices, customer management, dashboard, trends |
| `network` | 1 | Phone number listing and management |
| `settings` | +6 | Voice settings, behavior settings, memory settings, scribe settings, metrics settings, gap scanner settings |
| `sim` | +14 | Interactive simulation sessions, forking, graph coverage, recommendations |
| `surface` | +2 | Surface creation and delivery |
| `integration` | +1 | Endpoint testing |
| `recording` | +1 | Recording access |
| `world` | +1 | Duplicate detection |
| `pipeline` | +1 | Source overview |
All HTTP interfaces validated with Pydantic schemas matching the live OpenAPI spec.
**Platform Simulation Testing**
Two new commands for testing agent configurations through the Platform API simulation infrastructure:
* **`forge platform sim smoke-test`** - Single-turn sanity check that creates a tracked simulation session, sends a test message, and reports the agent's response. Useful for quick post-deploy validation.
* **`forge platform sim bridge`** - Multi-scenario AI-driven testing using tracked simulation runs. An LLM generates test scenarios, plays the caller role, and evaluates agent responses. Results are tracked in the platform for dashboard visibility and billing.
Both commands create tracked simulation runs, so sessions appear in the Agent Performance dashboard and count toward metering.
**Simulation Run Management**
New commands for managing tracked simulation runs:
| Command | Description |
| --------------------------------- | ----------------------------------- |
| `forge platform sim run-create` | Create a tracked simulation run |
| `forge platform sim run-list` | List simulation runs with filtering |
| `forge platform sim run-complete` | Mark a simulation run as complete |
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.
```bash
forge platform surface e2e --entity-id --env myorg
```
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:
```bash
# View current config
forge platform service voice-config --get --service-id --env myorg
# Apply a preset
forge platform service voice-config --preset balanced --service-id --env myorg
# Custom JSON config
forge platform service voice-config --body '{"filler_style":"backchannel"}' --service-id --env myorg
```
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 |
```bash
forge quality check [--days 7] [--verbose] [--json]
```
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 via ThreadPoolExecutor with ephemeral test users, atomic budget enforcement across concurrent sessions, a batched LLM classifier (Claude Haiku) 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.
PRs: [#338](https://github.com/amigo-ai/agent-forge/pull/338), [#347](https://github.com/amigo-ai/agent-forge/pull/347), [#366](https://github.com/amigo-ai/agent-forge/pull/366), [#370](https://github.com/amigo-ai/agent-forge/pull/370)
Docs: `docs/reference/simulation-cli.md`, `docs/skills/evals/simulation-bridge-testing.md`, `docs/skills/platform-commands.md`
v0.3.27 - SQL Analytics, Auth Refactor & Simulation Fixes (March 28, 2026)
**Analyze Commands (New)**
New `forge analyze` command group replacing the previous dashboard commands with a unified SQL analytics interface:
| Command | Description |
| ----------------------------- | ----------------------------------------------------------------------------------------- |
| `forge analyze query` | Execute ad-hoc SQL SELECT queries (inline or `--sql-file`). 1,000-row limit, 30s timeout. |
| `forge analyze describe` | Preview output schema without executing (validates JOINs and column types) |
| `forge analyze tables` | List workspace tables with `--filter` (SQL LIKE patterns) |
| `forge analyze schema` | Describe table columns: names, types, comments |
| `forge analyze sample` | Preview sample rows (default 5, max 20 via `--rows`) |
| `forge analyze detail` | Rich table metadata: row count, size, partitioning, nullability, freshness |
| `forge analyze profile` | Column distribution: cardinality, null rate, min/max values |
| `forge analyze catalog` | Display full data catalog offline without a database connection |
| `forge analyze template list` | List pre-built query templates, filterable by category |
| `forge analyze template show` | Display template SQL and parameters |
| `forge analyze template run` | Execute a template with `-P key=value` parameters |
All commands support `--json` for structured output. Queries are proxied through the backend SQL API with rate limiting (6 req/min) and read-only enforcement.
**Manual Update Command**
`forge update` checks for new commits on `origin/main`, shows a preview, and applies the update. Stashes uncommitted changes during the update and restores them afterward. Auto-installs dependencies when `pyproject.toml` changes.
Background auto-update checks run every 30 minutes before each command.
**Metric Versioning**
Metrics now support version tracking with a `latest_version` field. Existing metrics are automatically migrated to the versioned schema. Each metric version captures the full evaluation definition (value type, bounds/categories, description), enabling teams to evolve scoring criteria while maintaining history.
**Auth Improvements**
Cached token auth is now properly cleared on logout.
**Simulation Improvements**
* **User variables, language, and timezone** now configurable on simulation test users
* **`initial_message` passthrough** - `simulate-batch` correctly passes initial messages to conversation creation
* **Cross-org user invite** - New `forge user invite` command for inviting users across organizations
**Additional Changes**
* Simplified response schemas for agent HSM version endpoints
* Organization image assets documentation
v0.3.26 - Organization Management, Simulation Hardening & Action Invocations (March 24, 2026)
**Organization Creation (Feature Parity)**
`forge org create` now has full feature parity with the standalone `create_org` repo. Create and configure organizations directly from the CLI without needing a separate tool.
**Action Invocations Command**
New command to inspect tool invocation history:
* `forge action invocations` - View invocation logs for actions with input parameters and results
**Simulation Improvements**
Production hardening of the batch simulation CLI:
* **`--test-user` flag** on `forge simulate-batch` for scoping simulation runs
* **`summary.json` output** for programmatic consumption of simulation results
* Improved error reporting for batch simulation failures
* Fixed validation and config file handling for `--init` compatibility
**Service Management Best Practices**
New documentation for service lifecycle management including health monitoring, drift detection, and multi-environment support.
**LLM Catalog Updates**
Added support for latest model families in the LLM catalog for per-interaction model selection.
**Additional Changes**
* Creator and audit fields (created-by, updated-at, updated-by) now displayed in `forge persona list` and `forge scenario list`
* `product_type` added as mandatory service tag with automatic metric assignment
* Validation skip for inactive services
* Multilingual service builder skill documentation
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)
{% hint style="danger" %}
**Breaking change**: `run_tool()` signature now requires a 6th parameter `user_variables: UserVariables`. Invocation mode `conversation` renamed to `regular`, and `conversation-test` removed.
{% endhint %}
**Impact**: High | **Action Required**: Yes, for all tool developers
The tool scaffold signature and project configuration have been updated.
**`run_tool()` Signature Change**
```python
# Before (5 parameters)
async def run_tool(tool_input, metadata, config, conversation, send_status_event):
# After (6 parameters)
from amigo_tool_scaffold.user_variables import UserVariables
async def run_tool(tool_input, metadata, config, conversation, send_status_event, user_variables: UserVariables):
```
**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.23 - Creator Fields & Temporary Access Fixes (March 3, 2026)
**Creator & Audit Fields in CLI Output**
Persona and scenario list commands now display creator, updated-at, and updated-by information for better traceability.
**What Changed**
* **Creator Column**: `forge persona list` and `forge scenario list` now show who created each resource
* **Updated By/At Columns**: See when and by whom resources were last modified
* **Efficient User Resolution**: User IDs are resolved to display names via batched API calls with caching
**Temporary Access Bug Fixes**
Fixes to the conversation access system introduced in v0.3.22:
* **API Path Fix**: Corrected endpoint paths to use `/role/temporary_permission_grant(s)/` matching the backend API
* **Tag Format Fix**: Changed tag value from `forge-cli` to `forge_cli` (API requires `^\w\s+$` pattern, no hyphens)
* **Super Admin Requirement Documented**: Only `DefaultSuperAdministratorRole` can grant temporary conversation access; `DefaultAmigoAdministratorRole` fails the backend's subsetting check
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**
```bash
# 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 colleague@example.com
```
**Example: List Active Grants**
```bash
# 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 |
{% hint style="danger" %}
**Breaking change**: `AgentEngineerRole` has been removed. Use `forge conversation request-access` for per-conversation temporary access instead.
{% endhint %}
**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](https://github.com/amigo-ai/agent-forge/pull/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, 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**
```bash
# List users with search
forge user list -e myorg --search "john"
# Get user by email
forge user get -e myorg --email "john@example.com"
# Create user with context
forge user create -e myorg --first-name John --last-name Doe --email "john@example.com" \
-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**
```bash
# 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 "john@example.com" -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](https://github.com/amigo-ai/agent-forge/pull/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 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**
```bash
# 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](https://github.com/amigo-ai/agent-forge/pull/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](https://github.com/amigo-ai/agent-forge/pull/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**
```bash
# 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](https://github.com/amigo-ai/agent-forge/pull/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**
```bash
# 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 john@example.com
```
**Environment Configuration**
```env
# 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](https://github.com/amigo-ai/agent-forge/pull/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 ` 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**
```bash
# 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**
```bash
# 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](https://github.com/amigo-ai/agent-forge/pull/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 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**
```bash
# 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**
```bash
# 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](https://github.com/amigo-ai/agent-forge/pull/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**
```bash
# 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**
```bash
# 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](https://github.com/amigo-ai/agent-forge/pull/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 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**
```bash
# 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 analytics data
**Related Pull Request**
* [agent-forge#248](https://github.com/amigo-ai/agent-forge/pull/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, 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**
```bash
# 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](https://github.com/amigo-ai/agent-forge/pull/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**
```bash
# 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](https://github.com/amigo-ai/agent-forge/pull/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**
```bash
# 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**
```bash
# 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), SQL discovery (C), and full conversation mutation chain (D).
**Related Pull Request**
* [agent-forge#243](https://github.com/amigo-ai/agent-forge/pull/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 -- 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**
```bash
# 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**
```bash
# 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**
```json
{
"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](https://github.com/amigo-ai/agent-forge/pull/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 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 ` | Wait for post-processing completion (memories, metrics) |
**Example: Parallel Simulations with Test Users**
```bash
# 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**
```bash
# 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:
```json
{
"conversation_id": "...",
"conversation_url": "...",
"test_user": {
"id": "user_id_here",
"email": "simtest_abc123@test.example.com",
"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](https://github.com/amigo-ai/agent-forge/pull/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 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**
```bash
# 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:
```bash
# 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:
```bash
# 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:
```bash
# 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](https://github.com/amigo-ai/agent-forge/blob/main/docs/AUTOMATED_SIMULATION_GUIDE.md) - 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 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.
**Related Pull Request**
* [agent-forge#205](https://github.com/amigo-ai/agent-forge/pull/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 - 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.
**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**
```bash
# 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**
```bash
# 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 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**
```bash
# 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:
```bash
# 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**
```bash
# 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**
```bash
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 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:
```bash
# 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**
```bash
# 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
```bash
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:
```bash
# 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 lets you debug and analyze 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.
{% hint style="warning" %}
**30-Day Retention**: Prompt logs are only available for conversations within the last 30 days.
{% endhint %}
**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**
```bash
# 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**
```bash
# 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 storage prefix directly:
```bash
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 storage 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**
```bash
# 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**
```bash
# 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:
```bash
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), allowing consistent management across all service components.
**New Asset Discovery Commands**
```bash
# 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:
```bash
$ 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:
```bash
$ 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](https://docs.amigo.ai/developer-guide/core-api/services#dynamic-behaviors) - Service integration with behaviors
* [Dynamic Behavior Tables](https://docs.amigo.ai/developer-guide/data-access/organization-tables/dynamic-behaviors) - 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`**
```bash
# 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](https://docs.amigo.ai/developer-guide/devops/version-sets-best-practices) - 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 --json` | List services as JSON array |
| `forge version-set list -e --json` | List version sets as JSON array (includes name in each entry) |
| `forge version-set diff -s -e --json` | Output structured diff with both configs and `identical` flag |
**Example: Scripting with JSON Output**
```bash
# 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](https://docs.amigo.ai/developer-guide/devops/version-sets-best-practices) - 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, so you can discover assets without going through services first.
**New Commands**
| Command | Description |
| ------------------------------------------------ | --------------------------------------------------- |
| `forge asset agent list -e ` | List all agents with latest version numbers |
| `forge asset context-graph list -e ` | List all context graphs with latest version numbers |
| `forge asset agent list -e --json` | JSON output for scripting |
| `forge asset context-graph list -e --json` | JSON output for scripting |
**Also Added**: `--json` flag to existing `version-list` commands for consistency:
* `forge asset agent version-list -e --json`
* `forge asset context-graph version-list -e --json`
**Example: Complete Asset Discovery Workflow**
```bash
# 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](https://docs.amigo.ai/reference/agent-forge) - 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 -e ` | Preview rollback (dry-run) |
| `forge version-set rollback -s -e --apply` | Execute the rollback |
**Example: Rollback Workflow**
```bash
# 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](https://docs.amigo.ai/developer-guide/devops/version-sets-best-practices) - 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, so you can complete the full workflow without leaving the terminal.
**New Commands**
| Command | Description |
| ---------------------------------------------- | ---------------------------------------------------- |
| `forge service list -e ` | List all services with tags and version set counts |
| `forge service list -e --tag ` | Filter services by tag (e.g., `production`, `phone`) |
| `forge service show -e ` | Show service details including linked assets |
| `forge service show -e --json` | JSON output for scripting |
**Example: Complete Discovery Workflow**
```bash
# 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](https://docs.amigo.ai/developer-guide/devops/version-sets-best-practices) - 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**
```bash
$ 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:
```bash
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](https://docs.amigo.ai/developer-guide/devops/version-sets-best-practices) - 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 lets users 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 -e ` | List all versions of an agent |
| `forge asset agent version-show -e ` | Show details of a specific agent version |
| `forge asset context-graph version-list -e ` | List all versions of a context graph |
| `forge asset context-graph version-show -e ` | Show details of a specific context graph version |
**Example: Discover Versions Before Pinning**
```bash
# 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](https://docs.amigo.ai/developer-guide/devops/version-sets-best-practices) - 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**
```bash
$ 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)**
```bash
$ 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](https://docs.amigo.ai/developer-guide/devops/version-sets-best-practices) - CLI validation documentation
* [Channel Tagging](https://docs.amigo.ai/developer-guide/devops/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`:
```bash
# 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:
```bash
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](https://docs.amigo.ai/developer-guide/devops/version-sets-best-practices) - 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.
```json
{
"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 ` to check your configurations.
v0.2.14 - LLM Preferences Validation (January 10, 2026)
Agent Forge v0.2.14 adds full validation for version set LLM preferences against channel and preset constraints. This makes sure 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](https://docs.amigo.ai/developer-guide/devops/channel-tagging) - 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, supporting 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**
```bash
# 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:
```yaml
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](https://docs.amigo.ai/developer-guide/devops/version-sets-best-practices) - CLI commands and workflow guide
* [Channel Tagging System](https://docs.amigo.ai/developer-guide/devops/channel-tagging) - 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 lets you 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**
```bash
# 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**
```bash
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](https://docs.amigo.ai/developer-guide/devops/channel-tagging) - 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)**:
```json
{
"tags": [
{"key": "phone", "value": null},
{"key": "voice_premium", "value": null}
]
}
```
**After (recommended)**:
```json
{
"tags": ["phone", "voice_premium"]
}
```
Or in YAML:
```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](https://docs.amigo.ai/developer-guide/devops/channel-tagging) - 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:
```bash
# 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](https://docs.amigo.ai/developer-guide/getting-started/regions-and-endpoints) - Regional LLM availability details
* [Channel Tagging System](https://docs.amigo.ai/developer-guide/devops/channel-tagging) - 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:
```json
{
"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 ` | Show channel profile and constraints |
| `show-tags ` | Show tags for a channel/preset combination |
| `validate-preset ` | 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**
```bash
# 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](https://docs.amigo.ai/developer-guide/devops/channel-tagging) - Configuration guide and best practices
v0.2.8 - Role Provisioning CLI (January 9, 2026)
Agent Forge v0.2.8 introduces role provisioning capabilities, so organizations can 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**
```bash
# 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:
```bash
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:
```json
{
"actions": [
{
"type": "inject-instruction",
"instruction": "Your instruction text here",
"overrides_instructions": false
}
]
}
```
New `change-tool-candidates` action type (for future use):
```json
{
"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:
```bash
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
```
2. 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**
```bash
[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 --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**
```bash
forge version rollback --entity-type --id --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**
```bash
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**:
```bash
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:
```bash
forge action publish --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:
```bash
# Before (v0.2.1)
forge action publish --env production
# ... prompted for ID ...
# After (v0.2.2)
forge action publish --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](https://github.com/amigo-ai/agent-forge/pull/133)) adds full schema support for the new `ToolCallState` type in Context Graph definitions, so you can manage and deploy tool-call states locally through the Agent Forge CLI.
{% hint style="info" %}
This release accompanies API v0.6.1. See [Amigo API changelog](https://docs.amigo.ai/api-reference/change-logs/amigo-api) for backend changes.
{% endhint %}
v0.2.0 - Tool Call Result Persistence (November 13, 2025)
Agent Forge v0.2.0 ([PR #132](https://github.com/amigo-ai/agent-forge/pull/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.
{% hint style="warning" %}
**Breaking Change**: The `result_persistence` field is now required in all tool call specifications.
{% endhint %}
> **TL;DR**: Add `"result_persistence": "persisted-preferred"` to all `tool_call_specs` in your Context Graphs. [See migration guide below](#migration-guide)
**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"`:
```json
{
"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:
```json
{
"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](https://docs.amigo.ai/api-reference/amigo-api#tool-call-result-persistence-implementation).
**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.
```bash
# 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:
```bash
# 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](#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](https://github.com/amigo-ai/agent-forge/blob/v0.2.0/sync_module/entity_services/context_graph/CONTEXT_GRAPH_BEST_PRACTICES.md) - Usage patterns, examples, and recommendations for `result_persistence`
* [Agent Forge v0.2.0 Release](https://github.com/amigo-ai/agent-forge/releases/tag/v0.2.0) - Full release notes and changes
* [Agent Forge Repository](https://github.com/amigo-ai/agent-forge) - SDK documentation and setup instructions
***
## Versioning
The Agent Forge SDK follows [Semantic Versioning](https://semver.org/) 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+ |