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.
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.
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 |
|---|---|---|
|
string |
Successfully created conversation ID. |
|
string |
Publication workspace. |
|
string |
Agent definition workspace; may be system for system agents. |
|
string |
Target agent. |
|
object |
Display summary of the target agent. |
|
string |
Conversation title; omitted when empty. |
|
boolean |
Whether the user edited the title. |
|
string |
Conversation state; active at creation. |
|
string |
webapp for these objects. |
|
string |
Conversation visibility. |
|
string |
Parent conversation and source message; omitted when empty. |
|
boolean |
Conversation pinned state. |
|
string |
Current head message; omitted when empty. |
|
string |
Active/latest tasks; omitted when empty. |
|
string |
Latest task state; omitted when empty. |
|
string |
Last message time; omitted when unset. |
|
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.
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 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.
Files and feedback¶
Object |
Fields |
Purpose |
|---|---|---|
Staged uploaded file |
|
Assemble canonical attachments and per-file credentials. Does not mean the model used the file. |
Conversation archival |
|
Confirms status=archived, not physical deletion. |
Feedback receipt |
|
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.
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.