Threads - Create Thread

服务:

AI Foundry

API 版本:

v1

创建新线程。 线程包含消息，可由代理运行。

POST {endpoint}/threads?api-version=v1

URI 参数

名称	在	必需	类型	说明
endpoint	path	True	string (uri)	项目端点，其形式为： https://.services.ai.azure.com/api/projects/
api-version	query	True	string minLength: 1	用于此操作的 API 版本。

请求正文

名称	类型	说明
messages	ThreadMessageOptions[]	要与新线程关联的初始消息。
metadata	object	一组最多可以附加到对象的 16 个键/值对，用于以结构化格式存储有关该对象的其他信息。 键长度可能最多为 64 个字符，值长度可能最多为 512 个字符。
tool_resources	ToolResources	一组可供此线程中的代理工具使用的资源。 资源特定于工具类型。 例如，code_interpreter 工具需要文件 ID 列表，而 file_search 工具需要矢量存储 ID 列表。

响应

名称	类型	说明
200 OK	AgentThread	有关新创建的线程的信息。
Other Status Codes	AgentV1Error	意外的错误响应。

安全性

OAuth2Auth

类型: oauth2
流向: implicit
授权 URL: https://login.microsoftonline.com/common/oauth2/v2.0/authorize

作用域

名称	说明
https://ai.azure.com/.default

定义

名称	说明
AgentErrorDetail	描述代理 API 返回的错误信息。
AgentThread	有关与代理关联的单个线程的信息。
AgentThreadCreationOptions	用于创建新代理线程的详细信息。
AgentV1Error	代理 API 返回的错误负载。
AISearchIndexResource	AI 搜索索引资源。
AzureAISearchQueryType	Azure AI 搜索工具的可用查询类型。
AzureAISearchToolResource	azure_ai_search 工具使用的一组索引资源。
CodeInterpreterToolResource	code_interpreter 工具使用的一组资源。
FileSearchToolResource	file_search 工具使用的一组资源。
MessageAttachment	这描述了文件已附加到哪些工具。
MessageRole	归因于线程中消息的角色的可能值。
ThreadMessageOptions	代理线程中的单个消息，在该线程创建期间为初始状态提供。
ToolResources	代理工具使用的一组资源。 资源特定于工具类型。 例如，code_interpreter 工具需要文件 ID 列表，而 file_search 工具需要矢量存储 ID 列表。
VectorStoreConfiguration	矢量存储配置是数据源列表，当多个文件可用于企业文件搜索时使用。
VectorStoreConfigurations	结构，包含矢量存储配置列表，即 Azure 资产 ID 的列表。
VectorStoreDataSource	结构，包含 Azure 资产 URI 路径和用作企业文件搜索数据源的文件的资产类型。
VectorStoreDataSourceAssetType	矢量存储资产的类型。 资产类型可以是uri_asset，在这种情况下，它应包含资产 URI ID，在这种情况下，它应包含数据 ID id_asset。

AgentErrorDetail

Object

描述代理 API 返回的错误信息。

名称	类型	说明
code	string	机器可读的错误代码。
message	string	错误的可读描述。
param	string	导致错误的参数的名称（如果适用）。
type	string	错误类型标识符（例如 invalid_request_error）。

AgentThread

Object

有关与代理关联的单个线程的信息。

名称	类型	说明
created_at	integer (unixtime)	Unix 时间戳（以秒为单位）表示创建此对象的时间。
id	string	可以在 API 终结点中引用的标识符。
metadata	object	一组最多可以附加到对象的 16 个键/值对，用于以结构化格式存储有关该对象的其他信息。 键长度可能最多为 64 个字符，值长度可能最多为 512 个字符。
object	enum: thread	对象类型，始终为“thread”。
tool_resources	ToolResources	一组可供此线程中的代理工具使用的资源。 资源特定于工具类型。 例如，code_interpreter 工具需要文件 ID 列表，而 file_search 工具需要矢量存储 ID 列表。

AgentThreadCreationOptions

Object

用于创建新代理线程的详细信息。

名称	类型	说明
messages	ThreadMessageOptions[]	要与新线程关联的初始消息。
metadata	object	一组最多可以附加到对象的 16 个键/值对，用于以结构化格式存储有关该对象的其他信息。 键长度可能最多为 64 个字符，值长度可能最多为 512 个字符。
tool_resources	ToolResources	一组可供此线程中的代理工具使用的资源。 资源特定于工具类型。 例如，code_interpreter 工具需要文件 ID 列表，而 file_search 工具需要矢量存储 ID 列表。

AgentV1Error

Object

代理 API 返回的错误负载。

名称	类型	说明
error	AgentErrorDetail	表示错误。

