# SDK Ecosystem

Release history for the Amigo SDKs.

{% hint style="info" %}
**Three SDKs**:

* **Classic TypeScript SDK** (`@amigo-ai/sdk`): v1.1.3 - Classic API client for Node.js
* **Classic Python SDK** (`amigo-sdk`): v1.3.1 - Classic API client for Python
* **Platform TypeScript SDK** (`@amigo-ai/platform-sdk`): v0.56.0 - Platform API client for Node.js, auto-generated from OpenAPI spec
  {% endhint %}

## Classic SDKs

<details>

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

Both Classic SDKs reached general availability. The v1.0.0 release stabilizes the API surface introduced in rc.1 with CI and documentation fixes.

**Python SDK v1.1.0-v1.3.1** includes fixes for nested `ConversationEvent` unwrapping in the resource layer and integration test stability improvements.

**How to Get It**

```bash
# TypeScript
npm install @amigo-ai/sdk@1.0.0

# Python
pip install amigo-sdk==1.3.1
```

</details>

<details>

<summary>Classic v1.0.0-rc.1 - New Resources, Breaking Changes, Branded Types (March 10, 2026)</summary>

First release candidate for both SDKs. Adds full CRUD for Agents, Context Graphs, and extended Services. Includes breaking changes to error handling, resource naming, and method signatures.

{% hint style="danger" %}
**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`).
{% endhint %}

**Added**

**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`

**Breaking Changes**

**TypeScript SDK**

**Removed `errors` namespace** - Import error classes individually.

| Impact | High | Action Required | Yes |
| ------ | ---- | --------------- | --- |

```typescript
// Before
import { errors } from '@amigo-ai/sdk'
throw new errors.NotFoundError(...)

// After
import { NotFoundError } from '@amigo-ai/sdk'
throw new NotFoundError(...)
```

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

| Impact | High | Action Required | Yes |
| ------ | ---- | --------------- | --- |

```typescript
// Before
await client.conversations.getMessages(conversationId, limit, offset)

// After
await client.conversations.getMessages({ conversationId, limit, offset })
```

**`UserResource.get()` renamed to `getModel()`**

| Impact | Low | Action Required | If using `UserResource.get()` |
| ------ | --- | --------------- | ----------------------------- |

```typescript
// Before
const user = await client.users.get()

// After
const user = await client.users.getModel()
```

**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 |
| ------ | ---- | --------------- | --- |

```python
# Before
from amigo_sdk import PermissionError

# After
from amigo_sdk import ForbiddenError
```

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

| Impact | Medium | Action Required | If using sync client |
| ------ | ------ | --------------- | -------------------- |

```python
# Before
client.aclose()

# After
client.close()
```

**Plural resource properties** - Resource accessors are now plural.

| Impact | High | Action Required | Yes |
| ------ | ---- | --------------- | --- |

```python
# Before
client.organization.get()
client.service.list()
client.conversation.create(...)

# After
client.organizations.get()
client.services.list()
client.conversations.create(...)
```

**Changed**

* **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`

**How to Get It**

```bash
# TypeScript
npm install @amigo-ai/sdk@1.0.0-rc.1

# Python
pip install amigo-sdk==1.0.0rc1
```

</details>

<details>

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

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

**Added**

**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
* Runs nightly via GitHub Action

**Fixed**

* **Python**: Streaming timeout - httpx default 5s read timeout was killing streams before agent responses completed. Now uses 300s read timeout for streaming requests.

**Security**

* **Python**: Fixed `black` arbitrary file write vulnerability (Dependabot)
* **TypeScript**: Fixed `diff` DoS vulnerability in examples (Dependabot)
* **Both**: CodeQL workflow conflicts resolved

**How to Get It**

```bash
# TypeScript
npm install @amigo-ai/sdk@0.5.0

# Python
pip install amigo-sdk==0.5.0
```

</details>

<details>

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

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

**Added**

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

```typescript
import { conversationId, messageId } from '@amigo-ai/sdk'

// Compile-time error: ConversationId is not assignable to MessageId
const convId = conversationId('abc123')
const msgId = messageId('def456')
```

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

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

```typescript
// Both work - use whichever you prefer
const conversations = await client.conversations.getConversations()
const conversations = await client.conversations.list()
```

**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)

**How to Get It**

```bash
# TypeScript
npm install @amigo-ai/sdk@0.4.0

# Python
pip install amigo-sdk==0.4.0
```

</details>

## Version Compatibility

| SDK                         | Version | API Compatibility   | Runtime      |
| --------------------------- | ------- | ------------------- | ------------ |
| **Platform TypeScript SDK** | 0.56.0  | Platform API v1.0.0 | Node 18+     |
| **Classic TypeScript SDK**  | 1.1.3   | Classic API v0.7.0+ | Node 18+     |
| **Classic Python SDK**      | 1.3.1   | Classic API v0.7.0+ | Python 3.11+ |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.amigo.ai/api-reference/change-logs/sdk-ecosystem.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.