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

# Chat with your workspace

> Ask an agent that has your whole knowledge base as context — and let it record what you decide.

**Chat** is a [dispatch](/core/agents) fired *now*: you send a message, an
agent works your [workspace](/concepts#workspace) — every meeting, email, and note already compiled there
— and answers, streaming back live. This is not retrieval over a document store; the workspace is a
maintained Markdown knowledge base the agent reads and edits like a developer in a repo.

## Ask a question

The endpoint returns **Server-Sent Events**:

```bash theme={null}
curl -N -X POST "$API_BASE/agent/chat" \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"prompt":"What did we agree with Acme on pricing, and what is still open?"}'
```

Each `data:` line is one frame:

| frame           | fields                     | meaning                                       |
| --------------- | -------------------------- | --------------------------------------------- |
| `message-delta` | `text`                     | a chunk of the streamed reply                 |
| `tool-call`     | `tool`, `args`, `callId`   | the agent invoked a tool                      |
| `tool-result`   | `callId`, `ok`, `summary`  | that tool returned                            |
| `commit`        | `sha`                      | the agent wrote to the workspace (git commit) |
| `rejected`      | `violations`               | a write was blocked by governance             |
| `done`          | `reply`, `sessionId`, `ok` | turn finished                                 |

## Record a decision (trusted write)

Because input from you is **trusted**, the same agent can write — record a decision, update an entity,
draft a doc. Just ask:

```bash theme={null}
curl -N -X POST "$API_BASE/agent/chat" \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"prompt":"Record that Acme renewed at the Q3 pricing, effective July 1."}'
```

Watch for a `commit` frame — `git` is the durable state and the undo.

## Continue a conversation

Pass `session` to keep context across turns; reset or inspect history:

```bash theme={null}
# continue a session
-d '{"prompt":"And who owns the follow-up?","session":"<sessionId>"}'

curl -X POST "$API_BASE/agent/chat/reset" -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" -d '{"session":"<sessionId>"}'      # → {"ok":true}

curl -H "X-API-Key: $API_KEY" "$API_BASE/agent/sessions"             # list sessions
curl -H "X-API-Key: $API_KEY" "$API_BASE/agent/sessions/<id>/history"
```

## Build a cross-source briefing

The agent grounds its answer in everything the workspace holds, so you can ask it to pull a topic together
across past meetings and emails:

```bash theme={null}
-d '{"prompt":"Brief me on the Acme account: every meeting and email, the open decisions, and the next step."}'
```

This is the **knowledge agent** pattern — the output is anchored in
accumulated context, and each run leaves the workspace a little more complete.

<Note>
  A `rejected` frame means governance blocked the write. Trusted chat may write; untrusted triggers (email,
  web) are propose-only — see [Governance](/architecture/governance) and
  [Troubleshooting](/troubleshooting#agent-write-was-rejected).
</Note>