telnyx-ai-assistants-ruby

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Telnyx AI Assistants - Ruby

Telnyx AI 助手 - Ruby

Installation

安装

bash

gem install telnyx

bash

gem install telnyx

Setup

配置

ruby

require "telnyx"

client = Telnyx::Client.new(
  api_key: ENV["TELNYX_API_KEY"], # This is the default and can be omitted
)

All examples below assume

client

is already initialized as shown above.

ruby

require "telnyx"

client = Telnyx::Client.new(
  api_key: ENV["TELNYX_API_KEY"], # 这是默认配置，可以省略
)

以下所有示例均假设

client

已按上述方式完成初始化。

Error Handling

错误处理

All API calls can fail with network errors, rate limits (429), validation errors (422), or authentication errors (401). Always handle errors in production code:

ruby

assistant = client.ai.assistants.create(instructions: "You are a helpful assistant.", model: "openai/gpt-4o", name: "my-resource")
puts(assistant)

Common error codes:

invalid API key,

insufficient permissions,

resource not found,

validation error (check field formats),

rate limited (retry with exponential backoff).

所有API调用都可能因网络错误、速率限制(429)、校验错误(422)或认证错误(401)而失败。在生产代码中请务必做好错误处理：

ruby

assistant = client.ai.assistants.create(instructions: "You are a helpful assistant.", model: "openai/gpt-4o", name: "my-resource")
puts(assistant)

常见错误码：

API密钥无效，

权限不足，

资源未找到，

校验错误（请检查字段格式），

触发速率限制（请使用指数退避策略重试）。

Important Notes

重要注意事项

Phone numbers must be in E.164 format (e.g.,
```
+13125550001
```
). Include the
```
+
```
prefix and country code. No spaces, dashes, or parentheses.

Pagination: Use

.auto_paging_each

for automatic iteration:

page.auto_paging_each { |item| puts item.id }

电话号码必须为E.164格式（例如：
```
+13125550001
```
），需包含
```
+
```
前缀和国家代码，不允许有空格、短横线或括号。

分页： 使用

.auto_paging_each

实现自动遍历：

page.auto_paging_each { |item| puts item.id }

。

Reference Use Rules

参考使用规则

Do not invent Telnyx parameters, enums, response fields, or webhook fields.

If the parameter, enum, or response field you need is not shown inline in this skill, read references/api-details.md before writing code.
Before using any operation in
```
## Additional Operations
```
, read the optional-parameters section and the response-schemas section.

请勿自行杜撰Telnyx的参数、枚举值、响应字段或webhook字段。

如果你需要的参数、枚举或响应字段未在本skill的示例中列出，请在编写代码前查阅references/api-details.md。
在使用
```
## 额外操作
```
中的任意接口前，请先阅读可选参数章节和响应 schema 章节。

Core Tasks

核心任务

Create an assistant

创建助手

Assistant creation is the entrypoint for any AI assistant integration. Agents need the exact creation method and the top-level fields returned by the SDK.

client.ai.assistants.create()

—

POST /ai/assistants

Parameter	Type	Required	Description
`name`	string	Yes
`model`	string	Yes	ID of the model to use.
`instructions`	string	Yes	System instructions for the assistant.
`tools`	array[object]	No	The tools that the assistant can use.
`tool_ids`	array[string]	No
`description`	string	No
...			+12 optional params in references/api-details.md

ruby

assistant = client.ai.assistants.create(instructions: "You are a helpful assistant.", model: "openai/gpt-4o", name: "my-resource")

puts(assistant)

Primary response fields:

```
assistant.id
```
```
assistant.name
```
```
assistant.model
```
```
assistant.instructions
```
```
assistant.created_at
```
```
assistant.description
```

创建助手是所有AI助手集成的入口。Agents需要准确的创建方法以及SDK返回的顶层字段。

client.ai.assistants.create()

—

POST /ai/assistants

参数	类型	必填	描述
`name`	string	是
`model`	string	是	要使用的模型ID
`instructions`	string	是	给助手的系统指令
`tools`	array[object]	否	助手可以使用的工具列表
`tool_ids`	array[string]	否
`description`	string	否
...			另有12个可选参数见references/api-details.md

ruby

assistant = client.ai.assistants.create(instructions: "You are a helpful assistant.", model: "openai/gpt-4o", name: "my-resource")

puts(assistant)

主要响应字段：

```
assistant.id
```
```
assistant.name
```
```
assistant.model
```
```
assistant.instructions
```
```
assistant.created_at
```
```
assistant.description
```

Chat with an assistant

与助手对话

