Docyrus Agent

AI-powered conversational agent component with chat, action panel, and trigger modes.

Client Only

Installation

pnpm dlx @docyrus/cli add @docyrus/ui-docyrus-agent

Required Packages(2 packages)

pnpm add ai zod

UI Primitives(9 components)

npx shadcn@latest add avatar badge button input label select switch textarea tooltip

AI Elements(6 components)

npx shadcn@latest add @ai-elements/conversation @ai-elements/message @ai-elements/prompt-input @ai-elements/reasoning @ai-elements/suggestion @ai-elements/tool

Usage

Chat Mode

The default chat interface with message history, streaming responses, reasoning steps, tool calls, and suggestions.

import { useChat } from 'ai/react';

import {
  DocyrusAgent
} from '@/components/docyrus/docyrus-agent';
import type {
  AgentProfile,
  AgentMessagePayload
} from '@/components/docyrus/docyrus-agent';

const agent: AgentProfile = {
  name: 'My Assistant',
  description: 'AI-powered helper',
  avatar: { color: '#6366f1', name: 'MA' }
};

function ChatExample() {
  const { messages, status, append, stop } = useChat({
    api: '/api/chat'
  });

  const handleSend = (payload: AgentMessagePayload) => {
    void append({ role: 'user', content: payload.text });
  };

  return (
    <DocyrusAgent
      mode="chat"
      agent={agent}
      messages={messages}
      chatStatus={status}
      onSendMessage={handleSend}
      onStopGeneration={stop}
      allowAttachments
      suggestions={['Summarize this document', 'Draft an email']}
    />
  );
}

Trigger Mode

Compact card with inline input that opens a dialog for the full chat experience.

import {
  DocyrusAgentTrigger
} from '@/components/docyrus/docyrus-agent';

<DocyrusAgentTrigger
  agent={agent}
  messages={messages}
  chatStatus={status}
  onSendMessage={handleSend}
  onStopGeneration={stop}
  dialogContainer="sheet"
  dialogSide="right"
  dialogSize="lg"
/>

Action Panel Mode

Pre-defined actions with parameter forms — useful for structured agent workflows (e.g. "Generate Report", "Send Email").

import type { AgentAction, AgentActionPayload } from '@/components/docyrus/docyrus-agent';

const actions: AgentAction[] = [
  {
    id: 'summarize',
    label: 'Summarize Document',
    description: 'Create a concise summary',
    params: [
      { name: 'length', label: 'Length', type: 'select', options: [
        { label: 'Short', value: 'short' },
        { label: 'Medium', value: 'medium' },
        { label: 'Detailed', value: 'detailed' }
      ]}
    ]
  },
  {
    id: 'translate',
    label: 'Translate',
    description: 'Translate text to another language',
    params: [
      { name: 'text', label: 'Text', type: 'textarea', required: true },
      { name: 'language', label: 'Target Language', type: 'text', placeholder: 'e.g. Turkish' }
    ]
  }
];

const handleExecute = (payload: AgentActionPayload) => {
  console.log('Action:', payload.actionId, 'Params:', payload.params);
};

<DocyrusAgent
  mode="action-panel"
  agent={agent}
  actions={actions}
  onExecuteAction={handleExecute}
/>

With Sources

Attach contextual data (documents, JSON schemas, files) to the agent conversation.

import type { AgentSource } from '@/components/docyrus/docyrus-agent';

const sources: AgentSource[] = [
  { type: 'json-schema', label: 'Contact Schema', value: JSON.stringify(schema) },
  { type: 'pdf', label: 'Q4 Report', value: 'https://...', mimeType: 'application/pdf' }
];

<DocyrusAgent
  mode="chat"
  agent={agent}
  sources={sources}
  messages={messages}
  chatStatus={status}
  onSendMessage={handleSend}
/>

API Reference

DocyrusAgent

Prop	Type	Default	Description
`mode`	`'chat' \| 'action-panel' \| 'trigger'`	—	Required. Component display mode.
`agent`	`AgentProfile`	—	Required. Agent identity — name, description, avatar, model.
`messages`	`Array<UIMessage>`	`[]`	Chat message history (from Vercel AI SDK `useChat`).
`chatStatus`	`ChatStatus`	—	Stream status: `'ready'`, `'streaming'`, `'submitted'`, `'error'`.
`actions`	`Array<AgentAction>`	`[]`	Pre-defined actions shown in action panel mode.
`sources`	`Array<AgentSource>`	`[]`	Contextual data attached to the conversation.
`onSendMessage`	`(payload: AgentMessagePayload) => void \| Promise<void>`	—	Called when user sends a message.
`onStopGeneration`	`() => void`	—	Called when user stops generation.
`onExecuteAction`	`(payload: AgentActionPayload) => void \| Promise<void>`	—	Called when user executes an action.
`allowAttachments`	`boolean`	`false`	Show file attachment button in chat input.
`acceptFileTypes`	`string`	—	Accepted file MIME types (e.g. `'image/*,.pdf'`).
`suggestions`	`Array<string>`	`[]`	Quick-reply suggestions shown in empty state.
`emptyState`	`ReactNode`	—	Custom empty state. Defaults to agent name + icon.
`showMessageActions`	`boolean`	`true`	Show copy button on assistant messages.
`className`	`string`	—	Additional CSS classes.

