Skip to main content
You build an agent by writing a defineAgent() definition in your project. This page starts from the smallest working agent, then serves as the full reference for every option you can configure.

Build a simple agent

You can build a simple agent in just a few steps.
1

Define the agent

An agent needs only three things: a slug, a systemPrompt, and a model. Create a file in src/agents/ that default-exports the definition.
src/agents/support.ts
import { defineAgent } from "@keystrokehq/keystroke/agent";

export default defineAgent({
  slug: "support",
  systemPrompt: "You are a helpful support assistant. Answer concisely.",
  model: "anthropic/claude-sonnet-4.6",
});
The slug is the stable key Keystroke uses for discovery, routes, CLI commands, and history.
2

Deploy it

Ship the project to the platform so the agent runs in the cloud.
keystroke deploy --project <project-slug>
Deploy builds and uploads your project, and the CLI now targets it automatically. See deploy a project for project setup.
3

Use it

Prompt the deployed agent by its slug, or open Agents in the web app.
keystroke agents prompt support --message "Help me understand my bill"
The response includes a sessionId, the messages, and any error. For repeatable checks, add a test that prompts the agent or asserts its definition. You can also use the agent directly from Slack (see external channels). Prefer to iterate without deploying? Run a local server with keystroke dev.
That is a complete, working agent. The rest of this page is the full reference for configuring one.

Configuration reference

Every agent ships with some capabilities out of the box, then accepts options to change those defaults or add more. These capabilities are built in, locally and once deployed, with no configuration:
Built inWhat you getTune it with
WorkspaceEach session gets an isolated /workspace with file and bash (code execution) toolssandbox, mode
Web accessweb_search and web_fetch tools when a web provider is configuredWeb search
MemorySession history plus persistent memory, enabled by defaultmemory
Ephemeral triggersset_trigger and list_triggers tools so the agent can schedule its own runsEphemeral triggers
defineAgent() accepts these options. The required three are all you need to start; the rest are optional.
OptionRequiredWhat it does
slugYesStable key used for discovery, routes, CLI commands, and history
systemPromptYesInstructions given to the model
modelYesExact model id from the catalog in vendor/model-id format. See Models.
nameNoHuman-readable name shown in the platform
descriptionNoShort description shown in the platform
thinkingLevelNoReasoning setting. See Models.
toolsNoActions, subagents, workflows, or MCP tools. See Tools.
skillsNoProject skill folders. See Skills and files.
sandboxNoWorkspace file layout and execution mode (defineSandbox({ files, mode })). See Sandboxes.
memoryNoMemory options, or false to disable. See Memory.
Agent definitions do not have a credentials option. Credentials are declared on the actions an agent uses, then resolved when those tools run.

Tools

Tools allow agents to do real work: look up a customer, send an email, run a workflow, or call another agent. You list the tools an agent is allowed to use in tools. Tools come in a few forms:
Tool typeWhat it isAdd it with
ActionOne of your functions, or an action exported by an integrationtools: [myAction]
SubagentAnother agent, exposed as a callable tooltools: [researcher]
WorkflowA durable, multi-step workflow run as a single tooltools: [refundOrder]
MCP toolTools served by an external MCP serverdefineMcp()

Actions as tools

The most common tool is an action. The same action works as an agent tool or a workflow step; you just add it to tools.
import { defineAgent } from "@keystrokehq/keystroke/agent";
import { lookupCustomer } from "../actions/lookup-customer";

export default defineAgent({
  slug: "support",
  systemPrompt: "Help customers. Use lookupCustomer to find account details.",
  model: "anthropic/claude-sonnet-4.6",
  tools: [lookupCustomer],
});
Integration packages also export actions. Import only the ones the agent should be allowed to use.
import { defineAgent } from "@keystrokehq/keystroke/agent";
import {
  googlesuperFetchEmails,
  googlesuperSendEmail,
} from "@keystrokehq/googlesuper/actions";

