Ctrlk
Go to website
For the complete documentation index, see llms.txt. This page is also available as Markdown.

SDK Ecosystem

Release history for Amigo TypeScript, Python, and Platform SDKs. New resources, breaking changes, and type safety updates.

Release history keyed by package version. See the package version snapshot before upgrading; a version mentioned in an older entry is not a statement of the current release. SDK helpers and the live API schema can change on different schedules.

September 2026 Package Maintenance

Publications verified September 8, 2026 (UTC). These client changes do not add server capabilities or establish that an integration is provisioned.

Package
Release
Changes and upgrade action

Classic TypeScript @amigo-ai/sdk

2.1.0

Exports the six existing resource classes and VoiceData type so they appear in the generated API reference. Existing client methods are unchanged; retain the 2.0 migration checks below when upgrading from 1.x.

Classic Python amigo-sdk

2.0.1

Refreshes dependencies and removes broken development-command entry points from the wheel. Contributors run the documented scripts from a source checkout; SDK sync and async methods are unchanged.

Platform TypeScript @amigo-ai/platform-sdk

0.108.1

Fixes device-login URL normalization and refreshes dependencies and setup guidance. The 0.108.0 contract changes below still apply when upgrading from older packages.

Scribe TypeScript @amigo-ai/scribe-typescript-sdk

0.14.0

Refreshes generated contracts, including provider-settings types, and fixes URL normalization. Recompile schema consumers. The guide now documents the shipped ScribeRecorder, fixed session mode, visit-template prerequisites, and backend authorization checks.

Forge MCP @amigo-ai/forge-tools

0.1.14

Updates dependencies and publishing, and declares its Node.js 18+ runtime. This remains an experimental Classic API tool; use a designated test organization for mutating workflows.

Scribe is an ESM-only package for separately provisioned provider workflows. Backend provider credentials and browser attach tickets have different roles; follow the Scribe guide before making requests or recording audio.

September 2026 Compatibility Releases

All three package publications verified September 8, 2026 (UTC). These changes update client contracts; they do not introduce new server capabilities or certify a deployment.

Package
Release
Compatibility change

Classic TypeScript @amigo-ai/sdk

2.0.0

Refreshes the generated model-identifier enum and canonical message-type defaults. Recompile code that uses generated model identifiers; obsolete values are no longer accepted by the types. This release begins the stable Classic 2.x line.

Classic Python amigo-sdk

2.0.0

Refreshes request and response models, including metric creation's initial-version payload and version responses that no longer require an ID. Generated fields and model names can change; retest imports, construction, and parsing. Optional legacy organization-branding attributes remain compatible.

Platform TypeScript @amigo-ai/platform-sdk

0.108.0

sessions.getFleetStatus() reports voice capacity. The unsupported options argument is removed, and older JavaScript calls supplying options fail before transport. Omit the argument for voice capacity; this response cannot establish separate tool-runner capacity.

Platform 0.108.0 also includes contract changes since the published 0.107.0 package:

  • Remove client.agentDefinitions calls. client.agentRuns retains harnessContext(); its create() and get() methods are removed. Use client.runs for the current run inventory and detail surface.

  • Replace recordings.getUrls(), getMetadata(), and download() integrations with recordings.get(callSid) and review its returned URLs. A returned URL does not establish that the recording object is ready.

  • Remove operators.getAccessToken() and runs.accessToken() calls for retired browser voice takeover. Review the current operator handoff workflow.

  • Remove simulations.bridge.plan() calls; bridge.run() remains an executing operation and is not a dry-run replacement.

  • Recompile against the refreshed generated types and voice-provider constants; do not assume a previously accepted configuration value is still supported.

Install and pin the package for the correct API family. A refreshed schema snapshot does not prove every helper or every deployed workflow is compatible. Use Current Upgrade Guidance to select representative application checks.

Platform SDK

Platform TypeScript v0.107.0 - Schema Alignment (August 11, 2026)

Schema Alignment

The published package refreshes its generated request and response types against the Platform API contract used for this release. Recompile integrations after upgrading and review changed types at the resources you use. This version does not imply that every later server change is already represented by an SDK helper.

Platform TypeScript v0.106.0 - Retired Intake-Link and Environment Wrappers (August 7, 2026)

Retired Intake-Link and Environment Wrappers

This version removes wrappers for retired upload-link and environment-settings endpoints and refreshes the generated types. Remove calls to those helpers. For current dataset submission, follow Customer Data Intake; the upload-link migration note explains the retired path.

