Streaming components

Yield strings for markdown or dicts for rich components: thinking bubbles, tables, code, callouts, images and client actions.

An agent body yields two kinds of value. Strings render as markdown. Dicts render as components. Both stream as they are produced, so the interface fills in while the model is still working.

@cycls.agent(web=web, volumes={"/workspace": chats})
async def demo(context):
    yield {"type": "status", "status": "Checking the fleet"}

    yield "Here is what I found:\n\n"

    yield {"type": "table", "headers": ["Server", "Status", "CPU"]}
    yield {"type": "table", "row": ["web-1", "Online", "45%"]}
    yield {"type": "table", "row": ["web-2", "Offline", "0%"]}

    yield {"type": "code", "code": "systemctl restart web-2", "language": "bash"}
    yield {"type": "callout", "callout": "web-2 needs attention.", "style": "warning"}

Component reference

Type	Required keys	Behavior
text	text	accumulates into one block. A bare string is the same thing
thinking	thinking	accumulates into a collapsible bubble
code	code, language	accumulates into one block
table	headers or row	renders row by row
callout	callout, style	one card. style is info, warning, error or success
status	status	a single line that replaces the previous status
image	src, optional alt, caption	one image
sources	sources	citation chips from [{title, url, snippet}]
step	step, optional tool_name, id	a tool step line
ui	action	a client action, not rendered and not stored

Raw HTML strings pass through, which is the escape hatch for anything the components do not cover.

Thinking

Consecutive thinking yields append to the same bubble until a different type arrives. Provider reasoning deltas map here automatically, so extended thinking from Anthropic and delta.reasoning from OpenAI-compatible endpoints both show up without any work on your side.

yield {"type": "thinking", "thinking": "Checking the invoice totals "}
yield {"type": "thinking", "thinking": "against last month."}
yield "The totals match."

Tables

Send the header row once, then one row per record. Rows render as they arrive, so a slow query shows partial results instead of nothing.

yield {"type": "table", "headers": ["Region", "Revenue"]}
for region, revenue in await query():
    yield {"type": "table", "row": [region, f"{revenue:,.0f}"]}

Client actions

A ui event triggers something in the client. Nothing is rendered in the conversation and nothing is kept in history.

if await over_quota(context.user):
    yield {"type": "callout", "callout": "Free tier limit reached.", "style": "warning"}
    yield {"type": "ui", "action": "open_plan_modal"}
    return

Action	Fields	Effect
open_plan_modal	none	opens pricing. The client picks user or organization plans based on the active org
open_canvas	path, optional name	opens a workspace file in the canvas viewer
suggest	text	one follow-up chip above the composer
ask	questions	a question card above the composer, up to three questions

The Canvas, Suggest and Ask built-in tools fire these for you. Yield them directly only from a custom loop. One difference worth knowing: when the Ask tool fires, the turn ends, because the next user message carries the answers.

Errors

An unhandled exception inside the body becomes a callout with a short reference id, and the full traceback goes to structured logs.

Something went wrong. Reference: abc12345

Look it up with the reference:

cycls logs my-agent --query 'jsonPayload.error_id="abc12345"'

Errors the loop handles itself, such as a rate limit retry or a tool timeout, are shown as callouts and are not logged as failures.

Next

Context

What the body receives on every turn.