Agents API

Configuring agents

Choose the model, write the instructions, and decide what the agent may do without asking.

You configure an agent when you create its session. The configuration stays with the session for its whole life, across pauses and resumes. To run with different settings, create a new session.

Session settings

agentobjectrequired
modelstringrequired
A model your tier allows, e.g. anthropic/claude-sonnet-5.5. latentcode models lists yours.
instructionsstringoptional
How the agent should work: its role, constraints and the shape of its answer. Up to 20,000 characters.
permissionslist of rulesoptional
What the agent may do alone, must ask about, or may never do. See Permissions.
mcp_serverslist of serversoptional
Remote MCP servers whose tools the agent may use. See MCP servers.
environmentobjectoptional
Where the agent works, and what it can reach. Omit it for an empty sandbox. See Repositories and patches and Network.
limitsobjectoptional
Caps on what the session may spend, in turns, tokens or dollars. See Spend limits.
inputstringoptional
The first task. It runs as soon as the sandbox is ready. You can also create the session without it and send a message later.
metadataobjectoptional
Your own key/values, e.g. a ticket or pull request number. Returned unchanged on the session.
filesobjectoptional
Files to put in the workspace before the first message runs. See Send files with create.
outputslist of pathsoptional
Files to copy out at the end of each run and keep after the session ends. See Outputs.
end_after_runbooleanoptionaldefault false
Stop the session once its run has ended. See End after the run.
webhookobjectoptional
A URL to tell about this session as it changes state. See Webhooks.
idempotencyKey · idempotency_keystringoptional
Makes creation safe to retry. The same key with the same settings returns the first session instead of starting another.

Instructions

Instructions are added to LatentCode's own system prompt, so you don't need to explain how to use tools. Say what good work looks like for your task:

  • The goal and the limits: "Fix the failing tests. Do not change test assertions or add dependencies."
  • What to do when unsure: "If a fix needs a schema change, stop and explain instead."
  • The shape of the answer, when your code reads it: "End with a Markdown list of files changed and why."

Put anything that changes per task in the message, not the instructions.

You don't need to describe the sandbox. When it starts, LatentStack writes a note into the agent's instructions: where each repository is, where files go, what a pause keeps and what the network allows. Your instructions come after that note and win where the two meet.

Permissions

Every tool call is checked against the session's rules. Each rule has one of three effects:

EffectWhat happens
allowThe tool runs.
askThe agent stops and asks you. See Approvals.
denyThe call is refused and the agent is told, so it can try another way.

Default rules

Without permissions, the agent works on its own. The sandbox is the boundary, not a prompt: inside its workspace the agent can read, edit and run most commands without asking. An earlier default asked before most commands, and real tasks needed 34 to 94 approvals each.