Chat is the primary runtime path. Agents need the exact assistant method and the response content field.

client.ai.assistants.chat()

—

POST /ai/assistants/{assistant_id}/chat

Parameter	Type	Required	Description
`content`	string	Yes	The message content sent by the client to the assistant
`conversation_id`	string (UUID)	Yes	A unique identifier for the conversation thread, used to mai...
`assistant_id`	string (UUID)	Yes
`name`	string	No	The optional display name of the user sending the message

ruby

response = client.ai.assistants.chat(
  "assistant_id",
  content: "Tell me a joke about cats",
  conversation_id: "42b20469-1215-4a9a-8964-c36f66b406f4"
)

puts(response)

Primary response fields:

```
response.content
```

对话是主要的运行时路径。Agents需要准确的助手调用方法以及响应的内容字段。

client.ai.assistants.chat()

—

POST /ai/assistants/{assistant_id}/chat

参数	类型	必填	描述
`content`	string	是	客户端发送给助手的消息内容
`conversation_id`	string (UUID)	是	会话线程的唯一标识符，用于维护上下文...
`assistant_id`	string (UUID)	是
`name`	string	否	发送消息的用户的可选显示名称

ruby

response = client.ai.assistants.chat(
  "assistant_id",
  content: "Tell me a joke about cats",
  conversation_id: "42b20469-1215-4a9a-8964-c36f66b406f4"
)

puts(response)

主要响应字段：

```
response.content
```

Create an assistant test

创建助手测试

Test creation is the main validation path for production assistant behavior before deployment.

client.ai.assistants.tests.create()

—

POST /ai/assistants/tests

Parameter	Type	Required	Description
`name`	string	Yes	A descriptive name for the assistant test.
`destination`	string	Yes	The target destination for the test conversation.
`instructions`	string	Yes	Detailed instructions that define the test scenario and what...
`rubric`	array[object]	Yes	Evaluation criteria used to assess the assistant's performan...
`description`	string	No	Optional detailed description of what this test evaluates an...
`telnyx_conversation_channel`	object	No	The communication channel through which the test will be con...
`max_duration_seconds`	integer	No	Maximum duration in seconds that the test conversation shoul...
...			+1 optional params in references/api-details.md

ruby

assistant_test = client.ai.assistants.tests.create(
  destination: "+15551234567",
  instructions: "Act as a frustrated customer who received a damaged product. Ask for a refund and escalate if not satisfied with the initial response.",
  name: "Customer Support Bot Test",
  rubric: [
    {criteria: "Assistant responds within 30 seconds", name: "Response Time"},
    {criteria: "Provides correct product information", name: "Accuracy"}
  ]
)

puts(assistant_test)

Primary response fields:

```
assistant_test.test_id
```
```
assistant_test.name
```
```
assistant_test.destination
```
```
assistant_test.created_at
```
```
assistant_test.instructions
```
```
assistant_test.description
```

创建测试是上线前验证生产环境助手行为的主要校验途径。

client.ai.assistants.tests.create()

—

POST /ai/assistants/tests

参数	类型	必填	描述
`name`	string	是	助手测试的描述性名称
`destination`	string	是	测试会话的目标接收方
`instructions`	string	是	定义测试场景的详细指令以及...
`rubric`	array[object]	是	评估助手表现的评分标准...
`description`	string	否	该测试评估内容的可选详细描述...
`telnyx_conversation_channel`	object	否	测试运行的通信渠道...
`max_duration_seconds`	integer	否	测试会话允许的最长运行时长（秒）...
...			另有1个可选参数见references/api-details.md

ruby

assistant_test = client.ai.assistants.tests.create(
  destination: "+15551234567",
  instructions: "Act as a frustrated customer who received a damaged product. Ask for a refund and escalate if not satisfied with the initial response.",
  name: "Customer Support Bot Test",
  rubric: [
    {criteria: "Assistant responds within 30 seconds", name: "Response Time"},
    {criteria: "Provides correct product information", name: "Accuracy"}
  ]
)

puts(assistant_test)

主要响应字段：

```
assistant_test.test_id
```
```
assistant_test.name
```
```
assistant_test.destination
```
```
assistant_test.created_at
```
```
assistant_test.instructions
```
```
assistant_test.description
```

Important Supporting Operations

重要的辅助操作

Use these when the core tasks above are close to your flow, but you need a common variation or follow-up step.

当上述核心任务与你的流程相近，但你需要通用变体或后续步骤时，请使用这些操作。

Get an assistant

获取助手信息

Fetch the current state before updating, deleting, or making control-flow decisions.

client.ai.assistants.retrieve()

—