Platform TypeScript v0.105.0 - Billing Resource Retirement (August 4, 2026)

Billing Resource Retirement

This version removes the SDK billing resource while restoring schema/type synchronization. Remove dependencies on those SDK wrappers rather than assuming they remain available after an upgrade.

@amigo-ai/platform-sdk 0.104.0 (July 2026)

@amigo-ai/platform-sdk 0.104.0

What changed:

  • Async audit exports. audit.createExport() now returns a statement handle instead of a synchronous result. Poll with audit.getExport(statementId) until the status is ready, then use the presigned download links in the response chunks. The previous audit.listExports() method has been removed.

  • Personal audit trail. audit.listMyAuditEvents() returns the authenticated caller's own audit events across all workspaces. This replaces the previous identity-service self-audit endpoint.

  • Audit event schema changes. The actor_email field has been removed from audit events. The acting entity is now identified by actor_entity_id. The credential_id field has been renamed to actor_credential_id. The metadata field is now nullable.

  • Use case management removed. The useCases namespace (list, getServiceBinding, bindToService, unbindFromService) has been removed from the SDK.

  • Paginated response type names. Several paginated list response types have been renamed to follow a consistent {Resource}ListResponse pattern (e.g., triggers, surfaces, external write proposals).

What you need to do:

  • Update audit export integrations. Replace synchronous export calls with the submit-poll-download pattern. Remove any code that calls audit.listExports().

  • Update audit event parsing. Replace references to actor_email with actor_entity_id, credential_id with actor_credential_id, and handle nullable metadata.

  • Remove use case management code. If your integration managed use cases through the SDK, those operations are no longer available in this version.

Platform TypeScript v0.101.0 - v0.102.1 - Unified Runs and Framework Labels (July 2026)

Unified Runs and Framework Labels

The SDK now exposes the channel-neutral Runs API and removes wrappers for list endpoints retired in favor of that unified surface.

What changed:

  • New client.runs resource. list() covers conversation and framework runs with multi-value kind, channel, and status filters. summary() returns aggregate counts with multi-value kind and channel filters. get() resolves a single run by run_id, while trajectory() returns ordered framework-run steps.

  • Run-scoped operator methods. sendGuidance(), takeOver(), handBack(), switchMode(), and accessToken() expose operator controls through the same channel-neutral run identifier.

  • Retired list wrappers removed in v0.102.0. client.conversations.list() and client.calls.getActiveIntelligence() are no longer available because their API endpoints were retired. Conversation creation, detail, turn, and call-detail methods remain available.

  • Framework constants added in v0.102.1. AGENT_RUN_FRAMEWORKS, AgentRunFramework, and AGENT_RUN_FRAMEWORK_LABELS provide stable identifiers and display labels for the supported framework runtimes.

What you need to do:

  • Move list views to client.runs. Replace conversation-only listing and active-call intelligence reads with the unified runs resource and filter by kind, channel, or status as needed.

  • No action required for framework labels. The new constants are additive.

Platform TypeScript v0.98.1 - v0.100.0 - Binary Intake Downloads and Type Refreshes (July 2026)

Binary Intake Downloads and Type Refreshes

Intake upload downloads now preserve the endpoint's binary response, and upload listings expose the API's pagination controls. The following two releases refresh generated API types without changing the hand-authored resource interface.

What changed:

  • client.intake.links.downloadUpload() returns a Blob in v0.98.1. The method no longer attempts to decode uploaded files as JSON, so binary content and its content type are preserved.

  • Upload listing pagination. client.intake.links.listUploads() accepts the generated limit and offset query parameters so callers can retrieve uploads beyond the first page.

  • Generated types refreshed in v0.99.0 and v0.100.0. These releases synchronize the package with newer Platform API contracts.

What you need to do:

  • Upgrade to v0.98.1 or later when downloading intake uploads. Treat the result as a Blob rather than a JSON response object.

Platform TypeScript v0.97.0 - v0.98.0 - Simulation Fork, Score, and Promote Methods (July 2026)

Simulation Fork, Score, and Promote Methods

Three typed methods cover the interactive-to-coverage simulation workflow.

What changed:

  • simulations.forkSession(sessionId, body). Clones a coverage-bound session at its current turn and steps the supplied alternative caller utterances.

  • simulations.scoreSession(sessionId, body). Assigns a score and optional rationale to a completed simulation session.

  • simulations.promoteSession(sessionId). Promotes a run-less interactive session into a coverage run so it can be forked and scored. The operation is idempotent and reports when the session was already bound.

