{a.isImage && a.previewUrl && (
)}
{a.name}
))}
```
**Signature:**
```typescript
addAttachment(files: File | File[] | FileList): void
```
**PendingAttachment Type:**
```typescript
interface PendingAttachment {
id: string // Temporary ID
file: File // Original file object
name: string
mimeType: string
size: number
isImage: boolean
previewUrl: string | null // Object URL for image preview
width?: number
height?: number
}
```
---
### removeAttachment
Remove a pending attachment before sending.
```tsx
const { removeAttachment, attachments } = useThread()
```
**Signature:**
```typescript
removeAttachment(id: string): void
```
---
### clearAttachments
Remove all pending attachments.
```tsx
const { clearAttachments, attachments } = useThread()
{attachments.length > 0 && (
)}
```
**Signature:**
```typescript
clearAttachments(): void
```
---
### addFiles
Upload files to the thread's filesystem. Files are uploaded immediately and stored persistently.
**Use this for documents/files that should be stored on the thread but NOT sent directly to the LLM.**
```tsx
const { addFiles, files, getPreviewUrl } = useThread()
// Upload files to filesystem
addFiles(fileInput.files)
// Display uploaded files
{files.map(f => (
{f.isImage && })
}
{f.name}
{f.status} {/* 'uploading' | 'ready' | 'committed' | 'error' */}
))}
```
**Signature:**
```typescript
addFiles(files: File[] | FileList): void
```
**ThreadFile Type:**
```typescript
interface ThreadFile {
id: string
name: string
mimeType: string
size: number
isImage: boolean
localPreviewUrl: string | null
status: 'uploading' | 'ready' | 'committed' | 'error'
error?: string
path?: string
width?: number
height?: number
messageId?: string
}
```
---
### removeFile
Remove a pending file upload (cannot remove already committed files). A file that is still uploading has its HTTP request aborted, and it never reports `ready` or `error` afterwards.
```tsx
const { removeFile } = useThread()
```
---
### File URL Helpers
```tsx
const { getFileUrl, getThumbnailUrl, getPreviewUrl } = useThread()
// Full file URL (for download/viewing)
const url = getFileUrl(file)
// Thumbnail URL (for images)
const thumb = getThumbnailUrl(file)
// Preview URL (smart - uses local preview for pending, thumbnail for committed)
const preview = getPreviewUrl(file)
```
---
### stopExecution
Stop the current agent execution. Calling it when nothing is running is safe: the request succeeds and the thread is left unchanged.
```tsx
const { stopExecution } = useThread()
```
---
### deleteMessage
Delete a message from the thread. The message is optimistically removed from the UI immediately. If the server request fails, the message is restored.
```tsx
const { deleteMessage, messages } = useThread()
async function handleDelete(messageId: string) {
try {
await deleteMessage(messageId)
} catch (err) {
console.error('Failed to delete:', err)
}
}
// Usage
{messages.map(msg => (
{msg.content}
))}
```
**Signature:**
```typescript
deleteMessage(messageId: string): Promise
{workblock.workItems.map((item) => (
)
}
```
## TypeScript Support
The package is written in TypeScript and includes full type definitions.
```tsx
import type {
// Core types
Message,
WorkMessage,
WorkItem,
ThreadMessage,
Thread,
// Configuration
AgentBuilderConfig,
GetMessagesOptions,
SendMessagePayload,
ThreadProviderOptions,
// Attachment types
PendingAttachment,
AttachmentPayload,
AttachmentRef,
ThreadFile,
// Run status
ThreadStatus,
ThreadRunState,
// WebSocket events
MessageDataEvent,
MessageChunkEvent,
ErrorEvent,
ThreadEvent,
MessageStreamEvent,
LogDataEvent,
CustomEvent,
StoppedByUserEvent,
LogStreamEvent,
// WebSocket callbacks
MessageWebSocketCallbacks,
LogWebSocketCallbacks,
} from "@standardagents/react"
// Connection status type
import type { ConnectionStatus } from "@standardagents/react"
```
### Message Type
```typescript
interface Message {
id: string
role: "system" | "user" | "assistant" | "tool"
content: string | null
name?: string | null
tool_calls?: string | null // JSON array
tool_call_id?: string | null
log_id?: string | null
created_at: number // microseconds
request_sent_at?: number | null
response_completed_at?: number | null
status?: "pending" | "completed" | "failed"
silent?: boolean
tool_status?: "success" | "error" | null
reasoning_content?: string | null
reasoning_details?: string | null // JSON array
parent_id?: string | null
depth?: number
attachments?: string | AttachmentRef[] | null
}
```
HTTP message reads and `message_data` frames carry attachment arrays. The string form in the type is tolerance for older runtimes, whose frames could carry the stored JSON string. Use `parseAttachments(message)` when rendering SDK state.
## Complete Example
The example creates a thread with `AgentBuilderClient.createThread()` and then mounts `ThreadProvider` for that thread. Set `AGENT_ID` to the name of an agent in your project. It reads `runStatus` to disable the input while a run is active.
### View Complete Chat Interface Example with Image Attachments
```tsx
import { useState } from "react"
import type { ChangeEvent } from "react"
import {
AgentBuilderClient,
AgentBuilderProvider,
ThreadProvider,
useThread,
useThreadId,
parseAttachments,
} from "@standardagents/react"
import type { ThreadMessage, Message, WorkMessage } from "@standardagents/react"
const ENDPOINT = "/api"
// Use the name of an agent in your project
const AGENT_ID = "support_agent"
const client = new AgentBuilderClient(ENDPOINT)
async function createThread(): Promise
{item.type === "tool_call" ? `Calling ${item.name}...` : item.content}
))}
Status: {status} {loading && "(loading...)"}
{attachments.map((a) => (
)}
{a.isImage && a.previewUrl && (
)}
{a.name}
))}
setInput(e.target.value)}
onKeyDown={(e) => e.key === "Enter" && handleSend()}
disabled={isRunning}
placeholder="Type a message..."
/>
{isRunning ? (
) : (
)}
{messages.map((msg) => {
if ("type" in msg && msg.type === "workblock") {
return
)
}
function MessageAttachments({ message }: { message: Message }) {
const threadId = useThreadId()
const parsed = parseAttachments(message)
return (
{message.content}
{message.attachments &&
)
})}
{parsed.map((a) => (
))}
)
}
function WorkBlock({ block }: { block: WorkMessage }) {
return (
{block.workItems.map((item) => (
)
}
```
## Next Steps
- [Core Concepts](/docs/core-concepts/agents)
Learn about agents, prompts, and tools
* [Architecture](/docs/introduction/architecture)
How the backend framework works
## Reconnect recovery
A thread provider reads the newest message page after a socket reconnect.
`preload` controls the initial history reads.
When `preload` is enabled, a snapshot after the first socket open closes the initial subscription gap.
Recovery also reads history when `preload` is false.
Recovery runs in the background.
Snapshot results preserve in-flight events and optimistic mutations.
Thread switches invalidate pending history responses.
Deletions reconcile within the newest page window.
Older cached rows outside that window remain until history is read again.
Thread providers adapt a framework-free `ThreadSessionStore` from `@standardagents/client`. The store owns message history, live reducers, run status, committed files, and optimistic commands. Reconnect recovery runs once in that shared store. Upload queues and display grouping stay in the framework adapter. Socket frame types are available from `@standardagents/client/protocol`.
{item.type === "tool_call" ? (
Tool: {item.name}
) : (
{item.content}
)}
))}