Sending a response | Astro AI

Every reply your agent sends is an AgentResponse carrying exactly one payload variant.

Node

Python

AgentResponse

Field	Type	Required	Notes
`conversationId`	string	yes	Must match the inbound `Message.conversationId`.
`responseId`	string	no	Stable ID for this response. Used by feedback events.
`traceContext`	`TraceContext`	no	W3C trace context for this assistant response. See Trace context.
one variant		yes	One of the fields below; @grpc/proto-loader flattens the oneof.

AgentResponse payload variants

Variant	Type	Notes
`incomingMessage`	`Message`	Server → agent only. The inbound message itself.
`status`	`StatusUpdate`	Pre-content typing indicator.
`content`	`ContentChunk`	Actual message text, streamed.
`prompts`	`SuggestedPrompts`	Quick-reply suggestions.
`threadMetadata`	`ThreadMetadata`	Open a thread or update its title.
`transcript`	`Transcript`	STT result back to the platform (audio flow).
`error`	`ErrorResponse`	Surface an error to the user.
`contextRequest`	`ThreadHistoryRequest`	Ask the sidecar to hydrate thread history.
`audioConfig`	`AudioStreamConfig`	Server → agent only. Audio session start.
`audioChunk`	`AudioChunk`	Server → agent only. Audio bytes.
`feedback`	`PlatformFeedback`	Server → agent only. User feedback event.

Streaming text content

Node

Python

ContentChunk

Field	Type	Required	Notes
`type`	string	yes	`START` \| `DELTA` \| `END` \| `REPLACE` (see lifecycle).
`content`	string	no	Semantics depend on `type`.
`attachments`	`ResponseAttachment[]`	no	Ship with `END` chunks (or standalone).
`platformMessageId`	string	no	Returned by the adapter after `START`; pass on later chunks to update it.
`options`	`MessageOptions`	no	Creation flags.

ContentChunk.type lifecycle

Value	Use
`START`	Create the platform message. May be empty (immediate presence) or include initial content.
`DELTA`	Append the next token(s). Stream as many as you want.
`END`	Finalize. Last content (optional) and any `attachments` ship here.
`REPLACE`	Overwrite the full message content, for post-stream edits.

MessageOptions

Field	Type	Required	Notes
`ephemeral`	boolean	no	Only visible to the recipient user.
`createThread`	boolean	no	Start a new thread under the user’s message.
`replyToMessageId`	string	no	Reply to a specific message.
`silent`	boolean	no	Suppress notification.

ResponseAttachment (set exactly one variant)

Variant	Type	Fields
`image`	`ImageAttachment`	`url`, `altText?`, `title?`, `width?`, `height?`
`file`	`FileAttachment`	`url?`, `filename`, `mimeType?`, `sizeBytes?`. For a filesystem output, write `filename` inside `AGENT_FILES_DIR` before sending `END` and leave `url` empty.
`card`	`CardAttachment`	`platformCardJson` — Slack Block Kit, Discord Embeds, Teams cards.
`link`	`LinkPreview`	`url`, `title?`, `description?`, `imageUrl?`

conversation.sendContentChunk(cid, { type: 'START', content: '' });
for await (const token of llm.stream(prompt)) {
  conversation.sendContentChunk(cid, { type: 'DELTA', content: token });
}
conversation.sendContentChunk(cid, { type: 'END', content: '' });

Status updates

Node

Python

StatusUpdate

Field	Type	Required	Notes
`status`	string	yes	One of the enum values below.
`customMessage`	string	no	Required with `CUSTOM`; otherwise overrides the default phrasing.
`emoji`	string	no	Platform emoji, e.g. `:mag:`.

StatusUpdate.status values: THINKING, SEARCHING, GENERATING, PROCESSING, ANALYZING, CUSTOM.

conversation.sendStatusUpdate(cid, { status: 'SEARCHING' });
conversation.sendStatusUpdate(cid, {
  status: 'CUSTOM',
  customMessage: 'Querying the knowledge base…',
  emoji: ':mag:',
});

Suggested prompts

Node

Python

SuggestedPrompts

Field	Type	Required	Notes
`prompts`	`Prompt[]`	yes	Max 4–6 depending on platform.

Prompt

Field	Type	Required	Notes
`id`	string	yes	Unique ID. Echoed back in `PlatformFeedback.promptSelection`.
`title`	string	yes	Button/chip label.
`message`	string	yes	Full message sent on click.
`description`	string	no	Tooltip/help text.

Errors

Node

Python

ErrorResponse

Field	Type	Required	Notes
`code`	string	yes	One of the enum values below.
`message`	string	yes	User-facing error message.
`details`	string	no	Technical details. Logged, not shown to the user.
`retryable`	boolean	no	Whether the platform should offer a retry affordance.

ErrorResponse.code values: RATE_LIMIT, CONTEXT_TOO_LONG, INVALID_REQUEST, AGENT_ERROR, TOOL_ERROR, PLATFORM_ERROR.

Thread metadata

Node

Python

ThreadMetadata

Field	Type	Required	Notes
`threadId`	string	no	Platform thread ID. Set to update an existing thread.
`title`	string	no	Thread title/subject.
`createNew`	boolean	no	Create a new thread.

Transcript

Sent after STT to replace the “[audio]” placeholder on the platform.

Node

Python

Transcript

Field	Type	Required	Notes
`text`	string	yes	Transcribed text.
`messageId`	string	no	Placeholder message ID to update.
`language`	string	no	BCP-47 detected language (e.g. `en-US`).

Next steps

Trace context: correlate a response back to its trace
Audio: the STT flow that produces a Transcript
Worked examples: these pieces assembled into an agent