Change Logs

This changelog documents updates to both the Amigo API (backend services) and Agent Forge SDK (configuration management tooling).

Amigo Platform 1.0.0 (December 2025)

Amigo Platform

GPT 5.1 Available in Service Version Sets via Azure

GPT 5.1 is now available for use in Service Version Sets via Azure for experimental use. This new model option provides enhanced capabilities and fine-grained control over model behavior through configurable parameters.

What Changed

GPT 5.1 can now be selected as a model option when configuring Service Version Sets through Azure. The model exposes the following parameters for customization:

• Temperature: Controls the randomness of model outputs

• Top P: Controls diversity via nucleus sampling

• Verbosity: Controls the level of detail in model responses

• Reasoning Effort: Controls the computational effort allocated to reasoning tasks

How to Use

Configure GPT 5.1 in your Service Version Sets. Select "azure_gpt-5.1_2025_11_13" as your model option and adjust the available parameters to match your use case requirements.

Agent Forge 0.2.6 (December 3, 2025)

Version Compatibility: Compatible with Amigo API v0.6.0+.

Agent Forge

Continuation Token Type Fix

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.

Agent Forge 0.2.5 (December 2, 2025)

Version Compatibility: Compatible with Amigo API v0.6.0+.

Agent Forge

Improved Logline Formatting

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

What Changed

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

Example Output

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

How to Get It

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

Agent Forge 0.2.4 (November 28, 2025)

Version Compatibility: Compatible with Amigo API v0.6.0+.

Agent Forge

Null Field Update Fix

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

What Was Affected

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

How to Get It

1. Check out main and pull the latest changes

Verification Tip

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

Agent Forge 0.2.3 (November 24, 2025)

Version Compatibility: Compatible with Amigo API v0.6.0+.

Agent Forge SDK

Versioned Entity Rollbacks

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

How to Get It

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

2. Run poetry install to refresh dependencies.

How to Use

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

What Happens

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

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

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

Example Session

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

Why It Matters

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

Operational Notes

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

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

Agent Forge 0.2.2 (November 22, 2025)

Version Compatibility: Compatible with Amigo API v0.6.0+.

Agent Forge SDK

Automatic Tool Version Deprecation

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

What Changed:

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

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

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

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

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

How It Works:

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

1. Display the total count of active versions

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

   • Version number

   • Creation timestamp

   • Repository and lambda version

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

4. Deprecate approved versions with individual success/failure reporting

Example Output:

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

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

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

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

Action version published successfully!
New version: 1.0.9

Skipping Auto-Deprecation:

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

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

Important Notes:

• You can decline the deprecation prompt and manage versions manually

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

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

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

  • Tool-call state: The interaction will error out

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

Breaking Change:

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

Migration Guide:

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

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

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

Related Commands:

• forge action version delete - Manually deprecate specific tool versions

---

Version 0.6.1 / Agent Forge 0.2.1 (November 20, 2025)

Version Compatibility: Compatible with Agent Forge v0.2.0+.

Amigo API

ToolCallState Context Graph State Type

The API supports a ToolCallState (type: "tool-call"), which enforces execution of a designated tool call before allowing state transitions. This provides deterministic control over agent workflows where specific tools must be invoked.

Why This Matters: Previous state types (ActionState, DecisionState, ReflectionState) allowed agents to opportunistically choose whether to call tools. ToolCallState guarantees a specific tool will be called, making it ideal for required data fetches, mandatory validations, or enforced workflow checkpoints.

Key Features:

• Designated Tool Execution: Specify exactly which tool must be called using designated_tool

• Execution Guidance: Provide designated_tool_call_objective, designated_tool_call_context, designated_tool_call_guidances, and designated_tool_call_validations to control how the agent uses the tool

• Audio Support: Configure audio fillers during tool call parameter generation with designated_tool_call_params_generation_audio_fillers

• Additional Opportunistic Tools: Allow supplementary tool calls via tool_call_specs while ensuring the designated tool is always executed

• Persistence Requirement: Designated tools must use result_persistence: "persisted" (validated at Context Graph creation)

Example Configuration:

{
  "type": "tool-call",
  "name": "fetch_user_data",
  "next_state": "process_data",
  "designated_tool": {
    "tool_id": "get_user_profile",
    "version_constraint": ">=1.0.0",
    "additional_instruction": "Fetch the complete user profile",
    "result_persistence": "persisted"
  },
  "designated_tool_call_objective": "Retrieve user profile data for personalization",
  "designated_tool_call_context": "User has already authenticated and provided consent",
  "designated_tool_call_guidances": [
    "Use the user_id from the conversation context",
    "Request all profile fields including preferences"
  ],
  "designated_tool_call_validations": [
    "Verify user_id is present before calling",
    "Confirm response includes required fields: name, email, preferences"
  ],
  "designated_tool_call_params_generation_audio_fillers": [
    "Let me look up your information...",
    "Retrieving your profile..."
  ],
  "designated_tool_call_params_generation_audio_filler_triggered_after": 2.0,
  "tool_call_specs": []
}

Use Cases:

Use Case	Why Use ToolCallState
Required data fetches	Ensure critical data is loaded before proceeding
Mandatory compliance checks	Guarantee validation steps are never skipped
Workflow checkpoints	Enforce specific actions at defined workflow stages
Authentication/authorization	Ensure security checks are always performed

Related Documentation:

• Context Graph State Types - Overview of all state types

Python 3.14 Requirement for Tools

