# 公开Web应用对象

这些对象用于访客调用，发布管理对象与部署站点配置另有协议。示例中的ID、token和结果是固定说明值。

## 链接与session

resolve 返回 `agent_name`；仅短码输入 `k` 的响应另含 `agent_id`。session 创建和刷新返回 `session_token`、`expires_in`，后者单位为秒，固定604800。

## 创建会话

创建返回完整 `AgentConversationView`，其中继续调用使用 `id`。列表与改名返回的摘要则使用 `conversation_id`，两者不能互换字段名。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | string | 创建成功的会话ID。 |
| `workspace_id` | string | 发布工作区。 |
| `agent_workspace_id` | string | 智能体定义工作区，系统智能体可为system。 |
| `agent_id` | string | 目标智能体。 |
| `agent_summary` | object | 目标智能体的展示摘要。 |
| `title` | string | 会话标题，空时省略。 |
| `title_user_edited` | boolean | 标题是否经用户修改。 |
| `status` | string | 会话状态，创建为active。 |
| `purpose` | string | 本组为webapp。 |
| `visibility` | string | 会话可见性。 |
| `parent_conversation_id`、`source_message_id` | string | 父会话和来源消息，空时省略。 |
| `pinned` | boolean | 会话置顶状态。 |
| `head_message_id` | string | 当前头消息，空时省略。 |
| `active_task_id`、`latest_task_id` | string | 活动和最近任务，空时省略。 |
| `latest_task_state` | string | 最近任务状态，空时省略。 |
| `last_message_at` | string | 最近消息时间，未设置时省略。 |
| `created_at`、`updated_at` | string | RFC3339时间。 |

`agent_summary` 包含 `id`、`display_name`、`available`，以及可能省略的 `workspace_id`、`avatar_ref`、`status`、`unavailable_reason`。它是展示事实，不是独立授权结果。

## 列表、消息与事件

会话列表为 `items/total/limit/offset`；每条摘要仅包含 `conversation_id/title/updated_at`。改名也返回这三个字段。公开列表只列active，不使用管理接口的status筛选。

消息列表同为 `items/total/limit/offset`，消息15个顶层字段见[同一投影说明](../../ai-studio/agents/web-apps/objects.md#消息列表)。

事件列表返回 `items/total/after_seq`。每条事件包含 `id/workspace_id/task_id/seq/kind/visible/created_at`，以及可能省略的 `a2a_state/payload`。payload经过可公开内容投影和脱敏，不是完整内部事件对象。`after_seq`回显输入，`total`为本次投影条数；下一次按实际最大seq继续，不把空页当任务终态。

## 文件与反馈

| 对象 | 字段 | 用途 |
| --- | --- | --- |
| 暂存上传文件 | `file_id/workspace_id/volume_id/name/size/md5/file_token` | 组装规范附件及逐文件凭据；不等于模型已使用文件。 |
| 会话归档 | `conversation_id/status` | 确认status=archived，不是物理删除。 |
| 反馈回执 | `feedback_id` | 确认已记录，不代表重新生成或任务结果。 |

文件 `volume_id`、`size` 为integer，其余上传字段为string；size单位为字节。任务产物下载和预览直接返回字节/流。

## MCP应用

资源响应包含 `uri` 和 `contents`。调用响应包含 `content`、`is_error` 和可选 `structured_content`；`is_error=false`必须显式读取，HTTP成功不保证工具成功。

调用至少选择 `tool_id` 或 `tool_name`。存在 `tool_name` 时按任务中app-visible工具名匹配；不存在时按ID匹配，不能凭同连接上任意工具名调用。结果不会自动成为模型上下文或持久事件，客户端后续携带上下文须遵循规范data部件。