export default defineAgent({
  slug: "secretary",
  systemPrompt: "Help manage Gmail. Confirm ambiguous sends before acting.",
  model: "openai/gpt-5.5",
  tools: [googlesuperFetchEmails, googlesuperSendEmail],
});
Reach for actions for deterministic single-step capabilities, workflows for durable multi-step sequences, subagents for open-ended delegation, and MCP tools when an external server exposes an MCP surface.

Subagents as tools

A subagent is an agent exposed as a tool to another agent. Use one when a parent agent should delegate a specialized task (research, a stronger model, a different tool set) without sharing the whole parent conversation as instructions. Import the agent and add it to the parent agent’s tools. The tool name is the subagent’s slug, and the tool expects a message string parameter.
import { defineAgent } from "@keystrokehq/keystroke/agent";
import researcher from "./researcher";

export default defineAgent({
  slug: "orchestrator",
  systemPrompt:
    "You are an orchestrator. For research tasks, call researcher before answering.",
  model: "anthropic/claude-sonnet-4.6",
  tools: [researcher],
});
Subagent calls appear as tool calls in the parent session, and the child agent creates its own session. Inspect both in run history.

Workflows as tools

A workflow packages a fixed, multi-step sequence, often several actions chained together with durable retries. Import it into tools when you want the agent to trigger that whole sequence as a single, reliable step instead of orchestrating the steps itself.
import { defineAgent } from "@keystrokehq/keystroke/agent";
import refundOrder from "../workflows/refund-order";

export default defineAgent({
  slug: "support",
  systemPrompt:
    "Help customers. To issue a refund, call the refund-order tool with the order ID.",
  model: "anthropic/claude-sonnet-4.6",
  tools: [refundOrder],
});
The tool’s name and parameters are derived from the workflow’s slug and input schema, so you do not declare them by hand. The agent calls it like any other tool, and the workflow runs with its normal durability and step recording. Inspect the workflow run and the agent session together in run history. Choose a workflow tool when the work is a known sequence that should run reliably, and a subagent when the work needs open-ended reasoning.

MCP tools

Model Context Protocol (MCP) servers expose tools over a standard protocol. Point an agent at one with defineMcp(), and every tool that server lists becomes available to the agent.
import { defineAgent, defineMcp } from "@keystrokehq/keystroke/agent";

const deepwiki = defineMcp({
  key: "deepwiki",
  transport: { type: "http", url: "https://mcp.deepwiki.com/mcp" },
});

export default defineAgent({
  slug: "researcher",
  systemPrompt: "Use the DeepWiki tools to answer questions about GitHub repositories.",
  model: "anthropic/claude-sonnet-4.6",
  tools: [deepwiki],
});
Keystroke connects to the server when the agent runs and adds its tools to the agent for that session. Tool names are prefixed with the server key (for example mcp__deepwiki__ask_question) so they never collide with your other tools. For servers that require authentication, declare credentials on the definition. See credentials.
This is the client side of MCP: your agent using an external MCP server. For the reverse, building Keystroke agents, workflows, and triggers from an MCP-capable agent like ChatGPT or Claude, see MCP for agents.

Skills and files

Skills are reusable instructions in src/skills/. Files are static project context in src/files/. Both materialize into the agent workspace before a prompt runs, so the agent can read them like local files.
import { defineSandbox } from "@keystrokehq/keystroke/sandbox";

export default defineAgent({
  slug: "support",
  systemPrompt:
    "Read /workspace/agent/product-guide.md and the support skill before answering.",
  model: "anthropic/claude-sonnet-4.6",
  skills: ["support"],
  sandbox: defineSandbox({ files: true }),
});
With defineSandbox({ files: true }), Keystroke uses src/files/{agentSlug}/. You can also pass a string to use another file set:
export default defineAgent({
  slug: "support",
  systemPrompt: "Read the support handbook before answering.",
  model: "anthropic/claude-sonnet-4.6",
  sandbox: defineSandbox({ files: "support-handbook" }),
});
See project skills and files for the file formats.

