Messages & activity

A message is content in a conversation. Activity tells your app what is happening while inputs are handled.

Send and request

The TypeScript agent API provides two ways to submit an input:

• agent.send(input) queues it and returns a receipt.
• agent.request(input) waits for its answer and returns the resulting messages.

An accepted input is not a completed reply. Keep queued, running, and completed states distinct in your UI.

Input identity

Give each new input an ID that is unique in its conversation. The ID lets your app relate later results to the input that caused them.

Do not create new IDs merely to retry the same action without considering its effects. Your app’s handlers should also protect state-changing operations from unintended duplication.

Subscribe to activity

agent.subscribe({ onEvent }) delivers a snapshot and subsequent events. Important event types include:

Event	What your UI uses it for
message.start	Begin displaying a message
message.delta	Display provisional streamed text
message.end	Finalize a message
input	Update an input’s status
state	Show whether the agent is idle, running, or waiting

Render updates by message identity rather than treating each streamed chunk as a new message. Close the subscription when the conversation UI is disposed.

History and monitoring

Use agent.history({ limit, before }) to retrieve older conversation messages. Studio monitoring is a different view: reported model calls and usage are not a substitute for conversation messages or final turn outcomes.

See the TypeScript guide for a subscription example and Monitoring for reported usage.