ViteHub is still experimental. Expect bugs and breaking changes.

Chat

Add chat-oriented Agent Trigger behavior and Chat History state requirements.

chat() adds chat-oriented runtime behavior to an Agent Definition. It contributes a chat.message Agent Trigger, optional Chat Platform Adapter webhooks, Chat History state requirements, and a chat finish extension.

Installation

Import the Capability factory from -hub/agent/capabilities and add it to defineAgent({ capabilities }). Use the configuration example below as the starting point, then tighten modes, policies, stores, and providers for the Agent boundary.

What it adds

The Chat Capability turns message-shaped input into Agent Invocations and exposes the trigger to DevTools. When adapters are configured, the Agent Package can infer Chat Webhook Routes for supported platform events.

Configuration

Attach chat() when a chat surface should call the Agent through the Agent Trigger API. The application UI or platform adapter remains the trigger consumer.

server/agents/support.ts

import { defineAgent } from '@vite-hub/agent'
import { chat } from '@vite-hub/agent/capabilities'

export default defineAgent({
  driver: { model },
  capabilities: [
    chat(),
  ],
})

Runtime behavior

chat() registers the chat.message trigger with ui-message[] input and ui-message-stream output. It prepares Chat History state when available, records chat context, and provides chat finish data after the Agent Invocation completes.

Requirements

Chat History state is optional in local development but needs an Agent State Provider when the deployed stack requires durable sessions or concurrency coordination. External Chat Platform Adapters remain explicit application dependencies.

Driver support

Agent Driver	Support
Model-backed	Receives message-shaped input and can stream chat output through the model-backed path.
Harness-backed	Receives the prepared invocation input and chat context; harness-specific chat behavior depends on the harness adapter.
Custom-run-backed	Receives the chat trigger input and context; `driver.run` owns the response shape.

Inspect and verify

Open Agent DevTools and confirm the Agent exposes a chat.message trigger. Send one DevTools message and verify the invocation origin, Chat Session behavior, and finish extension in the run details.

When adapters are configured, inspect generated webhook registrations for the expected platform names and route metadata.

Options

Option	Type	Default	Description
`platforms`	`Record<string, Adapter> \| resolver`	none	Chat Platform Adapters used to infer webhook registrations.
`webhooks`	`Record<string, webhook \| webhook[] \| false>`	inferred	Explicit Chat Webhook registrations by platform.
`hooks`	`AgentChatEventHooks`	none	Chat event hooks such as `onDirectMessage`.
`event`	`"directMessage"`	none	Chat event binding hint.
`history`	`boolean \| "none" \| { source: "thread"; maxMessages?: number }`	inherited	Chat History selection for message input.
`sessions`	`boolean \| AgentChatSessionOptions`	inherited	Chat Session behavior, including `strategy`, `idleTimeoutMs`, and `metadataKey`.
`state`	`AgentChatStateResolver`	runtime state	Chat State adapter override.
`stream`	`boolean`	inherited	Whether the chat trigger should stream output.
`concurrency`	`"drop" \| "parallel" \| "queue" \| "reject" \| string`	inherited	Message concurrency behavior.
`lockScope`	`"agent" \| "channel" \| "thread" \| string`	inherited	Scope used for message locks.
`fallbackStreamingPlaceholderText`	`string \| null \| function`	inherited	Placeholder text while streaming starts.
`errorFallbackText`	`string \| null \| function`	inherited	Fallback message when chat handling fails.

Reference

Agent triggers
chatTitle()
chatSummary()
Source: packages/agent/src/chat-trigger.ts