Amigo API

Release history for the Amigo API (backend services).

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

---

v0.7.0 - Permission System & Voice Configuration (January 30, 2026)

Temporary Permission Grants

Grant time-limited permissions to users without modifying their role. Temporary grants automatically expire, ideal for support escalations or temporary elevated privileges.

New Endpoints:

Endpoint	Method	Description
/v1/{org}/role/temporary_permission_grant/	POST	Create a temporary permission grant
/v1/{org}/role/temporary_permission_grants/	GET	List and filter temporary permission grants

Key Features:

• Duration Control: Grants last from 1 minute to 3 days (ISO8601 duration format)

• Tags & Justification: Attach metadata tags and require justification for audit trails

• Filtering: Query grants by user, permission, creator, expiration status, and tags

• Permission Validation: Creator must have greater privileges than the grant being issued

Example Request (Create Grant):

POST /v1/{org}/role/temporary_permission_grant/
{
  "user_id": "support-agent-123",
  "duration": "PT2H",
  "permission_grant": {
    "permission_name": "Conversation:GetConversation",
    "conditions": {}
  },
  "tags": {"reason": "support_ticket", "ticket_id": "TICKET-456"},
  "justification": "Support agent needs access to review customer conversation for ticket TICKET-456"
}

New Permissions:

• Role:CreateTemporaryPermissionGrant - Required to create grants

• Role:GetTemporaryPermissionGrant - Controls which grants are visible in list queries

Conversation Tags

Tag conversations with key-value metadata for organization, filtering, and analytics.

New Capabilities:

• Create with Tags: Pass tags object when creating conversations

• Filter by Tags: Use tags query parameter in GetConversations

• Modify Tags: New POST /{conversation_id}/tags/ endpoint for adding, updating, and removing tags

Tag Constraints:

• Maximum 20 tags per conversation

• Keys and values: alphanumeric characters, underscores, and spaces only

• Values can be null for flag-style tags

Example (Modify Tags):

POST /v1/{org}/conversation/{conversation_id}/tags/
{
  "updates": {"department": "sales", "priority": "high"},
  "deletes": ["old_tag"]
}

Change Tool Candidates Dynamic Behavior Action

Dynamic behaviors now support the change-tool-candidates action type, allowing you to dynamically modify available tools based on conversation context.

Example Configuration:

{
  "action": {
    "type": "change-tool-candidates",
    "tool_specs": [
      {
        "tool_id": "payment_processor",
        "version_constraint": ">=2.0.0"
      }
    ]
  }
}

SSML Tag Support

Audio fillers now support Speech Synthesis Markup Language (SSML) tags for fine-grained control over speech output in voice conversations.

Supported Tags:

• <prosody> - Control rate (0.6-1.5), volume (0.5-2.0)

• <break> - Insert pauses (e.g., time="500ms")

• <emotion> - Apply emotional tone

Constraints: Audio fillers must be under 512 characters including SSML markup.

Arabic Language Support

Added arabic to supported voice languages for voice-enabled conversations.

API Key Names

API keys now support a name field for easier identification and management.

Breaking Change: The name parameter is now required when calling CreateAPIKey. Previously, a default name was generated automatically.

Migration:

// Before (worked with default)
POST /v1/{org}/api_key/
{}

// After (name required)
POST /v1/{org}/api_key/
{
  "name": "Production Backend Key"
}

Keyterms Field

The keyterms field has been added to GetService and GetUser responses, providing extracted key terminology for context-aware interactions.

New Permission: FinishConversation

Added Conversation:FinishConversation permission for granular control over who can end conversations programmatically.

---

Breaking Changes

Voice Configuration Simplified

Impact: High | Action Required: Yes

Voice configuration has been simplified. Legacy voice configuration fields have been removed.

What Changed:

• Legacy fields removed from VoiceConfig: stability, similarity_boost, style

• Agent voice_config now only requires voice_id

Migration:

// Updated voice_config format
"voice_config": {
  "voice_id": "your-voice-id"
}

1. Remove stability, similarity_boost, and style fields from voice configurations

2. Test voice output quality with the updated configuration

Deny Permission Grants Removed

Impact: High | Action Required: If using deny grants

The "deny" grant type has been removed from the permission system. Permissions now follow an allow-only model.

What Changed:

• grant_type: "deny" is no longer valid in role permission grants

• Existing deny grants will be ignored

• Permission checks use allow-only logic

Migration: Restructure role permissions to achieve the same access control using allow grants only. Consider using more specific conditions instead of broad allows with selective denies.

Role Inheritance Removed

Impact: Medium | Action Required: If using role inheritance

Roles no longer support inheritance from parent roles. Each role must define its complete permission set.

What Changed:

• parent_role field removed from role schema

• CreateRole and ModifyRole no longer accept parent role references

• Permissions are not inherited from other roles

Migration: Flatten inherited permissions directly into each role definition. Review and consolidate role hierarchies.

GetRoles Response Schema Change

Impact: Low | Action Required: If parsing permission_grants field

The backwards-compatibility permission_grants field has been removed from GetRoles responses. Use the permissions field instead.

GetOrganizationMetrics Endpoint Removed

Impact: Low | Action Required: If using this endpoint

The GET /v1/{org}/metric/organization/ endpoint has been removed.

External Event Message Field Rename

Impact: Low | Action Required: If using external events

The external_event_message fields in InteractWithConversation request bodies have been renamed for consistency. Update your request payloads to use the corrected field names.

CreateInvitedUser and UpdateUserInfo Endpoints Removed

Impact: Low | Action Required: If using these endpoints

These legacy user management endpoints have been removed:

• CreateInvitedUser → Use CreateUser endpoint instead

• UpdateUserInfo → Use ModifyUser endpoint instead

---

Deprecations

tool_repo Field

The tool_repo field is deprecated and will be removed in a future release. Use the CreateToolVersion endpoint to publish tool versions instead.

Audio Quality Adjustment

The ability to adjust voice response audio quality (bitrate) has been deprecated. The platform now automatically selects optimal audio quality settings.

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.7.x	Approaching 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+

• Agent Forge v0.3.x supports API v0.7.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