useAgent

Run AI agent queries with streaming, tool calls, interrupts, status updates, and automatic conversation persistence.

import { useAgent } from 'flowstack-sdk'

useAgent is the primary AI hook: it runs agent queries with token streaming, surfaces active/completed tool calls and connected data sources, and supports mid-execution interrupts.

Template (first arg): 'data-science' | 'marketing' | 'support' | 'custom'. For a persona-backed app (your app's brain is an agent registered via casino_create_agent), the template is just a fallback label — the registered persona overrides it. Use 'custom' (or omit) and select the brain with the persona option. The template does not pick the agent.

Conversation memory (automatic): useAgent persists a stable session ID for each component mount — generated on first use via crypto.randomUUID() (with a timestamp fallback for legacy browsers), stable across turns (every query() passes the same session ID), and reused by Strands' S3SessionManager so the agent remembers prior messages, tool calls, and context across turns. clearMessages() resets the session, generating a fresh session ID on the next query(). The session ID is tied to the component mount: unmounting/remounting (e.g. closing and reopening a modal) starts a new conversation. The simplest path (0.2.1+) for cross-reload persistence is to pass a stable sessionKey per surface; for cross-tab or multi-conversation persistence, manage the session ID at the application level (e.g. in localStorage). Wallet-authenticated users have conversations scoped to their wallet address server-side.

ChatMessage fields (each item in messages): id (string), role ('user' | 'assistant'), content (string), isStreaming (boolean), statusLine (string | undefined — live status text during streaming), toolCalls (ToolCall[]), visualizations (VisualizationData[]), searchResults (SearchResultsData[]).

Signature

const { messages, isStreaming, isLoading, toolCalls, connectedDataSources, error, query, clearMessages, startNewSession, cancelQuery, interruptAgent, respondToInterrupt } = useAgent(template?, options?)

Parameters

Returns

Examples

// Each surface gets its own brain + isolated conversation.
const chat   = useAgent('custom', { capabilities: ['data_access'], persona: 'assistant', sessionKey: 'chat' });
const worker = useAgent('custom', { capabilities: ['data_access'], persona: 'worker',    sessionKey: 'tasks' });

function AssistantChat() {
  const { query, messages, isStreaming } = useAgent(undefined, {
    persona: 'assistant'  // agent registered via casino_create_agent
  });

  // Turn 1: "summarize this dataset"
  // Turn 2: "now group it by region"      ← agent remembers "this dataset"
  // Turn 3: "which region is the biggest?" ← agent knows the grouping from turn 2

  return (
    <ChatUI messages={messages} onSend={query} isStreaming={isStreaming} />
  );
}

const chat = useAgent('custom', { capabilities: ['data_access'], sessionKey: 'support-chat' });
// Reopening/reloading this surface resumes the same conversation; a different sessionKey is a
// different conversation. Call chat.clearMessages() / startNewSession() to start fresh.

See also

useCollection · useAuth · useDatasets

Source: README.md#useagent · Also available in llms-full.txt and registry.json.