DocyrusAgentTrigger

Extends all DocyrusAgent props (except mode) with:

Prop	Type	Default	Description
`open`	`boolean`	—	Controlled open state.
`onOpenChange`	`(open: boolean) => void`	—	Called when dialog open state changes.
`dialogContainer`	`'modal' \| 'sheet' \| 'drawer'`	`'sheet'`	Dialog container type.
`dialogSide`	`'left' \| 'right' \| 'top' \| 'bottom'`	`'right'`	Sheet/drawer side.
`dialogSize`	`'sm' \| 'default' \| 'lg' \| 'xl' \| 'full'`	`'lg'`	Dialog size.

Components

Component	Description
`DocyrusAgent`	Main component — renders chat or action panel based on `mode` prop.
`DocyrusAgentTrigger`	Compact card with inline input → opens dialog with full chat.
`DocyrusAgentProvider`	Context provider — use to build custom layouts with agent sub-components.
`DocyrusAgentChat`	Full chat layout (header + messages + input).
`DocyrusAgentChatMessages`	Message list with reasoning, tool calls, and suggestions.
`DocyrusAgentChatInput`	Rich input with file attachments and submit/stop button.
`DocyrusAgentHeader`	Agent avatar + name + description header bar.
`DocyrusAgentActionPanel`	Action list → parameter form → execution flow.
`DocyrusAgentActionList`	Selectable action cards.
`DocyrusAgentActionParams`	Dynamic parameter form for selected action.

Type Exports

Type	Description
`DocyrusAgentProps`	Props for `DocyrusAgent` component.
`DocyrusAgentTriggerProps`	Props for `DocyrusAgentTrigger` component.
`DocyrusAgentContextValue`	Context value — access via `useDocyrusAgent()` hook.
`AgentProfile`	Agent identity (name, description, avatar, model).
`AgentMode`	`'chat' \| 'action-panel' \| 'trigger'`
`AgentAction`	Action definition with params.
`AgentActionParam`	Individual action parameter definition.
`AgentActionPayload`	Payload sent when executing an action.
`AgentMessagePayload`	Payload sent when sending a message.
`AgentSource`	Contextual data source attached to conversation.
`AgentSourceType`	`'text' \| 'json' \| 'image' \| 'pdf' \| 'json-schema' \| 'file' \| 'custom'`
`ActionPanelView`	`'action-list' \| 'action-params' \| 'executing'`

Type Reference

AgentProfile

Field	Type	Description
`name`	`string`	Agent display name.
`description`	`string`	Short description shown below name.
`avatar`	`{ name?: string; color?: string; icon?: string; image?: string }`	Avatar configuration — color for background, image for custom avatar.
`model`	`string`	AI model identifier (informational).

AgentAction

Field	Type	Description
`id`	`string`	Unique action identifier.
`label`	`string`	Display label for the action card.
`description`	`string`	Short description shown below label.
`icon`	`ReactNode`	Icon displayed on the action card.
`params`	`Array<AgentActionParam>`	Parameters shown in the form when action is selected.
`isDefault`	`boolean`	If true, auto-selects this action on mount.
`opensChat`	`boolean`	If true, switches to chat mode after execution.

AgentActionParam

Field	Type	Description
`name`	`string`	Parameter key in the payload.
`label`	`string`	Display label for the form field.
`type`	`'text' \| 'textarea' \| 'number' \| 'boolean' \| 'select'`	Input type.
`required`	`boolean`	Whether the field is required.
`defaultValue`	`string \| number \| boolean`	Initial value.
`placeholder`	`string`	Placeholder text.
`options`	`Array<{ label: string; value: string }>`	Options for `select` type.
`description`	`string`	Help text shown below the field.

AgentSource

Field	Type	Description
`type`	`AgentSourceType`	Source type — determines how the data is interpreted.
`label`	`string`	Display label for the source badge.
`value`	`string`	Source content or URL.
`mimeType`	`string`	MIME type for file-based sources.
`meta`	`Record<string, unknown>`	Additional metadata.

AgentMessagePayload

Field	Type	Description
`text`	`string`	Message text content.
`files`	`Array<FileUIPart>`	Attached files (from Vercel AI SDK).
`sources`	`Array<AgentSource>`	Context sources included with the message.
`actionId`	`string`	Action ID if message originated from an action.
`actionParams`	`Record<string, string \| number \| boolean>`	Action parameters if from action execution.

AgentActionPayload

Field	Type	Description
`actionId`	`string`	Executed action ID.
`params`	`Record<string, string \| number \| boolean>`	User-provided parameter values.
`sources`	`Array<AgentSource>`	Context sources included with the action.
`customPrompt`	`string`	Additional user prompt text.

Credits

vercel/ai

Docyrus Agent

Credits

On this page