GET /ai/assistants/{assistant_id}

Parameter	Type	Required	Description
`assistant_id`	string (UUID)	Yes
`call_control_id`	string (UUID)	No
`fetch_dynamic_variables_from_webhook`	boolean	No
`from`	string (E.164)	No
...			+1 optional params in references/api-details.md

ruby

assistant = client.ai.assistants.retrieve("550e8400-e29b-41d4-a716-446655440000")

puts(assistant)

Primary response fields:

```
assistant.id
```
```
assistant.name
```
```
assistant.created_at
```
```
assistant.description
```
```
assistant.dynamic_variables
```
```
assistant.dynamic_variables_webhook_url
```

在更新、删除或做控制流决策前拉取助手当前状态。

client.ai.assistants.retrieve()

—

GET /ai/assistants/{assistant_id}

参数	类型	必填	描述
`assistant_id`	string (UUID)	是
`call_control_id`	string (UUID)	否
`fetch_dynamic_variables_from_webhook`	boolean	否
`from`	string (E.164)	否
...			另有1个可选参数见references/api-details.md

ruby

assistant = client.ai.assistants.retrieve("550e8400-e29b-41d4-a716-446655440000")

puts(assistant)

主要响应字段：

```
assistant.id
```
```
assistant.name
```
```
assistant.created_at
```
```
assistant.description
```
```
assistant.dynamic_variables
```
```
assistant.dynamic_variables_webhook_url
```

Update an assistant

更新助手

Create or provision an additional resource when the core tasks do not cover this flow.

client.ai.assistants.update()

—

POST /ai/assistants/{assistant_id}

Parameter	Type	Required	Description
`assistant_id`	string (UUID)	Yes
`name`	string	No
`model`	string	No	ID of the model to use.
`instructions`	string	No	System instructions for the assistant.
...			+16 optional params in references/api-details.md

ruby

assistant = client.ai.assistants.update("550e8400-e29b-41d4-a716-446655440000")

puts(assistant)

Primary response fields:

```
assistant.id
```
```
assistant.name
```
```
assistant.created_at
```
```
assistant.description
```
```
assistant.dynamic_variables
```
```
assistant.dynamic_variables_webhook_url
```

当核心任务未覆盖该流程时，创建或配置额外资源。

client.ai.assistants.update()

—

POST /ai/assistants/{assistant_id}

参数	类型	必填	描述
`assistant_id`	string (UUID)	是
`name`	string	否
`model`	string	否	要使用的模型ID
`instructions`	string	否	给助手的系统指令
...			另有16个可选参数见references/api-details.md

ruby

assistant = client.ai.assistants.update("550e8400-e29b-41d4-a716-446655440000")

puts(assistant)

主要响应字段：

```
assistant.id
```
```
assistant.name
```
```
assistant.created_at
```
```
assistant.description
```
```
assistant.dynamic_variables
```
```
assistant.dynamic_variables_webhook_url
```

List assistants

列出所有助手

Inspect available resources or choose an existing resource before mutating it.

client.ai.assistants.list()

—

GET /ai/assistants

ruby

assistants_list = client.ai.assistants.list

puts(assistants_list)

Response wrapper:

items:
```
assistants_list.data
```

Primary item fields:

```
id
```
```
name
```
```
created_at
```
```
description
```
```
dynamic_variables
```
```
dynamic_variables_webhook_url
```

在修改资源前查看可用资源或选择现有资源。

client.ai.assistants.list()

—

GET /ai/assistants

ruby

assistants_list = client.ai.assistants.list

puts(assistants_list)

响应包装：

条目列表:
```
assistants_list.data
```

主要条目字段：

```
id
```
```
name
```
```
created_at
```
```
description
```
```
dynamic_variables
```
```
dynamic_variables_webhook_url
```

Import assistants from external provider

从外部服务商导入助手

Import existing assistants from an external provider instead of creating from scratch.

client.ai.assistants.imports()

—

POST /ai/assistants/import

Parameter	Type	Required	Description
`provider`	enum (elevenlabs, vapi, retell)	Yes	The external provider to import assistants from.
`api_key_ref`	string	Yes	Integration secret pointer that refers to the API key for th...
`import_ids`	array[string]	No	Optional list of assistant IDs to import from the external p...

ruby

assistants_list = client.ai.assistants.imports(api_key_ref: "my-openai-key", provider: :elevenlabs)

puts(assistants_list)

Response wrapper:

items:
```
assistants_list.data
```

Primary item fields:

```
id
```
```
name
```
```
created_at
```
```
description
```
```
dynamic_variables
```
```
dynamic_variables_webhook_url
```

