<span id="公开web应用对象"></span>

# Public Web application objects

These objects serve visitor calls. Publication-management objects and deployed site configuration have separate protocols. Example IDs/tokens/results are fixed illustrative values.

<span id="链接与session"></span>

## Links and sessions

resolve returns `agent_name`; only short-code `k` responses additionally include `agent_id`. Session creation/refresh returns `session_token` and `expires_in`, fixed604800 seconds.

<span id="创建会话"></span>

## Create conversations

Creation returns full `AgentConversationView`; use `id` for subsequent calls. List/rename summaries use `conversation_id` instead. These field names are not interchangeable.

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Successfully created conversation ID. |
| `workspace_id` | string | Publication workspace. |
| `agent_workspace_id` | string | Agent definition workspace; may be system for system agents. |
| `agent_id` | string | Target agent. |
| `agent_summary` | object | Display summary of the target agent. |
| `title` | string | Conversation title; omitted when empty. |
| `title_user_edited` | boolean | Whether the user edited the title. |
| `status` | string | Conversation state; active at creation. |
| `purpose` | string | webapp for these objects. |
| `visibility` | string | Conversation visibility. |
| `parent_conversation_id`, `source_message_id` | string | Parent conversation and source message; omitted when empty. |
| `pinned` | boolean | Conversation pinned state. |
| `head_message_id` | string | Current head message; omitted when empty. |
| `active_task_id`, `latest_task_id` | string | Active/latest tasks; omitted when empty. |
| `latest_task_state` | string | Latest task state; omitted when empty. |
| `last_message_at` | string | Last message time; omitted when unset. |
| `created_at`、`updated_at` | string | RFC3339 timestamp. |

`agent_summary` contains `id`, `display_name`, `available`, and potentially omitted `workspace_id`, `avatar_ref`, `status`, and `unavailable_reason`. These are display facts, not an independent authorization result.

<span id="列表消息与事件"></span>

## Lists, messages, and events

Conversation lists return `items/total/limit/offset`; each summary contains only `conversation_id/title/updated_at`. Rename returns the same three fields. Public lists include active only and do not use management status filters.

Message lists also return `items/total/limit/offset`. See the [Shared projection](../../ai-studio/agents/web-apps/objects.md#消息列表) for15 message top-level fields.

Events return `items/total/after_seq`. Each event includes `id/workspace_id/task_id/seq/kind/visible/created_at` and optionally `a2a_state/payload`. payload is publicly projected and sanitized, not a complete internal event. `after_seq` echoes input; `total` counts this projection. Continue with the actual maximum seq; empty pages do not mean terminal tasks.

<span id="文件与反馈"></span>

## Files and feedback

| Object | Fields | Purpose |
| --- | --- | --- |
| Staged uploaded file | `file_id/workspace_id/volume_id/name/size/md5/file_token` | Assemble canonical attachments and per-file credentials. Does not mean the model used the file. |
| Conversation archival | `conversation_id/status` | Confirms status=archived, not physical deletion. |
| Feedback receipt | `feedback_id` | Confirms recording, not regeneration or task results. |

Uploaded file `volume_id`/`size` are integers; other upload fields are strings. size is bytes. Task artifact downloads/previews return bytes/streams directly.

<span id="mcp应用"></span>

## MCP applications

Resource responses contain `uri` and `contents`. Call responses contain `content`, `is_error`, and optional `structured_content`. Explicitly inspect `is_error=false`; HTTP success does not guarantee tool success.

Select at least `tool_id` or `tool_name`. With `tool_name`, match an app-visible tool name in the task; otherwise match by ID. Arbitrary tool names on the same connection cannot be called. Results do not automatically become model context or persisted events. Subsequent client context must use canonical data parts.