Memory

Memory is what lets an agent remember. It is enabled by default and has two parts:
PartWhat it does
Session historyKeeps the messages for one conversation so follow-up prompts have context
Persistent memoryGives the agent a memory tool and a filesystem-backed memory area (MEMORY.md, USER.md, archive notes, and searchable past sessions) stored outside /workspace
Set memory: false for a stateless agent, such as a deterministic classifier or a one-shot extraction agent:
export default defineAgent({
  slug: "one-shot-classifier",
  systemPrompt: "Classify the message and return only the label.",
  model: "anthropic/claude-sonnet-4.6",
  memory: false,
});
Persistent memory is agent-curated: the agent writes and edits USER.md, MEMORY.md, and archive notes itself through the memory tool. You don’t pre-load it from the definition — put stable, author-provided context in the systemPrompt or in files instead. The agent then records what it learns into memory over time. You can pass an options object to tune memory’s limits:
export default defineAgent({
  slug: "support",
  systemPrompt: "Help the user using memory when it is relevant.",
  model: "anthropic/claude-sonnet-4.6",
  memory: {
    memoryCharLimit: 3000,
  },
});
The memory object accepts these options:
OptionDefaultWhat it does
memoryCharLimit2200Char budget for MEMORY.md; the memory tool rejects writes that exceed it
userCharLimit1375Char budget for USER.md; the memory tool rejects writes that exceed it
archiveTocLimit30Max archive notes listed in the memory snapshot
The char limits keep MEMORY.md and USER.md concise (overflow belongs in unbounded archive notes), so the agent gets a clear error and trims when a write would exceed the budget. Continue a conversation by passing the same sessionId to the next prompt. See run agents for session commands.

Models

The model is the LLM that powers the agent’s reasoning and tool use. Keystroke supports hundreds of models from providers like Anthropic, OpenAI, and Google, chosen by ID in vendor/model-id format.
export default defineAgent({
  slug: "researcher",
  systemPrompt: "Research the user's question and cite sources when available.",
  model: "anthropic/claude-sonnet-4.6",
});
For the full, current list of model IDs, see the Keystroke models catalog. Copy the Model ID column exactly — IDs are opaque catalog strings, not display names you can reformat. Some models use dots in version segments (anthropic/claude-sonnet-4.6, google/gemini-3.5-flash); others use hyphens (alibaba/qwen-3-14b). Do not kebab-case a version number from the model name: anthropic/claude-sonnet-4-6 is invalid even though the product is called “Claude Sonnet 4.6”. Unknown IDs fail at build and deploy time. The same model string works locally and in the cloud; only how the model is accessed changes:
  • Local: set a single AI_GATEWAY_API_KEY to use any model in the catalog, or set a per-vendor key such as ANTHROPIC_API_KEY to call that provider directly.
  • Cloud: hosted workers route through the platform automatically, so deployed agents need no provider keys.
keystroke auth login authenticates you to the platform for deploys and cloud commands. It does not give your local runtime model access; local runs still need AI_GATEWAY_API_KEY or a direct provider key.
You can use thinkingLevel to control the model’s reasoning effort when the provider supports it. It defaults to medium; valid values are provider-default, none, minimal, low, medium, high, and xhigh.
export default defineAgent({
  slug: "planner",
  systemPrompt: "Plan carefully, then give a concise answer.",
  model: "anthropic/claude-sonnet-4.6",
  thinkingLevel: "high",
});

Structured output

By default agent.prompt() returns conversational text in result.messages. When you call the agent from code (a workflow, action, or script) and need a typed object instead, pass an outputSchema (Zod) on the call. outputSchema is a per-prompt option, not a defineAgent() field, so the same agent can return free text on one call and structured data on the next. Read the parsed, typed result from result.output:
import { z } from "zod";
import researcher from "../agents/signup-researcher";

