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

# Using Agents

> Start a session, watch tools run, approve dangerous operations, and drive a tesslate-agent instance to get work done

<img src="https://mintcdn.com/tesslate/VT6tbZolrCfpx26M/images/opensail-banner.png?fit=max&auto=format&n=VT6tbZolrCfpx26M&q=85&s=66579c47537b3464fb65b229cc9ab0fd" alt="Tesslate OpenSail" width="4712" height="1612" data-path="images/opensail-banner.png" />

## What an agent is in OpenSail

An agent in OpenSail is a running `tesslate-agent` instance, bound to a project workspace, that drives an LLM in a streaming tool-use loop. Every agent is a composition of four things:

<CardGroup cols={2}>
  <Card title="A system prompt" icon="file-lines">
    The personality, role, and rules of engagement. Co-authored by the creator.
  </Card>

  <Card title="A tool registry" icon="wrench">
    The built-in tool set (33 tools across 8 categories) plus any MCP connectors and view-scoped tools.
  </Card>

  <Card title="A skill catalog" icon="book">
    Lightweight skill descriptions injected at session start. Full bodies fetched on demand.
  </Card>

  <Card title="A model preference" icon="microchip">
    A LiteLLM-routed model for each session, with BYOK support and per-tier defaults.
  </Card>
</CardGroup>

The active agent runner lives in the `packages/tesslate-agent` submodule and is invoked by the orchestrator worker through `tesslate_agent_adapter.py`. The agent is model-agnostic, stateless between calls, and streams every step back to the UI as it happens.

