# Docyrus Agent
URL: /docs/web/docyrus/docyrus-agent

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

{/* @custom-mdx */}

**Demo:**

```tsx
'use client';

import { useState } from 'react';

import {
  DocyrusAgent,
  DocyrusAgentActionPanel,
  DocyrusAgentProvider,
  DocyrusAgentTrigger
} from '@docyrus/ui/components/docyrus-agent';
import {
  Tabs,
  TabsContent,
  TabsList,
  TabsTrigger
} from '@docyrus/ui/primitives/ui/tabs';
import { cn } from '@docyrus/ui/primitives/lib/utils';

import { PropControls } from '@/components/prop-controls';
import { useDemoData } from '@/data/docyrus-agent-data';

export function DocyrusAgentDemo() {
  const { props, controls } = useDemoData();
  const [open, setOpen] = useState(false);

  return (
    <div className="w-full">
      <div className="mb-3 flex justify-end">
        <button
          type="button"
          className="inline-flex items-center gap-1.5 rounded-md border border-border bg-background px-3 py-1.5 text-sm font-medium transition-colors hover:bg-accent"
          onClick={() => setOpen(prev => !prev)}>
          <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><path d="M12.22 2h-.44a2 2 0 0 0-2 2v.18a2 2 0 0 1-1 1.73l-.43.25a2 2 0 0 1-2 0l-.15-.08a2 2 0 0 0-2.73.73l-.22.38a2 2 0 0 0 .73 2.73l.15.1a2 2 0 0 1 1 1.72v.51a2 2 0 0 1-1 1.74l-.15.09a2 2 0 0 0-.73 2.73l.22.38a2 2 0 0 0 2.73.73l.15-.08a2 2 0 0 1 2 0l.43.25a2 2 0 0 1 1 1.73V20a2 2 0 0 0 2 2h.44a2 2 0 0 0 2-2v-.18a2 2 0 0 1 1-1.73l.43-.25a2 2 0 0 1 2 0l.15.08a2 2 0 0 0 2.73-.73l.22-.39a2 2 0 0 0-.73-2.73l-.15-.08a2 2 0 0 1-1-1.74v-.5a2 2 0 0 1 1-1.74l.15-.09a2 2 0 0 0 .73-2.73l-.22-.38a2 2 0 0 0-2.73-.73l-.15.08a2 2 0 0 1-2 0l-.43-.25a2 2 0 0 1-1-1.73V4a2 2 0 0 0-2-2z" /><circle cx="12" cy="12" r="3" /></svg>
          Configure
          <svg xmlns="http://www.w3.org/2000/svg" width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" className={cn('transition-transform duration-200', open && 'rotate-180')}><path d="m6 9 6 6 6-6" /></svg>
        </button>
      </div>
      <div
        className={cn(
          'grid transition-[grid-template-rows] duration-300 ease-in-out',
          open ? 'grid-rows-[1fr]' : 'grid-rows-[0fr]'
        )}>
        <div className="overflow-hidden">
          <div className="mb-4 grid gap-6 rounded-lg border border-border bg-muted/30 p-4">
            
          </div>
        </div>
      </div>

      
          
          
        

        

        
          </div>
        

        
      
    </div>
  );
}
```

## Installation

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

**Dependencies:**
- [ai](https://www.npmjs.com/package/ai)
- [zod](https://www.npmjs.com/package/zod)
- [lucide-react](https://www.npmjs.com/package/lucide-react)

## Usage

### Chat Mode

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

```tsx
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 (
    
  );
}
```

### Trigger Mode

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

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

```

### Action Panel Mode

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

```tsx
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);
};

```

### With Sources

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

```tsx
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' }
];

```

## 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. |