What you need to do:

  • Upgrade to v0.98.0 or later to use the full promote, fork, and score workflow.

Platform TypeScript v0.95.0 - Trigger Filters, Fire Inputs, and Surface Analytics Parameters (July 2026)

Trigger Filters, Fire Inputs, and Surface Analytics Parameters

Trigger and surface-analytics wrappers now forward the full public query and request options defined by the API.

What changed:

  • Trigger status filtering. triggers.list() and listAutoPaging() accept the generated trigger query parameters, including is_active.

  • Per-fire input overrides. triggers.fire(triggerId, body?) accepts optional input values that are merged with the trigger's configured input template.

  • Expanded surface analytics filters. Completion rate, channel effectiveness, and field abandonment methods accept lookback and date-range filters. Completion rate also accepts interval and entity filters, while entity history accepts a result limit.

  • New exported parameter types. ListTriggersParams, FireTriggerRequest, and the surface-analytics parameter types are available from the package root.

What you need to do:

  • No action required. Existing calls remain valid; pass the new optional parameters when you need narrower results or per-run trigger input.

Platform TypeScript v0.93.0 - v0.94.0 - Voice Session Provider Model Families (July 2026)

Voice Session Provider Model Families

Updates the generated types for the voice session_provider field to the new model-family values. v0.93.0 contained only routine generated-type updates.

What changed:

  • session_provider values are now model families. The generated voice configuration types accept amigo, gpt_realtime, and gpt_live. The previous values inhouse, openai_realtime, and atlas are no longer part of the types: inhouse is now amigo, and openai_realtime/atlas are now gpt_realtime.

  • New gpt_live family. The full-duplex speech-to-speech model family is available in the types alongside amigo and gpt_realtime.

What you need to do:

  • Update code that sets or switches on session_provider. The old string values no longer type-check against v0.94.0. Replace inhouse with amigo, and openai_realtime or atlas with gpt_realtime.

Platform TypeScript v0.91.0 - v0.92.0 - Conversation Channel Switching, Review-Queue Removal (July 2026)

Conversation Channel Switching, Review-Queue Removal

Adds a typed wrapper for moving a conversation to a different channel, and removes the review-queue surface and a voice-settings field. Intermediate releases not listed on this page (v0.84.0 - v0.87.0 and v0.89.0 - v0.91.0) contained only routine updates to the generated API types.

What changed:

  • conversations.switchChannel(conversationId, request). Moves a conversation to a different channel (for example web → sms or imessage). recipient (E.164) is required when switching to sms/imessage; passing dispatch_opener: true has the agent immediately send one turn on the new channel, optionally steered by instruction. Returns the updated ConversationDetail.

  • New type exports: ChannelKind and SwitchChannelRequest.

  • Removed the review-queue resource. client.reviewQueue (ReviewQueueResource) and the review-queue types are no longer part of the SDK.

  • Removed correction_categories from the voice-settings types.

What you need to do:

  • The channel-switching additions are backward compatible. The removals are breaking: code referencing client.reviewQueue, the review-queue types, or correction_categories no longer compiles against v0.92.0.

Platform TypeScript v0.87.0 - v0.88.0 - Agent Runs and Agent Definitions (July 2026)

Agent Runs and Agent Definitions

Adds two resources for framework agents: launching and polling agent runs, and a registry for native agent definitions.

What changed:

  • client.agentRuns: create() launches an agent run (non-blocking; returns a run_id to poll), get() fetches a run snapshot (status, final text, trajectory, and token usage), and harnessContext() fetches the framework-neutral session context (identity/instructions, world scope, tool descriptors, guardrails, and runtime) for a service and version set.

  • client.agentDefinitions: registry for native (bring-your-own) agent definitions: list() / listAutoPaging() (filterable by framework and archived state), register() (idempotent: re-pushing an identical body reports created: false; a changed body mints a new immutable version), validate() (dry-run validation; nothing is stored), get(), getVersion(), and archive().

What you need to do:

  • No action required. The new resources are additive; upgrade to ≥ v0.88.0 to use them.

Platform TypeScript v0.85.0 - v0.85.1 - Use Cases Resource (July 2026)

Use Cases Resource

Adds client.useCases for channel use cases: listing, workspace ownership, and the service binding that routes a use case's traffic.

