Appearance
Agent config
bot/agent.ts default-exports defineAgent(config), which sets the model that runs the agent and the defaults for a local run. Every field is optional on the root agent.
ts
import { defineAgent } from "@grok/agent-sdk";
export default defineAgent({
model: {
id: "grok-4.7",
params: [
{ id: "reasoning_effort", value: "high" },
{ id: "fast", value: "true" },
],
}, // optional; this is the default
});Agent fields
| Field | Type | Meaning |
|---|---|---|
model | string or { id, params } | Cursor model for turns. Defaults to grok-4.7 with reasoning_effort=high and fast=true. Subagents omit it to inherit. |
name | string | Display name. Defaults to the package or directory name. |
description | string | What the agent is for. Required on subagents, where the parent model reads it to decide when to delegate. |
instructions | string | Inline instructions for subagents and generated configs. Prefer instructions.md. |
local | { cwd?, workspaceDir?, sandbox? } | Defaults for a local run. See Local options. |
hosting | { egressDomains?, secretNames? } | The egress allowlist and expected secret names that agent-sdk deploy reads. Mounted extensions add their own. |
concurrency | { maxRunningTurns? } | Agent-wide limit on concurrent turns. See Concurrency. |
builtinTools | { reminders? } | Opt-in tools that Agent SDK provides. See Built-in tools. |
tools | ToolName[] | Allowlist of built-in tools. Omit it for the full standard toolset. See Harness tools. |
fs | FileSystem or (ctx) => FileSystem | Custom file tree for the session. root is the deprecated name. See Custom filesystem. |
workspace | string | With fs, the folder inside the tree the agent works in, and where project rules load from. Defaults to /. For a sandboxed agent without shell, where its session workspace is mounted, /workspace by default. |
skills | false or (ctx) => FileSystem | Replaces the skills tree mounted at /agent/skills, or turns that mount off. |
The persistent field was removed. Discovery rejects a config that still sets it, and the error is persistent was removed. Delete it from defineAgent., so validate, dev, and deploy fail until you delete the field. A deployment that is already running keeps serving until you stop or delete it.
Model
Set effort and speed with params, not in the id. Use the object form shown above to set params, or a plain string when you don't need any:
ts
model: "composer-2.5",Local options
local.workspaceDir points every session at one shared working directory, for agents that work inside an existing checkout. It takes precedence over cwd, and a per-send workspaceDir wins over both. Sessions share that tree, so one turn's files are visible to the next.
local.sandbox runs the agent inside Cursor's local sandbox. It's off by default, so shell commands auto-approve and inherit the serve process environment, including the host's credentials. Turn it on when turns read untrusted input, such as webhook payloads, PR diffs, or inbound chat. The sandbox limits the tools themselves, so an injected prompt can't talk the model past it.
With local.sandbox on, shell commands run without network access, writes and deletes outside the session workspace are refused, and a tool call that needs approval, such as an external MCP call, fails closed. What the agent can read depends on its tools:
- With shell (or with
toolsomitted, which includes it), the agent runs on the host disk. Shell commands and the file tools (read,grep,glob,ls) can read any file the serve process can, including credentials on the host. - With file tools and no shell, such as
tools: ["read", "grep"], the agent runs on its session workspace as a tree, mounted at/workspace. Setworkspaceto mount it elsewhere. Every file tool sees only the workspace and refuses a path outside it, including through a symlink. Running on a tree also turns off what only the host disk provides: Cursor hooks don't run, so a Slack follow-up waits for the turn to end instead of reaching the running turn;.cursor/mcp.jsonfrom the workspace or an enclosing checkout isn't loaded (connections inbot/still are); host git status doesn't reach the model; and skills are at/agent/skillsinstead of.cursor/skills.AGENTS.mdand.cursor/rules/in the workspace still load. Tools a tree can't run, such asreadLints, are left out with a warning.
To keep an agent's reads inside a tree you choose, give it fs instead.
A direct tool call on a host-disk agent refuses a path outside the session workspace, after symlinks, with Path is outside the workspace, whether or not local.sandbox is on.
Local cwd
local.cwd sets the parent directory for local session workspaces. Each session uses <cwd>/<sessionId> unless a per-send workspaceDir overrides it.
Session workspaces are real Cursor project directories, so the local agent reads AGENTS.md and .cursor config from every ancestor directory. When you omit cwd and the agent sits inside another git repo, such as a monorepo package, Agent SDK uses a per-project directory under ~/.cache instead, so the enclosing checkout's rules, skills, and MCP servers stay out of the turn. An agent at its own git root keeps its workspaces inside the project. Point cwd at a checkout only when the agent should inherit that tree.
Custom filesystem
Set fs and the agent's file tools (Read, Write, StrReplace, LS, Grep, Glob, Delete) and its subagents work on your tree instead of the host disk. Build it with tempFs, unionFs, overlayFs, readOnlyFs, or your own FileSystem.
ts
import { defineAgent, readOnlyFs, tempFs, unionFs } from "@grok/agent-sdk";
export default defineAgent({
fs: unionFs({
"/repo": readOnlyFs(repoFs),
"/notes": tempFs({ "/todo.md": "- check the rollout" }),
}),
workspace: "/repo",
});fs is mounted at /, and Agent SDK mounts /tmp and /agent/skills over it. Set fs or the deprecated root, not both. A tree that already has /agent/skills fails session start unless skills is false.
Each turn gets an empty /tmp, and large web results land there. Write anything the next turn needs elsewhere in the tree. Subagents work on the same tree, so their writes are visible to the agent right away, as subagents share the host workspace without fs.
workspace is the folder the model works in. Relative paths resolve against it, and LS, Grep, and Glob search it when a call names no path. It must be an absolute path outside /tmp, and defaults to /.
As on the host, the workspace's AGENTS.md and .cursor/rules/ load as project rules. Don't make a checkout you don't trust, such as a pull request under review, the workspace. Mount it beside the workspace instead, for example at /repo with workspace left at /, where its rules don't load.
An fs agent has no shell, and listing "shell" in tools fails validation. Tools a tree can't run, such as readLints or computerUse, are left out: an omitted tools never includes them, and a tools list that names them gets a warning. A tools list gets only the file tools it names. Omit tools to get all of them. fs works on local turns only.
With fs, local.sandbox only affects approvals: a tool call that needs approval, such as an external MCP call, fails closed, as it does without fs. It changes nothing about file access, because the file tools already see only the tree.
Harness tools
Use tools to limit which built-in Cursor tools the model can call. When you set it, the model gets only the tools you list. An empty list turns off every built-in tool, and new platform tools stay off until you add them.
ts
export default defineAgent({
model: "composer-2.5",
// Read-only triage: no shell, no edits, no subagents.
tools: ["read", "grep", "glob", "ls"],
});Agent SDK always adds "mcp" to a configured allowlist, because the server tools in bot/tools/ reach the model over MCP. With local.sandbox on, MCP tool calls fail closed. An enclosing checkout can also add MCP servers, as Local cwd explains.
Use the Cursor SDK's public tool names, such as "shell", "read", "edit", "grep", "glob", "ls", and "task". An unknown name fails the turn with a ConfigurationError, and "SemanticSearch" or "semSearch" fails validation.
Two names have broader effects:
"shell"also grants shell input. Tools withexecution: "agent"need it to run their scripts, and discovery warns when your allowlist blocks them."task"lets the root agent start subagents. Each subagent keeps its own toolset.
The allowlist doesn't isolate the serve host, so pair it with local.sandbox for untrusted input.
Migrate off semantic search
Semantic search is removed, and agent-sdk validate reports Semantic search has been removed. Use Grep. while a project still uses it. A turn fails or misbehaves lists what to delete and what to use instead.
Concurrency
concurrency.maxRunningTurns caps how many model turns run at once across the agent's sessions. It takes a positive integer up to 200. Omit it for no limit.
When every slot is busy, a new turn queues in arrival order instead of failing. The stream records a turn.queued event with the queue position, GET /v1/sessions reports queued: true, and the turn starts as soon as a slot frees.
A queued turn still counts as running. A follow-up preempts it, and a direct write-effect tool call gets 409 session_busy.
ts
export default defineAgent({
concurrency: { maxRunningTurns: 3 },
});Built-in tools
builtinTools opts into tools that Agent SDK provides. They behave like your own server tools in turns, direct calls, info, and the playground. A tool you write with the same name wins, with a warning.
builtinTools: { reminders: true } adds reminders_create, reminders_list, and reminders_cancel, bound to the current conversation. A session without a continuation key can't set reminders. See Schedules and reminders.
Serve programmatically
serve(dirOrProject, options) embeds the server in your own process:
ts
import { serve } from "@grok/agent-sdk";
const handle = await serve("./my-agent", {
port: 3000,
});
console.log(`listening on ${handle.url}`);
// handle.callTool(...), handle.dispatchSchedule("heartbeat"),
// handle.createReminder(...), handle.agents, await handle.close()handle.agents lists each mount as { slug, url, info }. handle.project is deprecated.
serve() takes the same host settings as the CLI serve flags, plus discovery for project-loading options and mode: "single" | "multi". Pass apiKey, or sign in the same way as the CLI, as Environment variables describes.
Inspect a project in tests
loadProject(dir) reads one project without serving it. Its info matches the GET /v1/info body.
ts
import { loadProject } from "@grok/agent-sdk";
const { info } = await loadProject("./my-agent", { strict: true });
expect(info.tools.map((t) => t.name)).toContain("inspect_pr");loadProject throws ProjectLoadError when discovery reports an error, and { strict: true } makes it throw on a warning too. error.diagnostics lists the findings, and each path is relative to the project directory. serve accepts the loaded project or a directory path.