# Add an assistant

Source: /docs/building/add-an-assistant.md

Add an assistant when a conversation helps users explore data, understand a result, or carry out an operation. Give it a specific job and the data and tools needed to do it.

Your coding agent implements the assistant resource. This runtime assistant is what app users talk to; it is separate from Codex, Claude Code, or the harness building your project.

## Choose what it can read and do [#choose-what-it-can-read-and-do]

Define one `Agent` declaration in the resource's Python source:

```python
from vortexify import Agent, AgentCapabilities, ApiRunner, Table


agent = Agent(
    prompt=(
        "Help users understand orders. Use available data and tools. "
        "Ask for missing identifiers and explain failed requests without inventing results."
    ),
    context=[Table("shop.orders")],
    tools=[ApiRunner("lookup_order")],
    capabilities=AgentCapabilities(sql_analysis=True),
)
```

This assumes that `shop.orders` and `lookup_order` exist. Context can reference synced tables and transform outputs. `ApiRunner` exposes a backend API as a tool; inspect that API's inputs, response, and side effects before describing it in the prompt. An assistant that only explains records needs different tools from one that changes them.

Enable SQL analysis when it needs to investigate its declared tables. Enable chart generation when it needs charts from completed analysis results. The Python context declaration does not accept database connections or secrets; use a scoped API tool for database-backed behavior.

Declaring context does not run a sync or prepare a missing output. Ensure the data is ready and API tool runtimes are usable. In preview, the assistant uses committed agent/API versions and preview data. Published execution uses deployed definitions and production data. Test in the mode the app will use.

## Attach supporting documents [#attach-supporting-documents]

Attach procedures or reference material when the assistant needs information beyond tables:

```sh
vortexify upload file ./operations.md --resource-type agent --resource operations_assistant --wait
vortexify commit --type agent --resource operations_assistant
```

Create and implement the agent before attaching files. PDF, TXT, and Markdown attachments supply document-search and preview tools through the saved agent version. They are managed attachments rather than Python context declarations. Upload completion and the subsequent commit matter: a document attached to a connector is not automatically available to this assistant.

## Connect the conversation to the app [#connect-the-conversation-to-the-app]

The React conversation manager consumes the stream, manages history and selection, and exposes text, tool progress, and errors for rendering. Your app supplies the message and, optionally, a bounded snapshot of the current screen.

There are two kinds of action:

| Action | Where it executes | Example |
| --- | --- | --- |
| Backend API tool | Backend runtime | Look up an order or save a decision |
| Frontend action | Browser handler | Open a record or change the selected view |

Frontend actions send their names, descriptions, parameter schemas, and optional timeoutMs to the agent; executable handlers stay in React. Each handler returns AgentToolResult ({success, message?, data?}, with message required on failure). The SDK reports results and errors to the backend, and the agent waits before continuing. A timeout means execution outcome is unknown. Register page context with useAgentView so the agent receives an initial snapshot and can request fresh context through get_current_view_context.

Persisted conversation history and an in-progress stream are different states. Handle loading, tool activity, failure, and conversation selection. Canceling local consumption does not stop an active backend turn or undo effects already started.

## Verify the whole interaction [#verify-the-whole-interaction]

Save the declaration before trying it from your app. Ask a question that requires the intended data or tool, inspect the response and tool activity, and check the underlying API run or data when needed. The saved tool results show which dependencies actually ran and what they returned.

In the platform, open the agent's **Conversations** view to inspect saved messages and tool activity, **Files** for document previews, and **Code** for its declaration. The resource **Overview** shows upstream and downstream connections. Use your app to verify the conversation interface and browser actions.

> **Platform screenshot placeholder:** The agent Overview connections and a saved conversation tool result, paired with the matching interaction in the app. Capture the mounted Conversations view.

If the assistant should visualize its answers, follow [analysis charts](/docs/reference/react/analysis-charts) for the full query-to-chart flow and a React renderer.

Next: [Publish your app](/docs/building/publish-your-app). See [Python agents](/docs/reference/python/agents) and [React conversations and actions](/docs/reference/react/conversations-and-actions) for the exact contracts.