# Alibaba Cloud OpenAgent API

> Alibaba Cloud OpenAgent API on Apizie: 12 endpoints (协作式取消 run, 创建会话, 删除会话, 读只读模式, …) returned as clean JSON through one API key. Send your own provider key in the x-upstream-key header. Call it over REST at https://zieapi.vercel.app/v1/cloud:aliyun-openagent/{endpoint} or from Claude, ChatGPT and Cursor through the Apizie MCP server. Free plan: 1,000 requests a month.

- Project key: `cloud:aliyun-openagent`
- Category: Cloud
- Status: byok
- Source: https://api.alibabacloud.com/product/openagent
- Page: https://zieapi.vercel.app/api/cloud/aliyun-openagent
- OpenAPI: https://zieapi.vercel.app/api/cloud/aliyun-openagent/openapi.json

Alibaba Cloud OpenAPI for OpenAgent (openagent, version 2026-08-01). Calls are signed with ACS3-HMAC-SHA256 using your AccessKey ID and secret.

## Endpoints

### 协作式取消 run
`POST https://zieapi.vercel.app/v1/cloud:aliyun-openagent/cancel-run` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| sessionId | string | yes | The sessionId |
| runId | string | yes | The runId |
| reason | string | no | 可选取消原因 |
| X-OpenAgent-Idempotency-Key | string | no | 可选幂等键；相同身份、键和请求摘要安全重试，摘要冲突返回 IdempotencyKey.Conflict |

### 创建会话
`POST https://zieapi.vercel.app/v1/cloud:aliyun-openagent/create-session` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| title | string | no | 会话标题 |
| X-OpenAgent-Idempotency-Key | string | no | 可选幂等键；相同身份、键和请求摘要安全重试，摘要冲突返回 IdempotencyKey.Conflict |

### 删除会话
`POST https://zieapi.vercel.app/v1/cloud:aliyun-openagent/delete-session` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| sessionId | string | yes | The sessionId |
| X-OpenAgent-Idempotency-Key | string | no | 可选幂等键；仅首次删除成功返回200，删除后的重复调用（含同键重试）返回404 Session.NotFound，不回放首次成功结果；目标尚未删除时同键不同摘要返回409 IdempotencyKey.Conflict |

### 读只读模式
`GET https://zieapi.vercel.app/v1/cloud:aliyun-openagent/get-readonly-mode` (byok)

### 查询 run 详情/终态
`GET https://zieapi.vercel.app/v1/cloud:aliyun-openagent/get-run` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| sessionId | string | yes | The sessionId |
| runId | string | yes | The runId |

### 查询会话详情
`GET https://zieapi.vercel.app/v1/cloud:aliyun-openagent/get-session` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| sessionId | string | yes | 要查询的 Session |

### 拉取可渲染历史 timeline
`GET https://zieapi.vercel.app/v1/cloud:aliyun-openagent/list-messages` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| sessionId | string | yes | The sessionId |
| runId | string | no | 仅查询指定 Run |
| maxResults | string | no | 正整数分页大小；POP 以原始 query 字符串转发，由 Gateway/Core 校验并返回标准错误结构 |
| nextToken | string | no | opaque 分页游标 |

### 查询会话列表
`GET https://zieapi.vercel.app/v1/cloud:aliyun-openagent/list-sessions` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| maxResults | string | no | 正整数分页大小；POP 以原始 query 字符串转发，由 Gateway/Core 校验并返回标准错误结构 |
| nextToken | string | no | opaque 分页游标 |

### 统一对话端点(POST→SSE,AG-UI 事件流)
`POST https://zieapi.vercel.app/v1/cloud:aliyun-openagent/send-message` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| sessionId | string | yes | The sessionId |
| content | string | no | type=MESSAGE 时必填且非空 |
| resume | array | no | type=RESUME 时必填且非空；必须覆盖全部待处理 Interrupt |
| runId | string | no | type=RECONNECT 时必填且非空 |
| type | string | no | 请求判别式；省略时为 MESSAGE |
| X-OpenAgent-Idempotency-Key | string | no | 可选幂等键；相同身份、键和请求摘要安全重试，摘要冲突返回 IdempotencyKey.Conflict |

### 写只读模式
`POST https://zieapi.vercel.app/v1/cloud:aliyun-openagent/update-readonly-mode` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| value | string | no | true/false(大小写不敏感) |

### 原子更新标题/置顶/会话 Toolset
`POST https://zieapi.vercel.app/v1/cloud:aliyun-openagent/update-session` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| sessionId | string | yes | The sessionId |
| pinned | string | no | 是否置顶；省略表示不修改 |
| title | string | no | 新标题；省略表示不修改 |
| X-OpenAgent-Idempotency-Key | string | no | 可选幂等键；相同身份、键和请求摘要安全重试，摘要冲突返回 IdempotencyKey.Conflict |

### version
`POST https://zieapi.vercel.app/v1/cloud:aliyun-openagent/version` (byok)

## Example
```
curl "https://zieapi.vercel.app/v1/cloud:aliyun-openagent/cancel-run" \
  -H "x-api-key: $APIZIE_KEY" \
  -H "x-upstream-key: $PROVIDER_KEY"
```

## FAQ

### How do I call the Alibaba Cloud OpenAgent API?
Create a free Apizie key, then send POST https://zieapi.vercel.app/v1/cloud:aliyun-openagent/cancel-run with the header x-api-key. Every endpoint returns { project, data, timestamp }.

### Is the Alibaba Cloud OpenAgent API free on Apizie?
Yes. The Free plan includes 1,000 requests a month at 100 requests a minute, no credit card. Alibaba Cloud OpenAgent itself also needs your own key from aliyuncs.com.

### Can AI agents use the Alibaba Cloud OpenAgent API?
Yes. Add the Apizie MCP server (https://zieapi.vercel.app/mcp) to Claude, ChatGPT, Cursor or VS Code, then ask in plain language. The agent calls run_scraper with project key cloud:aliyun-openagent.

### What is the status of the Alibaba Cloud OpenAgent API?
Needs your own provider key (bring your own key)