const Summary = z.object({ company: z.string(), summary: z.string() });

const result = await researcher.prompt({
  message: "Research Acme Corp",
  outputSchema: Summary,
});
if (result.error) throw new Error(result.error);

const { company, summary } = result.output!; // typed { company: string; summary: string }
Without outputSchema, result.output is undefined and you read the reply from result.messages. Structured output is an in-process TypeScript feature — it is not exposed over the HTTP route or keystroke agents prompt.

Schema design: model the shape precisely

Design the schema around the outcomes you actually expect, not one flat object that tries to cover every case with optional fields. This is both better type safety (each result is exhaustively typed) and it sidesteps a hard provider limit: Anthropic’s native structured output rejects schemas with more than 16 union-typed parameters — every .nullable() / .nullish() field compiles to a T | null union, so a wide flat object blows past the cap and fails at request time with Schemas contains too many parameters with union types. When a result has variants that carry different fields, use a discriminated union keyed on a literal so each branch declares only its own required fields:
const Decision = z.discriminatedUnion("action", [
  z.object({ action: z.literal("drop"), newPrice: z.number(), reasoning: z.string() }),
  z.object({ action: z.literal("no_more_offers"), reasoning: z.string() }),
  z.object({ action: z.literal("payment_plan"), months: z.number(), reasoning: z.string() }),
]);
Prefer required fields over .nullable()/.nullish(), and reach for discriminated unions over large optional-heavy objects. Plain .optional() (a field that may be absent) does not create a union, so it does not count toward the limit — but a precise discriminated union is usually the clearer model anyway.

Structured output with tools

When an agent has tools and you pass outputSchema, Keystroke runs a multi-step tool loop: the model calls tools, then returns a schema-validated result. Expect at least two LLM steps (tool call + structured result). See the AI SDK troubleshooting guide for the same step-count rule. Keystroke applies vendor-specific fixes automatically:
VendorBehavior
Anthropic (Sonnet/Opus)Native structured output compatible with extended thinking; forces a tool call on step 1 so the model cannot skip tools by satisfying the schema early. Haiku is excluded — tools + schema may still be unreliable.
OpenAI, Google, xAINative structured output; no extra guard needed.
z-ai (GLM), Alibaba (Qwen)No native structured output on the gateway. Keystroke uses a submit tool (submit_structured_output) for agent.prompt() with tools and for all promptLlm() calls.
Minimax, DeepSeekSubmit-tool path for promptLlm(); native structured output for agent.prompt() with tools.
Gateway model tags (reasoning, tool-use, vision, …) do not indicate structured-output support. Pick models from the models catalog for pricing and capabilities, but rely on the table above for outputSchema reliability. outputSchema works in agent.prompt() and workflow promptLlm() steps. It is not exposed over HTTP or the CLI. Agents can read information from the live web through two built-in host tools, injected when Keystroke can resolve a web provider:
  • web_search searches the web by query.
  • web_fetch fetches readable page text from a URL.
In hosted workers the platform can proxy web search automatically. For local runs, set EXA_API_KEY to enable Exa-backed web tools, then make the prompt explicit about when to search:
export default defineAgent({
  slug: "web-researcher",
  systemPrompt:
    "Use web_search before answering factual questions about current companies or events. Use web_fetch to inspect promising sources.",
  model: "anthropic/claude-sonnet-4.6",
});

Ephemeral triggers

