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

# Overview

> Learn how to build and run agents.

An agent is an LLM-powered worker that can reason about a request, choose tools, use memory, read files, and keep going until it has an answer or has completed the task.

Use an agent when the path must vary at runtime: answering a support question, researching an issue, drafting a reply, or deciding which tool to call next. If the work follows a known sequence, prefer a [workflow](/docs/learn/workflows/overview); it can still use an agent or `promptLlm()` for the steps that need judgment.

## Example requests

Ask your coding agent to build an agent, the tools it should use, and where people should interact with it.

> "Build a support agent that answers product questions from our docs, checks customer details, and drafts replies in our support tone."

> "Create an agent that watches for tagged Slack messages, investigates the topic, and replies with a sourced summary."

> "Build a data agent that can query our warehouse and answer questions from a #data Slack channel."

## How agents are defined

In Keystroke, agents live in your project code under `src/agents/`. Each file default-exports a `defineAgent()` definition, and the runtime discovers it when you run or deploy the project.

```ts theme={null}
import { defineAgent } from "@keystrokehq/keystroke/agent";
import { defineSandbox } from "@keystrokehq/keystroke/sandbox";

export default defineAgent({
  slug: "support",
  name: "Support",
  description: "Answers product questions using bundled docs and a support skill.",
  systemPrompt:
    "You are helpful support. Read /workspace/agent/support-instructions.md before answering.",
  model: "openai/gpt-5.6-sol",
  skills: ["support"],
  sandbox: defineSandbox({ files: "support" }),
});
```

## What agents can use

Agents are useful when a task needs judgment, language understanding, tool use, or multi-turn context.

| Capability           | How it works                                                                                                                   |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **Instructions**     | `systemPrompt` tells the model how to behave                                                                                   |
| **Models**           | `model` is an exact catalog id (`vendor/model-id`); optional `thinkingLevel`. See [Models](/docs/learn/agents/build-agents#models). |
| **File system**      | Each session gets a `/workspace` with a built-in file system and bash (code execution) tools                                   |
| **Web search**       | Built-in `web_search` and `web_fetch` tools when a web provider is configured                                                  |
| **Browser use**      | Coming soon — native browser automation for clicking, forms, and multi-step web flows                                          |
| **Tools**            | Attach custom tools, MCP tools, subagents, and workflows as tools                                                              |
| **Skills and files** | Attach project skills from `src/skills/` and static files from `src/files/`                                                    |
| **Company Brains**   | Search and read shared organization knowledge on demand. [Early access by request](/docs/learn/settings/company-brain).             |
| **Memory**           | Sessions and persistent memory are enabled by default unless disabled                                                          |
| **Sandbox**          | A built-in sandbox environment for using CLIs and more advanced code execution                                                 |
| **Self-scheduling**  | Built-in tools let an agent schedule its own future or recurring runs (ephemeral triggers)                                     |

Agents are one of the main primitives in a project, alongside [workflows](/docs/learn/workflows/overview), [actions](/docs/learn/actions/overview), and [triggers](/docs/learn/triggers/overview). Actions are the usual way to give an agent reliable capabilities. Workflows are the usual way to orchestrate several deterministic steps around one or more agent calls.

## How to run agents

You can use an agent from the CLI, API, a workflow, another agent, or an external gateway like Slack. You can also run an agent automatically by attaching a [trigger](/docs/learn/triggers/overview) (a schedule, webhook, or poll), and agents can even schedule their own runs with [ephemeral triggers](/docs/learn/agents/build-agents#ephemeral-triggers).

```bash theme={null}
keystroke agents prompt support --message "What is Keystroke?"
```

Open **Agents** in the web app to see the agents available in your active project. Open **History** and filter to **Agent** when you want to inspect sessions after they run.

## Running deployed agents

Deploy your project, then prompt the agent against the deployed project:

```bash theme={null}
keystroke deploy --project <slug>   # or --filter agents/support
keystroke agents prompt support --message "Hi"
```

## Next steps

<CardGroup cols={2}>
  <Card title="Build agents" href="/docs/learn/agents/build-agents">
    Define agents with tools, models, skills, files, and runtime options.
  </Card>

  <Card title="Run agents" href="/docs/learn/agents/run-agents">
    Prompt agents from the CLI and inspect sessions.
  </Card>

  <Card title="Triggers" href="/docs/learn/triggers/overview">
    Run agents on a schedule, webhook, or poll.
  </Card>

  <Card title="Agent runs" href="/docs/learn/logs/agent-runs">
    Review conversation history, tool calls, traces, and errors.
  </Card>
</CardGroup>