从外部服务商导入现有助手，无需从零创建。

client.ai.assistants.imports()

—

POST /ai/assistants/import

参数	类型	必填	描述
`provider`	enum (elevenlabs, vapi, retell)	是	导入助手的来源外部服务商
`api_key_ref`	string	是	指向对应服务商API密钥的集成密钥指针
`import_ids`	array[string]	否	可选的要从外部服务商导入的助手ID列表

ruby

assistants_list = client.ai.assistants.imports(api_key_ref: "my-openai-key", provider: :elevenlabs)

puts(assistants_list)

响应包装：

条目列表:
```
assistants_list.data
```

主要条目字段：

```
id
```
```
name
```
```
created_at
```
```
description
```
```
dynamic_variables
```
```
dynamic_variables_webhook_url
```

Get All Tags

获取所有标签

Inspect available resources or choose an existing resource before mutating it.

client.ai.assistants.tags.list()

—

GET /ai/assistants/tags

ruby

tags = client.ai.assistants.tags.list

puts(tags)

Primary response fields:

```
tags.tags
```

在修改资源前查看可用资源或选择现有资源。

client.ai.assistants.tags.list()

—

GET /ai/assistants/tags

ruby

tags = client.ai.assistants.tags.list

puts(tags)

主要响应字段：

```
tags.tags
```

List assistant tests with pagination

分页列出助手测试

Inspect available resources or choose an existing resource before mutating it.

client.ai.assistants.tests.list()

—

GET /ai/assistants/tests

