Research agent

The demo plays a scripted run, so it needs no API key: the agent plans, searches in five rounds with results arriving in batches, reads ten pages and writes a cited report. Ask a follow-up from the composer for a short answer drawn from the report. Open /preview/research-agent-demo to see it full screen.

Installation

The block installs to components/chatcn/research-agent/research-agent.tsx together with every component it composes. It is your code from here: rename the views, drop the sources filter, add an export.

Usage

Pass messages, status and actions from useChatcnChat. The block reads the run out of the messages: web search tool calls become the results view and the sources, page fetches count as reads, and two data parts carry the plan and the report.

"use client"


export default function Page() {
  const modes = useRef<string[]>(["deep-research"])
  const chat = useChatcnChat({
    transport: new DefaultChatTransport({
      api: "/api/research",
      body: () => ({ modes: modes.current }),
    }),
  })
  return (
    <ResearchAgent
      fullHeight
      messages={chat.chatcnMessages}
      status={chat.status}
      error={chat.error}
      actions={chat.actions}
      onSend={(text, options) => {
        modes.current = options.modes
        void chat.actions.send?.(text)
      }}
    />
  )
}

On the server, stream the plan and the report as data parts with a stable id. Writing the same id again replaces the part, so the report grows in place while the model writes it.

const stream = createUIMessageStream({
  execute: async ({ writer }) => {
    writer.write({ type: "data-research-plan", id: "plan", data: { title, steps } })

    // web_search and web_fetch tool calls stream as usual ...

    let markdown = ""
    for await (const delta of report.textStream) {
      markdown += delta
      writer.write({
        type: "data-research-report",
        id: "report",
        data: { markdown, sources: citedUrls, state: "streaming" },
      })
    }
    writer.write({
      type: "data-research-report",
      id: "report",
      data: { markdown, sources: citedUrls, state: "done", date: "Oct 21, 2026" },
    })
  },
})

The data parts

Other tool names work through toolKinds: { exa_search: "search", firecrawl: "read" }. Tools that are neither render in the thread with toolRenderers. Use researchFromMessages(messages) to read the same state outside the block, for example in a run list.

Components it composes

Responsive

The block lays out by its own width, not the viewport, so it works in a page, a sheet or this docs column. From 768 px it splits into the thread and a workspace with Results, Report and Sources tabs, resizable from 360 px. Narrower, one pane shows at a time under an Activity, Results, Report and Sources tab bar with 44 px targets on touch. A quiet dot marks the Report tab while a report you have not opened is written.

The workspace follows the run: results while it searches and reads, the report once writing starts. Picking a tab stops the following until the next question.

Props

Keyboard

Accessibility

• View tabs are a tablist with roving focus; the workspace is the tabpanel and scrolls by keyboard.
• The progress card announces each phase change and the end of the run once, never per source.
• The thread is a silent log; finished replies are announced through the conversation's live region.
• The sources filter uses aria-pressed, and the fresh dot on the Report tab has a text equivalent.
• Citations jump to their source and move focus there; modified clicks still open the page.

Motion

• Switching views is instant, whether by pointer or keyboard: the tab fill changes color in 150 ms and nothing moves.
• New searches, report sections and sources fade in with @starting-style; nothing slides or counts up.
• The report streams in place with the streaming caret. With reduced motion, only short opacity fades remain.