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
agentobjectrequiredmodelstringrequiredanthropic/claude-sonnet-5.5. latentcode models lists yours.instructionsstringoptionalpermissionslist of rulesoptionalmcp_serverslist of serversoptionalenvironmentobjectoptionallimitsobjectoptionalinputstringoptionalmetadataobjectoptionalfilesobjectoptionaloutputslist of pathsoptionalend_after_runbooleanoptionaldefault falsewebhookobjectoptionalidempotencyKey · idempotency_keystringoptionalInstructions
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:
| Effect | What happens |
|---|---|
| allow | The tool runs. |
| ask | The agent stops and asks you. See Approvals. |
| deny | The 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.
| Tool | Default |
|---|---|
| read · glob · grep · list | allow |
| edit | allow, except secrets and keys (*.env, *.env.*, *.pem, *.key, */.ssh/*, */.aws/*), which are denied |
| bash | allow, any command |
| external_directory | deny, except the whole workspace (/work/*), which is allowed |
| webfetch · websearch | allow when the session's network is open; deny otherwise, since they couldn't reach anything |
| task | allow. Subagents run as sessions of their own, and their spend counts toward this session's limits. |
| an MCP server's tools | allow; 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.
| Field | Values |
|---|---|
| action | A 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. |
| resource | What 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 *. |
| effect | allow, ask or deny. |
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.",
})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
| Goal | Rules |
|---|---|
| Let it work on its own | Omit permissions. It still asks before network and dangerous commands. |
| Never wait for a person | Start 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 code | Set 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" }| network | The sandbox can reach |
|---|---|
| open | The 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. |
| readonly | Only pip and npm, through the gateway, for reading: packages install, and nothing can be uploaded. No web search or fetch. |
| none | The gateway and nothing else. Nothing can be installed. |
- The proxy can't see inside HTTPS, so an
opensession can upload to a host on the list. Usereadonlyornonewhen that matters. - On a deployment without the proxy,
readonlyis the default andopenis refused withinvalid_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
ghhas your token in the sandbox.ghcalls the GitHub API, so it works inopenonly. 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-, 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).urlstringrequiredheadersobjectoptional{ "Authorization": "Bearer …" }.toolslist of stringsoptionaltimeout_secondsintegeroptionaldefault 60A 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:
"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_turnsintegeroptionalmax_tokensintegeroptionalmax_cost_usdnumberoptionalinvalid_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 withlimit_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.
"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 }
}
}| Field | Meaning |
|---|---|
| limits.spent | What counts toward the caps: turns, tokens and cost_usd. The subagents' share is included, and also shown on its own under subagents. |
| usage | On 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_reason | While paused: the cap it reached (max_turns, max_tokens or max_cost_usd), or requested, idle_timeout, hard_limit or restored. |
| stop_reason | null 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.