What changed:

  • client.useCases: list() (optionally filtered by entity/channel/setup), listOwned(), getOwnership() / assignOwnership() / releaseOwnership() for workspace ownership of a use case, and getServiceBinding() / bindToService() / unbindFromService() for binding a use case to the service that handles its traffic.

  • New exports: UseCasesResource plus the UseCase, UseCaseListResponse, OwnedUseCasesResponse, UseCaseOwnership, UseCaseServiceBinding, BindUseCaseServiceRequest, and ListUseCasesParams types.

What you need to do:

  • No action required. The new resource is additive; upgrade to ≥ v0.85.1 to use it.

Platform TypeScript v0.83.0 - Session Fleet Status (July 2026)

Session Fleet Status

Adds operator visibility into live session fleet capacity.

What changed:

  • sessions.getFleetStatus(opts?): returns live, workspace-global session fleet capacity: ready and allocated server counts plus remaining headroom, typed as FleetStatusResponse. The optional fleet option selects "voice" (the server default) or "tool-runner".

What you need to do:

  • No action required. The new method is additive; upgrade to ≥ v0.83.0 to use it.

Platform TypeScript v0.81.0 - v0.82.0 - Lifecycle Axis Types, Channels Resource Removed (June 2026)

Lifecycle Axis Types, Channels Resource Removed

v0.81.0 adds the lifecycle dispatch axis (coupled | independent) to the generated ToolCallSpec type, alongside execution and delivery, tracking the Platform API addition. v0.82.0 removes the channels resource.

What changed:

  • lifecycle?: "coupled" | "independent" on ToolCallSpec (v0.81.0). Surfaced on every place a tool binding appears (action_tool_call_specs, exit_condition_tool_call_specs, tool_call_specs). Optional and additive; existing code compiles unchanged.

  • Removed the channels resource (v0.82.0). client.channels.sesSetup, the ChannelsResource / SesSetupResource classes, and the CreateSesSetupRequest, DnsRecord, and SesSetupDetail types were removed, matching the removal of the SES email-channel setup endpoints from the Platform API.

What you need to do:

  • The lifecycle axis is additive; bindings left at the default (independent) need no code change.

  • The channels removal is a breaking change: code referencing client.channels or the SES setup types no longer compiles against v0.82.0.

Classic SDKs

Historical entries below identify the TypeScript and Python versions that shipped each change. For the current packages, see the package snapshot. The September compatibility releases retain the major upgrade guidance.

Use the current package snapshot when installing Classic TypeScript. The accidental 1.1.x publications remain deprecated. Use @amigo-ai/sdk for the Classic API and @amigo-ai/platform-sdk for the Platform API.

Classic TypeScript v1.0.0 / Python v1.3.1 - General Availability (March-April 2026)

General Availability

What changed:

  • The Classic TypeScript SDK reached general availability at v1.0.0, stabilizing the API surface introduced in the v1.0.0-rc.2 release candidate.

  • The Classic Python SDK's first 1.x release was v1.1.0 (no v1.0.0 or release candidate was published for Python); subsequent point releases through v1.3.1 refined the resource layer and type coverage.

What you need to do:

  • Upgrade to the GA packages:

Classic TypeScript v1.0.0-rc.2 - New Resources, Breaking Changes, Branded Types (April 2026)

New Resources, Breaking Changes, Branded Types

Release candidate for the TypeScript SDK. The matching Python SDK changes shipped in Python v1.1.0 (no Python release candidate was published). Adds full CRUD for Agents, Context Graphs, and extended Services. Includes breaking changes to error handling, resource naming, and method signatures.

Breaking changes: TypeScript - errors namespace removed, positional params replaced with options objects. Python - PermissionError renamed to ForbiddenError, resource properties are now plural (client.conversation to client.conversations).

What changed:

AgentResource - Full CRUD for agents and agent versions:

  • createAgent / create_agent - Create a new agent definition

  • getAgents / get_agents - List agents with pagination

  • deleteAgent / delete_agent - Deprecate an agent

  • createAgentVersion / create_agent_version - Create a new agent version (supports dry run)

  • getAgentVersions / get_agent_versions - List agent version history

ContextGraphResource - Full CRUD for context graphs and versions:

  • createContextGraph / create_context_graph - Create a context graph

  • getContextGraphs / get_context_graphs - List context graphs with pagination

  • deleteContextGraph / delete_context_graph - Deprecate a context graph

  • createContextGraphVersion / create_context_graph_version - Create a version (supports dry run)

  • getContextGraphVersions / get_context_graph_versions - List version history