ToolDefault
read · glob · grep · listallow
editallow, except secrets and keys (*.env, *.env.*, *.pem, *.key, */.ssh/*, */.aws/*), which are denied
bashallow, any command
external_directorydeny, except the whole workspace (/work/*), which is allowed
webfetch · websearchallow when the session's network is open; deny otherwise, since they couldn't reach anything
taskallow. Subagents run as sessions of their own, and their spend counts toward this session's limits.
an MCP server's toolsallow; only the listed ones when the server has a tools list

LatentCode itself still asks before some commands, even with bash allowed. These are its own checks, separate from the bash rule: commands that reach the network (curl, gh, git fetch, git push, pip install, npm install and similar), dangerous commands (a recursive rm, sudo, deleting a branch) and commands that write git metadata (git add, git commit, git checkout). See Approvals.

Writing rules

A rule is { action, resource, effect }. Rules apply in order and the last matching rule wins, so write the general rule first and exceptions after it.

FieldValues
actionA tool: read, edit, glob, grep, list, bash, task, webfetch, websearch, external_directory, skill, lsp, todowrite, an MCP server's tool as <server>_<tool> or all of them as <server>_*, or * for every tool.
resourceWhat the call targets, with * as a wildcard: a command line for bash (git *), a path for read and edit (src/*). Defaults to *. webfetch, websearch and todowrite take only *.
effectallow, ask or deny.
A read-only reviewer
const session = await sessions.create({
  agent: {
    model: "anthropic/claude-sonnet-5.5",
    instructions: "You review code. Read before you judge, name files and lines, and never modify files.",
    permissions: [
      { action: "*", effect: "deny" },                       // anything not allowed below is refused
      { action: "read", effect: "allow" },
      { action: "glob", effect: "allow" },
      { action: "grep", effect: "allow" },
      { action: "list", effect: "allow" },
      { action: "bash", resource: "git *", effect: "allow" },
      { action: "bash", resource: "git push*", effect: "deny" }, // later rules win
    ],
  },
  environment: { type: "repos", repos: ["acme/demo"] },
  input: "Review the most recent commit (git show HEAD). List up to three concrete risks or improvements.",
})
Warning
Your rules replace the default rules
When you pass permissions, your list replaces the table above entirely, including its denies on secret files and outside the workspace. Tools you leave out follow LatentCode's own rules, not the table. To stay in control, start with { action: "*", effect: "ask" } or deny and allow what the task needs after it.

An invalid rule, such as an unknown tool, an unknown effect, or a resource on a tool that takes none, is rejected when you create the session, with an error naming the rule.

Common setups

GoalRules
Let it work on its ownOmit permissions. It still asks before network and dangerous commands.
Never wait for a personStart with { action: "*", effect: "deny" }, then allow what the task needs.
Approve every command yourself{ action: "bash", effect: "ask" } after your other rules
Keep it inside the codeSet network to none, or add { action: "webfetch", effect: "deny" } and { action: "websearch", effect: "deny" } to your rules

Network

environment.network sets what the sandbox can reach. The sandbox never gets a route of its own: everything it reaches goes through LatentStack.

environment: { type: "repos", repos: ["acme/payments"], network: "readonly" }
networkThe sandbox can reach
openThe default on latentstack.dev. Package managers, curl, go, cargo, apt and the agent's own web search and fetch go through an egress proxy to an allowlist of package registries, source hosts and documentation sites. A host that isn't on the list is refused.
readonlyOnly pip and npm, through the gateway, for reading: packages install, and nothing can be uploaded. No web search or fetch.
noneThe gateway and nothing else. Nothing can be installed.
  • The proxy can't see inside HTTPS, so an open session can upload to a host on the list. Use readonly or none when that matters.
  • On a deployment without the proxy, readonly is the default and open is refused with invalid_request.
  • git is the same in every mode. Clone, fetch and push of any GitHub repository your token can reach go through the gateway with your token, and gh has your token in the sandbox. gh calls the GitHub API, so it works in open only. See Repositories and patches.

MCP servers

Give the agent the tools of remote MCP servers, such as GitHub, your issue tracker or your own APIs. Name each one in agent.mcp_servers when you create the session:

const session = await sessions.create({
  agent: {
    model: "anthropic/claude-sonnet-5.5",
    mcp_servers: [{
      name: "github",
      url: "https://api.githubcopilot.com/mcp/",
      headers: { Authorization: `Bearer ${process.env.GITHUB_TOKEN}` },
    }],
  },
  input: "Summarise the open issues labelled bug in acme/payments.",
})
namestringrequired
Up to 32 lower-case letters, digits and -, starting with a letter. It can't be a built-in tool's name, such as read or bash, or the first word of one, such as create (create_docx).
urlstringrequired
The server's https URL.
headersobjectoptional
Sent with every request to the server, e.g. { "Authorization": "Bearer …" }.
toolslist of stringsoptional
Only these of the server's tools. Leave it out for every tool.
timeout_secondsintegeroptionaldefault 60
How long one request to the server may take, from 1 to 600.

A session takes up to 10 servers.

Tool names and permissions

The agent sees each tool as <name>_<tool>: the get_issue tool of the github server is github_get_issue. They run without asking unless your rules say otherwise; a rule for every tool (action: "*") covers them too. A rule names one tool the same way, or every tool of a server as github_*, with no resource:

JSON
"permissions": [
  { "action": "github_*", "effect": "ask" },
  { "action": "github_get_issue", "effect": "allow" }
]

Choosing tools

With tools, the agent gets only the tools you list. LatentStack leaves the others out of the server's tool list and refuses any call to them before it reaches the server, whatever the agent tries.

Credentials

Header values are write-only. LatentStack keeps them encrypted, makes each request to the server itself and adds the headers then, so they never enter the sandbox and the agent can't read or print them. Reading the session back shows each server's name, its url with any query values shown as <hidden>, the names of its headers (header_names), its tools and its timeout_seconds, never a header's value.

Network

MCP servers work in every network mode, none included: the request to the server is made by LatentStack, not from the sandbox.

Which servers work

  • Servers that speak MCP's Streamable HTTP transport. The older SSE transport isn't supported.
  • A public https URL on port 443. A self-hosted deployment can let in its own private hosts by listing them in AGENT_MCP_PRIVATE_HOSTS.
  • A server that signs in with a header, such as a token or an API key. Servers that need you to sign in through a browser (OAuth) aren't supported.

Spend limits

limits caps what one session may spend. Set any of the three caps; leave out the ones you don't need.

const session = await sessions.create({
  agent: { model: "anthropic/claude-sonnet-5.5" },
  limits: { max_turns: 50, max_cost_usd: 5 },
  input: "Fix the failing tests.",
})
max_turnsintegeroptional
Model calls, subagents' included. A failed call counts.
max_tokensintegeroptional
Every token processed, cache reads and writes included.
max_cost_usdnumberoptional
Dollars. Refused with invalid_request on a deployment that can't price usage.

When a cap is reached

  • The agent is told to wrap up: no more tools, and a short text of what is done and what is left.
  • The session is paused after that step, with the cap as its pause_reason. Its patch is captured first, and it keeps its disk and conversation.
  • While it wraps up, new messages are refused with limit_reached. Approvals and cancel still work. Raising the cap past what it has spent during the wrap-up lets it go on afterwards instead of pausing.
  • To go on, raise the cap with sessions.update() (PATCH /v1/agents/sessions/{id}), then send a message or resume. Until then, continuing is refused with limit_reached, and nothing about the session changes. The same goes for a session you deleted at its cap: while its disk is kept, raise the cap, then resume it.
  • A cap can be exceeded by about two steps: the step that crossed it and the wrap-up step are both spent.

What a session has spent

Every read of a session carries limits: the caps, and the running tally they are checked against.

JSON
"limits": {
  "max_turns": 50,
  "max_tokens": null,
  "max_cost_usd": 5.0,
  "spent": {
    "turns": 12,
    "tokens": 418230,
    "cost_usd": 0.61,
    "subagents": { "turns": 3, "tokens": 52011, "cost_usd": 0.08 }
  }
}
FieldMeaning
limits.spentWhat counts toward the caps: turns, tokens and cost_usd. The subagents' share is included, and also shown on its own under subagents.
usageOn a single get() only: input_tokens, output_tokens, cache_read_tokens, cache_write_tokens, reasoning_tokens, model_calls, estimated_cost_usd, sandbox_seconds and as_of. It runs a little behind; read it again later for the final figure.
pause_reasonWhile paused: the cap it reached (max_turns, max_tokens or max_cost_usd), or requested, idle_timeout, hard_limit or restored.
stop_reasonnull while the session lives. Then deleted or paused_expired. A session made with end_after_run can also stop with run_finished, idle_timeout or hard_limit.

Other limits

  • Instructions: 20,000 characters. A message: 100,000 characters.
  • Up to 6 repositories per session.
  • Your administrator may cap how many active sessions an organization can have at once.