Amigo API

Release history for the Amigo API (backend services).

Current Version: v0.6.1 | Requires: Agent Forge v0.2.0+

---

v0.6.1 - ToolCallState & Python 3.14 (November 20, 2025)

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

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

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.

---

Versioning

The Amigo API follows Semantic Versioning with the format MAJOR.MINOR.PATCH:

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

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

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

Product	Version	Stage	Compatibility
Amigo API	v0.6.x	Halfway to 1.0	Requires Agent Forge v0.2.0+

Version Alignment

Why different version numbers from Agent Forge? 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 Target

v1.0 release is 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