ServiceResource extended:

  • createService / create_service - Create a new service

  • updateService / update_service - Update a service

  • upsertVersionSet / upsert_version_set - Create or update version sets (release, staging, dev)

  • deleteVersionSet / delete_version_set - Remove a version set

New Branded Types (TypeScript): AgentId, ToolId, DynamicBehaviorSetId, MetricId, SimulationPersonaId, SimulationScenarioId, SimulationUnitTestId, SimulationUnitTestSetId, WebhookDestinationId, RoleId, ApiKeyId

Other changes:

  • TypeScript: AmigoError constructor now correctly maps statusCode/errorCode via Object.assign (was silently dropping fields)

  • Python: AmigoConfig and all error classes exported from __init__.py

  • Python: scripts/ removed from wheel distribution; license and URLs added to pyproject.toml

What you need to do:

Install the release candidate; the sections below detail the breaking changes:

TypeScript SDK

Removed errors namespace - Import error classes individually.

Impact

High

Action Required

Yes

Options objects replace positional parameters - Conversation and user methods now take options objects.

Impact

High

Action Required

Yes

UserResource.get() renamed to getModel()

Impact

Low

Action Required

If using UserResource.get()

Minimum Node.js version: engines.node >= 18 is now enforced in package.json. Removed rollup optional dependency.

Python SDK

PermissionError renamed to ForbiddenError - Avoids shadowing the Python builtin.

Impact

High

Action Required

Yes

Sync aclose() renamed to close() - Standard naming for sync context manager cleanup.

Impact

Medium

Action Required

If using sync client

Plural resource properties - Resource accessors are now plural.

Impact

High

Action Required

Yes

v0.5.0 - Webhook Type Safety, Rate Limit Headers, Cross-SDK Integration Tests (March 3, 2026)

Webhook Type Safety, Rate Limit Headers, Cross-SDK Integration Tests

Adds typed webhook event parsing with signature verification, rate limit header utilities, and a cross-SDK integration test suite.

What changed:

Webhook Type Safety:

  • Typed interfaces/dataclasses for all webhook event types

  • parseWebhookEvent() / parse_webhook_event() with HMAC-SHA256 signature verification

  • Replay attack protection via configurable max age

  • Exported from package root

Rate Limit Header Exposure:

  • RateLimitInfo type with limit, remaining, reset fields

  • parseRateLimitHeaders() / parse_rate_limit_headers() utility

  • Parses X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset headers

Cross-SDK Integration Tests:

  • End-to-end test: Python creates user, TypeScript creates conversation, Python interacts, TypeScript gets messages, Python finishes

What you need to do:

  • No breaking changes. Upgrade to pick up the new utilities:

v0.4.0 - Branded ID Types, Convenience Aliases, Type Safety (February 24, 2026)

Branded ID Types, Convenience Aliases, Type Safety

Introduces compile-time ID type safety for TypeScript, convenience method aliases, and PEP 561 compliance for Python.

What changed:

Branded ID Types (TypeScript) - All ID parameters now use branded string types to prevent accidental ID swaps at compile time.

Available types: ConversationId, MessageId, UserId, OrgId, InteractionId, ServiceId

Convenience Aliases - Resource methods now include shorter aliases for common operations:

Type Safety (Python):

  • PEP 561 compliance: py.typed marker added for downstream type checking

  • Explicit model exports replace wildcard barrel import in models.py

  • InteractionInput TypedDict groups the 9+ parameters of interact_with_conversation() for cleaner call sites

  • Streaming types tightened from dict[str, Any] to proper TypedDict

Security:

  • TypeScript: Error serialization sanitized to prevent bearer token leakage in logs. All 7 npm audit vulnerabilities resolved.

  • Python: Response bodies in exceptions truncated to 500 chars and sanitized (token/key/secret fields stripped)

What you need to do:

  • No breaking changes. Upgrade to pick up the type safety and security improvements:

Version Compatibility

Use the dated current SDK package snapshot for installable versions. SDK versions and API versions are separate; validate the operations and generated models your application uses against its deployment.

SDK
API family
Runtime

Platform TypeScript SDK

Platform API

Node 20+

Classic TypeScript SDK

Classic API

Node 18+

Classic Python SDK

Classic API

Python 3.11+

Scribe TypeScript SDK

Scribe provider API

Node 20+; ESM-only; browser capture requires supported Web APIs

PreviousWeb Platform History: Archive 6
NextAgent Forge CLI

Last updated

Was this helpful?