<Info>
  For the authoritative, per-tool reference of all 33 built-in tools (parameters, edit-mode gating, return shape, quirks), see the tesslate-agent reference: [https://github.com/TesslateAI/tesslate-agent/blob/main/docs/DOCS.md](https://github.com/TesslateAI/tesslate-agent/blob/main/docs/DOCS.md).
</Info>

## Starting a session

<Steps>
  <Step title="Open a project">
    Open any project from your dashboard. The chat panel opens on the right and the agent picks up the project workspace, open files, and git state automatically.
  </Step>

  <Step title="Pick an agent">
    The agent selector at the top of the chat shows every agent installed on your account plus the project's default. Any agent published to the marketplace that you have installed is available here.
  </Step>

  <Step title="Pick an edit mode">
    The edit-mode toggle controls how much autonomy the agent has: Ask Before Edit (default), Allow All Edits, or Plan Mode. Mode is enforced at the tool registry level, not the system prompt, so every agent respects it.
  </Step>

  <Step title="Describe the task">
    Type in natural language. Reference files by path. Drop in screenshots, error messages, or attached files. The agent reads the project tree, the git status, any `TESSLATE.md`, and the skill catalog before its first model call.
  </Step>

  <Step title="Watch it work">
    Each tool call streams into the transcript as a separate card: the tool name, arguments, and result. Text the agent emits between tool calls streams inline. The session persists progressively to the database, so you can close the tab and come back later without losing the trajectory.
  </Step>
</Steps>

## The conversation pattern

The agent runs an iteration loop until the model stops asking for tool calls:

```
loop:
  pre-flight compaction if context >= 80% of window
  model.chat_with_tools(messages, tools)
  if response text: stream it
  if no tool calls: emit complete and return
  run tool calls
  append tool results to history
  emit agent_step
```

You see streamed text, tool cards, and (on context pressure) a compaction marker. When the loop terminates with no more tool calls, you get a `complete` event and the chat is ready for your next message.

### Approval modes

Dangerous tools (file writes, shell commands, web fetch) are gated at the registry level by the active edit mode:

<Tabs>
  <Tab title="Ask Before Edit">
    Default and safest. Reads proceed silently. Writes and shell commands pause the agent and show an approval card with Allow Once, Allow All, and Stop. Allow All for write tools flips the session into Allow All Edits; Allow All for shell/web tools persists per tool category only.
  </Tab>

  <Tab title="Allow All Edits">
    Full autonomy. Every tool executes immediately. Use this once you trust the agent for a given task.
  </Tab>

  <Tab title="Plan Mode">
    Read-only. Writes, shell commands, and any mutating tool are blocked at the registry level. The agent is forced to produce a detailed plan as text rather than execute it. Switch into Plan Mode before risky migrations, refactors, or production work to dry-run the approach.
  </Tab>
</Tabs>

<Warning>
  Approvals persist only for the current chat session. Clearing the chat or starting a new one resets all Allow All decisions.
</Warning>

### Attaching files and context

* Drag and drop files into the chat input to attach them. Images are viewable by the agent via `view_image` (supported on vision-capable models).
* The architecture panel is shared state: nodes and edges you add show up to the agent on its next iteration, and the agent's graph edits show up on your canvas in real time.
* Long-running sessions compact older messages automatically when the token estimate crosses 80% of the model's window. Multi-hour runs do not hit a wall.

## Running, interrupting, resuming

<AccordionGroup>
  <Accordion icon="play" title="Cancel a running task">
    Click Stop in the chat input while the agent is working. A cancellation signal is published to the worker, which checks between iterations and stops on the next loop boundary. Partial work is preserved in the transcript.
  </Accordion>

  <Accordion icon="rotate-right" title="Resume after a disconnect">
    Agent steps persist to the database as they happen. Close the tab, lose network, or have the worker pod restart: on reconnect the transcript rehydrates from the stored trajectory and the WebSocket resubscribes to the Redis event stream. Any events you missed replay before live streaming picks up.
  </Accordion>

  <Accordion icon="clock-rotate-left" title="Rollback a change">
    Every file write is recorded with a prior snapshot. Use `file_undo` to revert individual files, or use the workspace snapshot timeline to roll the entire project back to any point in the session. Up to 5 snapshots are retained per project.
  </Accordion>

  <Accordion icon="comments" title="Refine iteratively">
    Agents work best when steered. After a tool card lands, you can interject with a short correction ("use Tailwind, not CSS modules") without waiting for the iteration to end. The correction lands in the next model turn.
  </Accordion>
</AccordionGroup>

## Writing prompts that work

<Tabs>
  <Tab title="Be specific">
    Include the file path, the framework, the expected behavior, and any constraints. "Create `src/components/Button.tsx` as a React TS component with `variant`, `size`, and `loading` props, using Tailwind" beats "add a button".
  </Tab>

  <Tab title="Reference existing code">
    Point the agent at a file, component, or pattern already in the project: "style this the same way `FeatureCard` is styled". The agent will read the referenced file and match the pattern.
  </Tab>

  <Tab title="Break up big tasks">
    For multi-hour work, give the agent an ordered plan and let it tick off steps. Agents have planning tools (`update_plan`, `todo_write`, `save_plan`) and will use them to track progress.
  </Tab>

  <Tab title="Paste errors verbatim">
    When debugging, paste the error output exactly. The agent pattern-matches stack traces faster than summaries and will search the codebase for the referenced symbols.
  </Tab>
</Tabs>

## Tool categories at a glance

| Category        | What the agent uses it for                                                                            |
| --------------- | ----------------------------------------------------------------------------------------------------- |
| File operations | Read, write, patch, multi-edit, and undo files in the workspace                                       |
| Shell commands  | One-off `bash_exec`, persistent `shell_open`/`shell_exec` sessions, background processes, Python REPL |
| Navigation      | `glob`, `grep`, and `list_dir` for fast codebase traversal                                            |
| Git             | `git_log`, `git_blame`, `git_status`, `git_diff` inside the container                                 |
| Memory          | Cross-session scratchpad the agent can read and write                                                 |
| Web             | `web_fetch`, `web_search` via Tavily, Brave, or DuckDuckGo                                            |
| Planning        | Todos, plan documents, structured updates                                                             |
| Delegation      | Spawn subagents, wait on them, send messages, close them                                              |

For full parameter lists, gating rules, and return shapes, see the [tesslate-agent reference](https://github.com/TesslateAI/tesslate-agent/blob/main/docs/DOCS.md).

## Troubleshooting

<AccordionGroup>
  <Accordion icon="circle-pause" title="Agent is stuck waiting">
    If you are in Ask Before Edit mode, the agent pauses for approval on the first dangerous tool. Check the chat for a pending approval card. You can also widen the approval scope with Allow All for the tool type.
  </Accordion>

  <Accordion icon="ban" title="Tool calls are blocked">
    Plan Mode blocks writes and shell commands at the registry. Switch modes with the toggle next to the input. API-key scoping can also restrict tools: see `/guides/api-keys` for scope details.
  </Accordion>

  <Accordion icon="arrows-spin" title="Agent is looping">
    The loop terminates when the model stops asking for tools. If it keeps going, cancel, clarify the success criteria, and restart. Consider Plan Mode to force the agent to commit to an approach before executing.
  </Accordion>

  <Accordion icon="credit-card" title="Credit or budget errors">
    If you hit a credit ceiling mid-task, purchase a credit pack or upgrade your tier. See `/guides/billing`. BYOK keys (Pro and Ultra) bypass the credit system entirely.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Customizing Agents" icon="sliders" href="/guides/customizing-agents">
    Build your own agent with a custom system prompt, skills, and MCP bindings
  </Card>

  <Card title="Skills" icon="book" href="/guides/skills">
    Package a reusable capability and attach it to any agent
  </Card>

  <Card title="Connectors (MCP)" icon="plug" href="/guides/connectors-mcp">
    Wire Slack, Gmail, Linear, and more into your agent's tool registry
  </Card>

  <Card title="Model Management" icon="microchip" href="/guides/model-management">
    Pick the right model, BYOK, or self-host with Ollama or vLLM
  </Card>
</CardGroup>