# 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](#local-options). |
| `hosting` | `{ egressDomains?, secretNames? }` | The egress allowlist and expected secret names that `agent-sdk deploy` reads. Mounted [extensions](/docs/reference/extensions.md#build-an-extension) add their own. |
| `concurrency` | `{ maxRunningTurns? }` | Agent-wide limit on concurrent turns. See [Concurrency](#concurrency). |
| `builtinTools` | `{ reminders? }` | Opt-in tools that Agent SDK provides. See [Built-in tools](#built-in-tools). |
| `tools` | `ToolName[]` | Allowlist of built-in tools. Omit it for the full standard toolset. See [Harness tools](#harness-tools). |
| `fs` | `FileSystem` or `(ctx) => FileSystem` | Custom file tree for the session. `root` is the deprecated name. See [Custom filesystem](#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 `tools` omitted, 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`. Set
  [`workspace`](#custom-filesystem) to 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.json` from the workspace
  or an enclosing checkout isn't loaded (connections in `bot/` still are); host
  git status doesn't reach the model; and skills are at `/agent/skills`
  instead of `.cursor/skills`. `AGENTS.md` and `.cursor/rules/` in the
  workspace still load. Tools a tree can't run, such as `readLints`, are left
  out with a warning.

To keep an agent's reads inside a tree you choose, give it
[`fs`](#custom-filesystem) instead.

A [direct tool call](/docs/reference/tools.md#call-a-tool-without-a-model-turn) 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](#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 with `execution: "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](/docs/troubleshooting.md#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](/docs/reference/schedules.md#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](/docs/reference/cli.md) `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](/docs/reference/cli.md#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.

## Related

- [Instructions](/docs/reference/instructions.md)
- [Sessions](/docs/reference/sessions.md)
