> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Chat & Streaming

> Send messages, stream replies, and read tool cards in the Desktop app

Every reply streams live from your local agent — text, reasoning, tool cards, and usage all arrive as typed events over `127.0.0.1`.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent

agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant.",
)
# The Desktop app streams this agent's reply token-by-token.
agent.start("Write a haiku about the sea", stream=True)
```

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    You[👤 You] --> Msg[💬 Message]
    Msg --> Engine[🧠 Engine]
    Engine --> Stream[📡 SSE Events]
    Stream --> Turn[✅ Rendered Turn]

    classDef you fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef msg fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef engine fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef stream fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef turn fill:#10B981,stroke:#7C90A0,color:#fff

    class You you
    class Msg msg
    class Engine engine
    class Stream stream
    class Turn turn
```

## Quick Start

<Steps>
  <Step title="Send your first message">
    Type in the composer and press `Enter`. The reply streams in as the agent produces it.
  </Step>

  <Step title="Watch the events render">
    Text, a live reasoning panel, tool cards, and a usage line all appear in the same turn as they stream.
  </Step>

  <Step title="Act on the turn">
    Hover a turn to **Copy**, **Regenerate**, **Fork**, or **Delete** it.
  </Step>
</Steps>

***

## How It Works

The engine sends Server-Sent Events on `POST /chat`. Each event carries a `msg_id` so the client can address a specific message rather than assuming the last one is live.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant You as 👤 You
    participant App as 🌐 App
    participant Engine as 🧠 Engine
    participant Agent as 🤖 Agent

    You->>App: type message + Enter
    App->>Engine: POST /chat (prompt)
    Engine->>Agent: agent.start(stream=True)
    Agent-->>Engine: chunks
    Engine-->>App: start / delta / tool_call / usage / end
    App-->>You: streamed turn
```

Every event the stream emits (from `engine/server.py`):

| Event              | Rendered as                                                                |
| ------------------ | -------------------------------------------------------------------------- |
| `start`            | New assistant turn container                                               |
| `delta`            | Streamed text into the current turn                                        |
| `reasoning`        | Live "Thinking… Xs" panel (collapses to "Thought for Xs")                  |
| `tool_call`        | Tool card (running dot)                                                    |
| `tool_drafting`    | Argument preview inside a tool card                                        |
| `tool_result`      | Tool card result pane (tail-truncated with **Show all** + **Copy output**) |
| `approval_request` | Approval card (Allow / Always allow / Deny)                                |
| `usage`            | Chars, seconds, time-to-first-token under the reply                        |
| `cancelled`        | "Stopped" indicator                                                        |
| `error`            | Typed error card — `auth` / `rate_limit` / `empty` / `internal`            |
| `end`              | Finalizes the turn                                                         |

<Note>
  A stream that yields nothing is reported as an `empty` error, not a blank answer — silence is treated as a failure.
</Note>

***

## Capabilities

<AccordionGroup>
  <Accordion title="Reasoning panel">
    When the model emits reasoning, a live "Thinking… Xs" panel shows it and collapses to "Thought for Xs" when the turn ends. Toggle it with **Show reasoning** and **Collapse reasoning by default** in Settings.
  </Accordion>

  <Accordion title="Tool cards">
    A `tool_call` opens a card with a running dot; `tool_drafting` previews the arguments; `tool_result` fills the result pane. Long output is tail-truncated with **Show all** and **Copy output**.
  </Accordion>

  <Accordion title="Attachments">
    Drag-drop or use the **+** button. Chips show each file's size. Limits: **2 MB max**, up to **5 files**, each clipped to **100 kB** of text before it is sent. Long pastes condense into an attachment instead of filling the context.
  </Accordion>

  <Accordion title="Cancel, regenerate, fork">
    **Stop** cancels a live run — the client is told explicitly with a `cancelled` event rather than inferring it from silence. Per-turn hover actions cover **Copy**, **Regenerate**, **Fork** (`POST /fork/{cid}/{idx}`), and **Delete message** (`DELETE /messages/{cid}/{idx}`).
  </Accordion>
</AccordionGroup>

***

## Keyboard Shortcuts

| Key           | Action                   |
| ------------- | ------------------------ |
| `⌘N`          | New chat                 |
| `⌘K`          | Search all conversations |
| `⌘,`          | Open settings            |
| `Enter`       | Send                     |
| `Shift+Enter` | Newline                  |
| `Esc`         | Close overlay            |

***

## Related

<CardGroup cols={2}>
  <Card title="Approvals & Safety" icon="shield-check" href="/docs/features/desktop/approvals">
    How tool calls are approved before they run
  </Card>

  <Card title="Conversations & Search" icon="magnifying-glass" href="/docs/features/desktop/conversations">
    Fork, delete, projects, and `⌘K` search
  </Card>
</CardGroup>