Skip to main content
Messages in Terminal Use are returned in UIMessage format, optimized for frontend consumption with automatic tool merging and pagination.
This page is an overview. For the HTTP API, use List Messages and Get Message. The CLI does not currently expose tu messages.

​
Sending Messages (Agents)

Use ctx.messages in agent handlers to send messages: 
from terminaluse.lib import AgentServer, TaskContext, Event
from terminaluse.lib import TextPart, DataPart

server = AgentServer()

@server.on_event
async def handle_event(ctx: TaskContext, event: Event):
    # Simple text message (recommended)
    await ctx.messages.send("Hello!")

    # With markdown formatting
    await ctx.messages.send("**Bold** and *italic*")

    # Explicit TextPart
    await ctx.messages.send(TextPart(text="Hello world"))

    # Structured data (for generative UIs)
    await ctx.messages.send(DataPart(data={"temperature": 72, "unit": "fahrenheit"}))
For full ADK reference, see ADK Reference.

​
List Messages

List messages for a task in UIMessage format. 
# Using ctx in agent handlers (recommended)
messages = await ctx.messages.list()

# Using SDK client directly
messages = client.messages_v2.list(task_id="task-uuid")
for message in messages:
    print(message.parts)

# With pagination
for page in messages.iter_pages():
    print(page)
Parameters:
  • task_id (str): Task UUID
  • limit (int, optional): Max results (default: 50)
  • cursor (str, optional): Pagination cursor
  • direction (str, optional): “older” (default) or “newer”
  • parent_tool_use_id (str, optional): Filter by parent tool use ID (for subagent context)
Returns: Paginated UiMessage list

​
Retrieve Message

Get a single message by ID. 
message = client.messages_v2.retrieve(
    message_id="message-uuid",
    task_id="task-uuid"
)
Parameters:
  • message_id (str): Message UUID
  • task_id (str): Task UUID
Returns: UiMessage or null if not found

​
Content Types

​
TextPart

from terminaluse.lib import TextPart

# Simple - just pass a string (auto-wrapped to TextPart)
await ctx.messages.send("Hello!")

# Explicit TextPart
await ctx.messages.send(TextPart(text="Hello!"))

​
DataPart

from terminaluse.lib import DataPart

# Structured data for generative UIs
await ctx.messages.send(DataPart(data={"key": "value"}))

​
UIMessage Format

Messages are returned in UIMessage format, compatible with the Vercel AI SDK: 
message.id              # Message UUID
message.role            # "user" | "assistant"
message.parts           # Content parts (text, tool calls, etc.)
message.created_at      # Creation timestamp
Features:
  • Tool merging: tool_use and tool_result are combined into single tool parts
  • Complete-units pagination: Never splits tool request/result pairs across pages
  • Streaming support: Real-time updates via SSE