Parameter	Type	Required	Description
`test_suite`	string	No	Filter tests by test suite name
`telnyx_conversation_channel`	string	No	Filter tests by communication channel (e.g., 'web_chat', 'sm...
`destination`	string	No	Filter tests by destination (phone number, webhook URL, etc....
...			+1 optional params in references/api-details.md

ruby

page = client.ai.assistants.tests.list

puts(page)

Response wrapper:

items:
```
page.data
```
pagination:
```
page.meta
```

Primary item fields:

```
name
```
```
created_at
```
```
description
```
```
destination
```
```
instructions
```
```
max_duration_seconds
```

在修改资源前查看可用资源或选择现有资源。

client.ai.assistants.tests.list()

—

GET /ai/assistants/tests

参数	类型	必填	描述
`test_suite`	string	否	按测试套件名称筛选测试
`telnyx_conversation_channel`	string	否	按通信渠道筛选测试（例如'web_chat'、'sm...）
`destination`	string	否	按目标接收方筛选测试（电话号码、webhook URL等...）
...			另有1个可选参数见references/api-details.md

ruby

page = client.ai.assistants.tests.list

puts(page)

响应包装：

条目列表:
```
page.data
```
分页信息:
```
page.meta
```

主要条目字段：

```
name
```
```
created_at
```
```
description
```
```
destination
```
```
instructions
```
```
max_duration_seconds
```

Get all test suite names

获取所有测试套件名称

Inspect available resources or choose an existing resource before mutating it.

client.ai.assistants.tests.test_suites.list()

—

GET /ai/assistants/tests/test-suites

ruby

test_suites = client.ai.assistants.tests.test_suites.list

puts(test_suites)

Response wrapper:

items:
```
test_suites.data
```

Primary item fields:

```
data
```

在修改资源前查看可用资源或选择现有资源。

client.ai.assistants.tests.test_suites.list()

—

GET /ai/assistants/tests/test-suites

ruby

test_suites = client.ai.assistants.tests.test_suites.list

puts(test_suites)

响应包装：

条目列表:
```
test_suites.data
```

主要条目字段：

```
data
```

Get test suite run history

获取测试套件运行历史

Fetch the current state before updating, deleting, or making control-flow decisions.

client.ai.assistants.tests.test_suites.runs.list()

—

GET /ai/assistants/tests/test-suites/{suite_name}/runs

Parameter	Type	Required	Description
`suite_name`	string	Yes
`test_suite_run_id`	string (UUID)	No	Filter runs by specific suite execution batch ID
`status`	string	No	Filter runs by execution status (pending, running, completed...
`page`	object	No	Consolidated page parameter (deepObject style).

ruby

page = client.ai.assistants.tests.test_suites.runs.list("suite_name")

puts(page)

Response wrapper:

items:
```
page.data
```
pagination:
```
page.meta
```

Primary item fields:

```
status
```
```
created_at
```
```
updated_at
```
```
completed_at
```
```
conversation_id
```
```
conversation_insights_id
```

在更新、删除或做控制流决策前拉取当前状态。

client.ai.assistants.tests.test_suites.runs.list()

—

GET /ai/assistants/tests/test-suites/{suite_name}/runs

参数	类型	必填	描述
`suite_name`	string	是
`test_suite_run_id`	string (UUID)	否	按特定套件执行批次ID筛选运行记录
`status`	string	否	按执行状态筛选运行记录（pending、running、completed...）
`page`	object	否	统一分页参数（deepObject格式）

ruby

page = client.ai.assistants.tests.test_suites.runs.list("suite_name")

puts(page)

响应包装：

条目列表:
```
page.data
```
分页信息:
```
page.meta
```

主要条目字段：

```
status
```
```
created_at
```
```
updated_at
```
```
completed_at
```
```
conversation_id
```
```
conversation_insights_id
```

Additional Operations

额外操作

Use the core tasks above first. The operations below are indexed here with exact SDK methods and required params; use references/api-details.md for full optional params, response schemas, and lower-frequency webhook payloads. Before using any operation below, read the optional-parameters section and the response-schemas section so you do not guess missing fields.

Operation	SDK method	Endpoint	Use when	Required params
Trigger test suite execution	`client.ai.assistants.tests.test_suites.runs.trigger()`	`POST /ai/assistants/tests/test-suites/{suite_name}/runs`	Trigger a follow-up action in an existing workflow rather than creating a new top-level resource.	`suite_name`
Get assistant test by ID	`client.ai.assistants.tests.retrieve()`	`GET /ai/assistants/tests/{test_id}`	Fetch the current state before updating, deleting, or making control-flow decisions.	`test_id`
Update an assistant test	`client.ai.assistants.tests.update()`	`PUT /ai/assistants/tests/{test_id}`	Modify an existing resource without recreating it.	`test_id`
Delete an assistant test	`client.ai.assistants.tests.delete()`	`DELETE /ai/assistants/tests/{test_id}`	Remove, detach, or clean up an existing resource.	`test_id`
Get test run history for a specific test	`client.ai.assistants.tests.runs.list()`	`GET /ai/assistants/tests/{test_id}/runs`	Fetch the current state before updating, deleting, or making control-flow decisions.	`test_id`
Trigger a manual test run	`client.ai.assistants.tests.runs.trigger()`	`POST /ai/assistants/tests/{test_id}/runs`	Trigger a follow-up action in an existing workflow rather than creating a new top-level resource.	`test_id`
Get specific test run details	`client.ai.assistants.tests.runs.retrieve()`	`GET /ai/assistants/tests/{test_id}/runs/{run_id}`	Fetch the current state before updating, deleting, or making control-flow decisions.	`test_id` , `run_id`
Delete an assistant	`client.ai.assistants.delete()`	`DELETE /ai/assistants/{assistant_id}`	Remove, detach, or clean up an existing resource.	`assistant_id`
Get Canary Deploy	`client.ai.assistants.canary_deploys.retrieve()`	`GET /ai/assistants/{assistant_id}/canary-deploys`	Fetch the current state before updating, deleting, or making control-flow decisions.	`assistant_id`
Create Canary Deploy	`client.ai.assistants.canary_deploys.create()`	`POST /ai/assistants/{assistant_id}/canary-deploys`	Create or provision an additional resource when the core tasks do not cover this flow.	`versions` , `assistant_id`
Update Canary Deploy	`client.ai.assistants.canary_deploys.update()`	`PUT /ai/assistants/{assistant_id}/canary-deploys`	Modify an existing resource without recreating it.	`versions` , `assistant_id`
Delete Canary Deploy	`client.ai.assistants.canary_deploys.delete()`	`DELETE /ai/assistants/{assistant_id}/canary-deploys`	Remove, detach, or clean up an existing resource.	`assistant_id`
Assistant Sms Chat	`client.ai.assistants.send_sms()`	`POST /ai/assistants/{assistant_id}/chat/sms`	Run assistant chat over SMS instead of direct API chat.	`from` , `to` , `assistant_id`
Clone Assistant	`client.ai.assistants.clone_()`	`POST /ai/assistants/{assistant_id}/clone`	Trigger a follow-up action in an existing workflow rather than creating a new top-level resource.	`assistant_id`
List scheduled events	`client.ai.assistants.scheduled_events.list()`	`GET /ai/assistants/{assistant_id}/scheduled_events`	Fetch the current state before updating, deleting, or making control-flow decisions.	`assistant_id`
Create a scheduled event	`client.ai.assistants.scheduled_events.create()`	`POST /ai/assistants/{assistant_id}/scheduled_events`	Create or provision an additional resource when the core tasks do not cover this flow.	`telnyx_conversation_channel` , `telnyx_end_user_target` , `telnyx_agent_target` , `scheduled_at_fixed_datetime` , +1 more
Get a scheduled event	`client.ai.assistants.scheduled_events.retrieve()`	`GET /ai/assistants/{assistant_id}/scheduled_events/{event_id}`	Fetch the current state before updating, deleting, or making control-flow decisions.	`assistant_id` , `event_id`
Delete a scheduled event	`client.ai.assistants.scheduled_events.delete()`	`DELETE /ai/assistants/{assistant_id}/scheduled_events/{event_id}`	Remove, detach, or clean up an existing resource.	`assistant_id` , `event_id`
Add Assistant Tag	`client.ai.assistants.tags.add()`	`POST /ai/assistants/{assistant_id}/tags`	Create or provision an additional resource when the core tasks do not cover this flow.	`tag` , `assistant_id`
Remove Assistant Tag	`client.ai.assistants.tags.remove()`	`DELETE /ai/assistants/{assistant_id}/tags/{tag}`	Remove, detach, or clean up an existing resource.	`assistant_id` , `tag`
Get assistant texml	`client.ai.assistants.get_texml()`	`GET /ai/assistants/{assistant_id}/texml`	Fetch the current state before updating, deleting, or making control-flow decisions.	`assistant_id`
Add Assistant Tool	`client.ai.assistants.tools.add()`	`PUT /ai/assistants/{assistant_id}/tools/{tool_id}`	Modify an existing resource without recreating it.	`assistant_id` , `tool_id`
Remove Assistant Tool	`client.ai.assistants.tools.remove()`	`DELETE /ai/assistants/{assistant_id}/tools/{tool_id}`	Remove, detach, or clean up an existing resource.	`assistant_id` , `tool_id`
Test Assistant Tool	`client.ai.assistants.tools.test_()`	`POST /ai/assistants/{assistant_id}/tools/{tool_id}/test`	Trigger a follow-up action in an existing workflow rather than creating a new top-level resource.	`assistant_id` , `tool_id`
Get all versions of an assistant	`client.ai.assistants.versions.list()`	`GET /ai/assistants/{assistant_id}/versions`	Fetch the current state before updating, deleting, or making control-flow decisions.	`assistant_id`
Get a specific assistant version	`client.ai.assistants.versions.retrieve()`	`GET /ai/assistants/{assistant_id}/versions/{version_id}`	Fetch the current state before updating, deleting, or making control-flow decisions.	`assistant_id` , `version_id`
Update a specific assistant version	`client.ai.assistants.versions.update()`	`POST /ai/assistants/{assistant_id}/versions/{version_id}`	Create or provision an additional resource when the core tasks do not cover this flow.	`assistant_id` , `version_id`
Delete a specific assistant version	`client.ai.assistants.versions.delete()`	`DELETE /ai/assistants/{assistant_id}/versions/{version_id}`	Remove, detach, or clean up an existing resource.	`assistant_id` , `version_id`
Promote an assistant version to main	`client.ai.assistants.versions.promote()`	`POST /ai/assistants/{assistant_id}/versions/{version_id}/promote`	Trigger a follow-up action in an existing workflow rather than creating a new top-level resource.	`assistant_id` , `version_id`
List MCP Servers	`client.ai.mcp_servers.list()`	`GET /ai/mcp_servers`	Inspect available resources or choose an existing resource before mutating it.	None
Create MCP Server	`client.ai.mcp_servers.create()`	`POST /ai/mcp_servers`	Create or provision an additional resource when the core tasks do not cover this flow.	`name` , `type` , `url`
Get MCP Server	`client.ai.mcp_servers.retrieve()`	`GET /ai/mcp_servers/{mcp_server_id}`	Fetch the current state before updating, deleting, or making control-flow decisions.	`mcp_server_id`
Update MCP Server	`client.ai.mcp_servers.update()`	`PUT /ai/mcp_servers/{mcp_server_id}`	Modify an existing resource without recreating it.	`mcp_server_id`
Delete MCP Server	`client.ai.mcp_servers.delete()`	`DELETE /ai/mcp_servers/{mcp_server_id}`	Remove, detach, or clean up an existing resource.	`mcp_server_id`
List Tools	`client.ai.tools.list()`	`GET /ai/tools`	Inspect available resources or choose an existing resource before mutating it.	None
Create Tool	`client.ai.tools.create()`	`POST /ai/tools`	Create or provision an additional resource when the core tasks do not cover this flow.	`type` , `display_name`
Get Tool	`client.ai.tools.retrieve()`	`GET /ai/tools/{tool_id}`	Fetch the current state before updating, deleting, or making control-flow decisions.	`tool_id`
Update Tool	`client.ai.tools.update()`	`PATCH /ai/tools/{tool_id}`	Modify an existing resource without recreating it.	`tool_id`
Delete Tool	`client.ai.tools.delete()`	`DELETE /ai/tools/{tool_id}`	Remove, detach, or clean up an existing resource.	`tool_id`

For exhaustive optional parameters, full response schemas, and complete webhook payloads, see references/api-details.md.

请优先使用上述核心任务。此处列出的操作提供了准确的SDK方法和必填参数；完整的可选参数、响应schema和低频次webhook payload请查阅references/api-details.md。在使用以下任意操作前，请先阅读可选参数章节和响应 schema 章节，请勿猜测缺失的字段。

操作	SDK方法	端点	适用场景	必填参数
触发测试套件执行	`client.ai.assistants.tests.test_suites.runs.trigger()`	`POST /ai/assistants/tests/test-suites/{suite_name}/runs`	在现有工作流中触发后续操作，而非创建新的顶层资源	`suite_name`
根据ID获取助手测试	`client.ai.assistants.tests.retrieve()`	`GET /ai/assistants/tests/{test_id}`	在更新、删除或做控制流决策前拉取当前状态	`test_id`
更新助手测试	`client.ai.assistants.tests.update()`	`PUT /ai/assistants/tests/{test_id}`	修改现有资源，无需重新创建	`test_id`
删除助手测试	`client.ai.assistants.tests.delete()`	`DELETE /ai/assistants/tests/{test_id}`	移除、解绑或清理现有资源	`test_id`
获取特定测试的运行历史	`client.ai.assistants.tests.runs.list()`	`GET /ai/assistants/tests/{test_id}/runs`	在更新、删除或做控制流决策前拉取当前状态	`test_id`
触发手动测试运行	`client.ai.assistants.tests.runs.trigger()`	`POST /ai/assistants/tests/{test_id}/runs`	在现有工作流中触发后续操作，而非创建新的顶层资源	`test_id`
获取特定测试运行的详情	`client.ai.assistants.tests.runs.retrieve()`	`GET /ai/assistants/tests/{test_id}/runs/{run_id}`	在更新、删除或做控制流决策前拉取当前状态	`test_id` , `run_id`
删除助手	`client.ai.assistants.delete()`	`DELETE /ai/assistants/{assistant_id}`	移除、解绑或清理现有资源	`assistant_id`
获取金丝雀发布配置	`client.ai.assistants.canary_deploys.retrieve()`	`GET /ai/assistants/{assistant_id}/canary-deploys`	在更新、删除或做控制流决策前拉取当前状态	`assistant_id`
创建金丝雀发布配置	`client.ai.assistants.canary_deploys.create()`	`POST /ai/assistants/{assistant_id}/canary-deploys`	当核心任务未覆盖该流程时，创建或配置额外资源	`versions` , `assistant_id`
更新金丝雀发布配置	`client.ai.assistants.canary_deploys.update()`	`PUT /ai/assistants/{assistant_id}/canary-deploys`	修改现有资源，无需重新创建	`versions` , `assistant_id`
删除金丝雀发布配置	`client.ai.assistants.canary_deploys.delete()`	`DELETE /ai/assistants/{assistant_id}/canary-deploys`	移除、解绑或清理现有资源	`assistant_id`
助手短信对话	`client.ai.assistants.send_sms()`	`POST /ai/assistants/{assistant_id}/chat/sms`	通过SMS运行助手对话，而非直接API调用	`from` , `to` , `assistant_id`
克隆助手	`client.ai.assistants.clone_()`	`POST /ai/assistants/{assistant_id}/clone`	在现有工作流中触发后续操作，而非创建新的顶层资源	`assistant_id`
列出 scheduled events	`client.ai.assistants.scheduled_events.list()`	`GET /ai/assistants/{assistant_id}/scheduled_events`	在更新、删除或做控制流决策前拉取当前状态	`assistant_id`
创建 scheduled event	`client.ai.assistants.scheduled_events.create()`	`POST /ai/assistants/{assistant_id}/scheduled_events`	当核心任务未覆盖该流程时，创建或配置额外资源	`telnyx_conversation_channel` , `telnyx_end_user_target` , `telnyx_agent_target` , `scheduled_at_fixed_datetime` , 另有1个参数
获取 scheduled event	`client.ai.assistants.scheduled_events.retrieve()`	`GET /ai/assistants/{assistant_id}/scheduled_events/{event_id}`	在更新、删除或做控制流决策前拉取当前状态	`assistant_id` , `event_id`
删除 scheduled event	`client.ai.assistants.scheduled_events.delete()`	`DELETE /ai/assistants/{assistant_id}/scheduled_events/{event_id}`	移除、解绑或清理现有资源	`assistant_id` , `event_id`
添加助手标签	`client.ai.assistants.tags.add()`	`POST /ai/assistants/{assistant_id}/tags`	当核心任务未覆盖该流程时，创建或配置额外资源	`tag` , `assistant_id`
移除助手标签	`client.ai.assistants.tags.remove()`	`DELETE /ai/assistants/{assistant_id}/tags/{tag}`	移除、解绑或清理现有资源	`assistant_id` , `tag`
获取助手texml	`client.ai.assistants.get_texml()`	`GET /ai/assistants/{assistant_id}/texml`	在更新、删除或做控制流决策前拉取当前状态	`assistant_id`
添加助手工具	`client.ai.assistants.tools.add()`	`PUT /ai/assistants/{assistant_id}/tools/{tool_id}`	修改现有资源，无需重新创建	`assistant_id` , `tool_id`
移除助手工具	`client.ai.assistants.tools.remove()`	`DELETE /ai/assistants/{assistant_id}/tools/{tool_id}`	移除、解绑或清理现有资源	`assistant_id` , `tool_id`
测试助手工具	`client.ai.assistants.tools.test_()`	`POST /ai/assistants/{assistant_id}/tools/{tool_id}/test`	在现有工作流中触发后续操作，而非创建新的顶层资源	`assistant_id` , `tool_id`
列出助手所有版本	`client.ai.assistants.versions.list()`	`GET /ai/assistants/{assistant_id}/versions`	在更新、删除或做控制流决策前拉取当前状态	`assistant_id`
获取特定助手版本	`client.ai.assistants.versions.retrieve()`	`GET /ai/assistants/{assistant_id}/versions/{version_id}`	在更新、删除或做控制流决策前拉取当前状态	`assistant_id` , `version_id`
更新特定助手版本	`client.ai.assistants.versions.update()`	`POST /ai/assistants/{assistant_id}/versions/{version_id}`	当核心任务未覆盖该流程时，创建或配置额外资源	`assistant_id` , `version_id`
删除特定助手版本	`client.ai.assistants.versions.delete()`	`DELETE /ai/assistants/{assistant_id}/versions/{version_id}`	移除、解绑或清理现有资源	`assistant_id` , `version_id`
将助手版本升级为正式版	`client.ai.assistants.versions.promote()`	`POST /ai/assistants/{assistant_id}/versions/{version_id}/promote`	在现有工作流中触发后续操作，而非创建新的顶层资源	`assistant_id` , `version_id`
列出MCP服务器	`client.ai.mcp_servers.list()`	`GET /ai/mcp_servers`	在修改资源前查看可用资源或选择现有资源	无
创建MCP服务器	`client.ai.mcp_servers.create()`	`POST /ai/mcp_servers`	当核心任务未覆盖该流程时，创建或配置额外资源	`name` , `type` , `url`
获取MCP服务器	`client.ai.mcp_servers.retrieve()`	`GET /ai/mcp_servers/{mcp_server_id}`	在更新、删除或做控制流决策前拉取当前状态	`mcp_server_id`
更新MCP服务器	`client.ai.mcp_servers.update()`	`PUT /ai/mcp_servers/{mcp_server_id}`	修改现有资源，无需重新创建	`mcp_server_id`
删除MCP服务器	`client.ai.mcp_servers.delete()`	`DELETE /ai/mcp_servers/{mcp_server_id}`	移除、解绑或清理现有资源	`mcp_server_id`
列出工具	`client.ai.tools.list()`	`GET /ai/tools`	在修改资源前查看可用资源或选择现有资源	无
创建工具	`client.ai.tools.create()`	`POST /ai/tools`	当核心任务未覆盖该流程时，创建或配置额外资源	`type` , `display_name`
获取工具	`client.ai.tools.retrieve()`	`GET /ai/tools/{tool_id}`	在更新、删除或做控制流决策前拉取当前状态	`tool_id`
更新工具	`client.ai.tools.update()`	`PATCH /ai/tools/{tool_id}`	修改现有资源，无需重新创建	`tool_id`
删除工具	`client.ai.tools.delete()`	`DELETE /ai/tools/{tool_id}`	移除、解绑或清理现有资源	`tool_id`

如需完整的可选参数、全量响应schema和完整webhook payload，请查阅references/api-details.md。