The platform now requires Python 3.14 for all new tools and tool versions. This aligns tool development with the backend runtime environment upgrade completed in early November 2025.

What Changed:

• All new tools must specify requires-python = ">=3.14" in their pyproject.toml

• Ruff configuration must target Python 3.14: target-version = "py314"

• Existing deployed tools continue to function without modification

Who This Affects:

• ✅ Action Required: Developers creating new tools or publishing new tool versions

• ⚠️ No Action Required: Existing deployed tools and tool versions

Migration Guide:

Update your tool's pyproject.toml file before publishing new versions:

[project]
name = "my-tool"
version = "1.0.0"
requires-python = ">=3.14"  # Updated from >=3.13
# ... other settings

[tool.ruff]
target-version = "py314"  # Updated from py313

Benefits:

• Access to Python 3.14's performance improvements and new language features

• Consistent runtime environment between tool development and execution

• Better type checking and static analysis capabilities

Agent Forge SDK

ToolCallState Schema Support

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

---

Version 0.6.0 / Agent Forge 0.2.0 (November 13, 2025)

Version Compatibility: API v0.6.0 requires Agent Forge v0.2.0 or later for Context Graph management. Existing deployed agents remain unaffected.

Amigo API

Tool Call Result Persistence Implementation

The result_persistence property gives you fine-grained control over tool call result visibility across agent interactions. This addresses the challenge of balancing context retention (persisting results for future reference) with performance (avoiding bloat from large outputs).

Why This Matters: Previously, all tool results were persisted regardless of size or relevance, leading to oversized conversation logs and degraded agent performance. Now you can optimize for your use case.

What Changed

Persistence Behavior

Tool call result persistence is now controlled by the result_persistence property, which accepts three modes:

Mode	Output Storage	Character Limit	Error on Exceed
"ephemeral"	Not persisted (only visible in current LLM interaction)	20,000	No
"persisted-preferred"	Persisted if ≤ 5,000 characters, otherwise ephemeral	20,000	No
"persisted"	Always persisted if ≤ 5,000 characters	5,000	Yes

Breaking Changes (Effective November 13, 2025)

• Required field: result_persistence must be explicitly specified (previously had a default value of "persisted")

• Validation enforcement: API requests without this field will fail with a 400 Bad Request error

• Size validation: Tool call results exceeding character limits will now fail for "persisted" mode (previously succeeded with truncation)

Validation Rules

• Designated tools in ToolCallState must use result_persistence: "persisted" (validation enforced at Context Graph creation)

Migration Notes

Required Action All tool call specifications in Context Graph definitions must now explicitly specify the result_persistence property. Configurations missing this field will be rejected.

Recommended Values

• Use "persisted-preferred" for most tools (provides graceful handling of large outputs)

• Use "ephemeral" for large datasets, file contents, or verbose debugging information

• Use "persisted" for critical context where outputs must always be available to the agent

Related Documentation

See the Tool Result Persistence section in the Developer Guide for detailed configuration examples and best practices.

Agent Forge SDK

Tool Call Result Persistence Configuration

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

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

Use Cases:

Use Case	Recommended Mode	Why
General-purpose tools	"persisted-preferred"	Gracefully handles large outputs
Database queries, file reads	"ephemeral"	Results too large to persist efficiently
Critical decision data	"persisted"	Must always be available to agent

Before & After

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

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

After (v0.2.0) - Field required:

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

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 persistence behavior table in the API section above.

Who This Affects

✅ Requires Action:

• Developers creating new Context Graphs

• Developers modifying existing Context Graphs

• CI/CD pipelines that deploy Context Graph configurations

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

⚠️ No Action Needed:

• Already-deployed agents (backward compatible)

• Users only reading Context Graphs

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

Migration Guide

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

Option 1: Re-sync from Remote (Recommended)

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

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

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

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

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

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

Option 2: Manual Update

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

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

2. Find all tool call specification objects

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

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

Validation: After migration, verify your changes:

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

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

Troubleshooting

Error: "result_persistence field is required"

• Cause: Context Graph definition missing the result_persistence field

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

Error: "Field required" when syncing to remote

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

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

Unexpected diffs when running forge sync-to-remote

• Cause: Local files still use old schema without result_persistence

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

Getting 400 errors when deploying Context Graphs

• Cause: API now enforces result_persistence as required

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

Related Resources

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

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

• Agent Forge Repository - SDK documentation and setup instructions

---

Versioning

Both the Amigo API and Agent Forge SDK follow Semantic Versioning with the format MAJOR.MINOR.PATCH:

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

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

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

Current Versions

Product	Version	Stage	Compatibility
Amigo API	v0.6.x	Halfway to v1.0 GA	Requires Agent Forge v0.2.0+
Agent Forge SDK	v0.2.x	Early release	Compatible with API v0.6.0+

Version Alignment

Why different version numbers? The API and SDK evolve at different paces:

• API versions reflect backend feature maturity and breaking changes

• SDK versions track tooling capabilities and schema support

• Compatibility is maintained across reasonable version ranges

Compatibility Policy:

• Agent Forge v0.2.x supports API v0.6.0+

• Always use the latest SDK version for the best experience with new API features

• Backward compatibility for deployed agents is maintained even during breaking changes

Version 1.0 Targets

v1.0 releases are expected when:

• Core API surface is stable with comprehensive testing

• Production deployments have validated the architecture

• Breaking change frequency has decreased significantly

• Feature set is considered complete for general availability

The API and SDK will reach v1.0 independently based on their maturity timelines.