AISearchIndexResource

Object

AI 搜索索引资源。

名称	类型	说明
filter	string	搜索资源的 filter 字符串。
index_asset_id	string	为搜索资源的资产 ID 编制索引。
index_connection_id	string	附加到此代理的 IndexResource 中的索引连接 ID。
index_name	string	附加到此代理的 IndexResource 中的索引的名称。
query_type	AzureAISearchQueryType	附加到此代理的 AIIndexResource 中的查询类型。
top_k	integer (int32)	要从搜索中检索到的文档数，并将其呈现到模型。

AzureAISearchQueryType

枚举

Azure AI 搜索工具的可用查询类型。

值	说明
semantic	查询类型 semantic
simple	查询类型 simple
vector	查询类型 vector
vector_semantic_hybrid	查询类型 vector_semantic_hybrid
vector_simple_hybrid	查询类型 vector_simple_hybrid

AzureAISearchToolResource

Object

azure_ai_search 工具使用的一组索引资源。

名称	类型	说明
indexes	AISearchIndexResource[]	附加到此代理的索引。 最多可以有 1 个索引资源附加到代理。

CodeInterpreterToolResource

Object

code_interpreter 工具使用的一组资源。

名称	类型	说明
data_sources	VectorStoreDataSource[]	要使用的数据源。 此选项与 fileIds 属性互斥。
file_ids	string[]	可供 code_interpreter 工具使用的文件 ID 列表。 最多可以有 20 个与该工具关联的文件。

FileSearchToolResource

Object

file_search 工具使用的一组资源。

名称	类型	说明
vector_store_ids	string[]	附加到此代理的向量存储的 ID。 最多可以有 1 个向量存储附加到代理。
vector_stores	VectorStoreConfigurations[]	来自 Azure 的矢量存储配置对象列表。 此列表限制为一个元素。 此列表的唯一元素包含搜索工具使用的 Azure 资产 ID 列表。

MessageAttachment

Object

这描述了文件已附加到哪些工具。

名称	类型	说明
data_source	VectorStoreDataSource	Azure 资产 ID。
file_id	string	要附加到消息的文件的 ID。
tools	MessageAttachmentToolDefinition[]	要添加到此文件的工具。

MessageRole

枚举

归因于线程中消息的角色的可能值。

值	说明
assistant	表示代理的角色。
user	表示最终用户的角色。

ThreadMessageOptions

Object

代理线程中的单个消息，在该线程创建期间为初始状态提供。

名称	类型	说明
attachments	MessageAttachment[]	附加到消息的文件列表及其应添加到的工具。
content	MessageInputContent	初始消息的内容。 这可以是基本字符串（如果只需要文本）或键入内容块的数组（例如，文本、image_file、image_url等）。
metadata	object	一组最多可以附加到对象的 16 个键/值对，用于以结构化格式存储有关该对象的其他信息。 键长度可能最多为 64 个字符，值长度可能最多为 512 个字符。
role	MessageRole	正在创建消息的实体的角色。 允许的值包括： user，它指示消息由实际用户发送（在大多数情况下应用于表示用户生成的消息），以及 assistant，指示消息由代理生成（使用此值将来自代理的消息插入到对话中）。

ToolResources

Object

代理工具使用的一组资源。 资源特定于工具类型。 例如，code_interpreter 工具需要文件 ID 列表，而 file_search 工具需要矢量存储 ID 列表。

名称	类型	说明
azure_ai_search	AzureAISearchToolResource	由索引 ID 和名称组成的 azure_ai_search 工具使用的资源。
code_interpreter	CodeInterpreterToolResource	由文件 ID 组成的 code_interpreter 工具使用的资源。
file_search	FileSearchToolResource	由矢量存储 ID 组成的 file_search 工具使用的资源。

VectorStoreConfiguration

Object

矢量存储配置是数据源列表，当多个文件可用于企业文件搜索时使用。

名称	类型	说明
data_sources	VectorStoreDataSource[]	数据源

VectorStoreConfigurations

Object

结构，包含矢量存储配置列表，即 Azure 资产 ID 的列表。

名称	类型	说明
configuration	VectorStoreConfiguration	配置
name	string	名称

VectorStoreDataSource

Object

结构，包含 Azure 资产 URI 路径和用作企业文件搜索数据源的文件的资产类型。

名称	类型	说明
type	VectorStoreDataSourceAssetType	资产类型
uri	string	资产 URI。

VectorStoreDataSourceAssetType

枚举

矢量存储资产的类型。 资产类型可以是uri_asset，在这种情况下，它应包含资产 URI ID，在这种情况下，它应包含数据 ID id_asset。

值	说明
id_asset	数据 ID
uri_asset	Azure URI