Every agent is given two built-in tools (set_trigger and list_triggers) so it can schedule its own work without a deploy. The agent can create a cron, webhook, or poll trigger on itself, then update, pause, or delete it later. These are ephemeral triggers: the agent manages them at runtime and they live in the database, separate from the triggers you write in src/triggers/. These tools are injected automatically; there is no defineAgent() option to add them, and they require no configuration. They are how an agent honors a request like “remind me about this in an hour” or “check the deploy every morning and message me if it’s red”: the agent creates a trigger on itself from inside the conversation instead of needing you to write one. Ephemeral triggers support the same three kinds as code triggers:
KindFires
CronOn a schedule
WebhookWhen a matching payload hits an endpoint
PollWhen a scheduled script reports new work
The agent can give a trigger a lifecycle so it stops on its own: maxExecutions for a fixed number of runs (a single future reminder is just maxExecutions: 1) or until for an expiry time. When an ephemeral trigger fires it starts a new agent session and appears in History alongside every other run. When you want a sustained, deploy-time automation instead (a schedule or webhook wired to an agent in code), define it in src/triggers/. See run agents from triggers and the triggers section.

Browser use

Browser use means driving a real browser: clicking, filling forms, navigating multi-step flows, and taking screenshots. That goes beyond reading page text with web_fetch.
Native browser automation is coming soon. Until then, wrap browser work in a task-specific action or a workflow step rather than exposing a general browser to the agent.

Sandboxes

Every agent already gets a /workspace with built-in bash, read, write, and edit tools, running in-process with no VM. /workspace/agent persists across sessions (skills, attached files, anything worth keeping); /workspace/session is per-session scratch where coding tools default. This handles a surprising amount on its own: manipulating files, processing text and data, and running shell commands and scripts. Many platforms boot a full sandbox VM for any code execution at all; Keystroke gives agents this lightweight bash environment by default, so most agents never need a sandbox. The workspace starts empty unless you attach content:
SourceWhere it comes from
Agent filessandbox: defineSandbox({ files: true }) uses src/files/{agentSlug}/; files: "key" uses src/files/{key}/
Project skillsskills: ["support"] materializes src/skills/support/
Inline sandbox filesdefineSandbox({ files: [...] }) seeds explicit paths in code
Runtime filesThe agent can create and edit files during the session
Use defineSandbox() to attach project file sets or seed specific files directly in code:
import { defineAgent } from "@keystrokehq/keystroke/agent";
import { defineSandbox } from "@keystrokehq/keystroke/sandbox";

const seeded = defineSandbox({
  files: [{ path: "context/seed.txt", file: "seeded" }],
});

export default defineAgent({
  slug: "sandbox-seeded",
  systemPrompt: "Read files from /workspace before answering.",
  model: "anthropic/claude-sonnet-4.6",
  sandbox: seeded,
});
The in-process bash is not a full machine, though. You can easily enable a VM-backed sandbox with defineSandbox({ mode: "vm" }) when your agent needs capabilities the default workspace can’t provide:
Enable a VM when your agent needs to…Example
Run real CLI tools and binariesgit, python, ffmpeg, a package manager
Clone, build, and test a real codebasegit clone a GitHub repo, install deps, run its tests
Install dependencies or system packagesnpm install, pip install, apt-get
Run heavy or long-lived processescompile a project, start a dev server
Strongly isolate untrusted code from the hostsafely execute arbitrary agent-generated code
export default defineAgent({
  slug: "repo-worker",
  systemPrompt: "Clone the repo into /workspace, then make the requested change.",
  model: "anthropic/claude-sonnet-4.6",
  sandbox: defineSandbox({ mode: "vm" }),
});
In both modes the agent itself runs in the Keystroke worker and works through its bash, read, write, and edit tools; sandbox.mode only changes where those tools execute. A bash call with mode: "vm" runs the command inside the VM and returns its output to the agent, rather than running in-process. The agent reaches into the VM through tools; it never runs inside it. For everything else, we recommend leaving mode unset on defineSandbox() (the in-process bash is faster to start and saves you money because you aren’t running a VM).

Next steps

Run agents

Prompt agents from the CLI and inspect sessions.

Test agents

Add tests and local prompts before deploying agent changes.

External channels

Route Slack messages to an agent.

Agent runs

Review conversation history, tool calls, traces, and errors.