LatentStackLatentStack/Docs

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. bedrock/us.anthropic.claude-sonnet-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.
environmentobjectoptional
Where the agent works. Omit it for an empty sandbox. See Repositories and patches.
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.
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. With several repositories, the agent is automatically told where each one is.

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, a session uses rules built for unattended coding work. The agent can read, edit, run tests and inspect git on its own, and asks before anything that reaches further:

ToolDefault
read · glob · grep · listallow
editallow, except secrets and keys (*.env, *.pem, *.key, .ssh, .aws), which are denied
bashask, except test runners (npm test, pytest, go test, cargo test, make test, …) and git that reads or moves around the workspace (status, diff, log, show, fetch, checkout, …), which are allowed
webfetch · websearchask
taskask, since sub-agents multiply model usage
external_directorydeny: nothing outside the workspace

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, 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: "bedrock/us.anthropic.claude-sonnet-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.",
})
Your rules replace the default rules
When you pass permissions, the table above isn't used. Tools you leave out follow LatentCode's own defaults, which allow most tools, including shell commands, and ask only before touching sensitive files (.env, lockfiles, CI workflows, Dockerfiles), dangerous commands and network access. 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
Never wait for a personStart with { action: "*", effect: "deny" }, then allow what the task needs.
Let it run anything in an empty sandbox{ action: "bash", effect: "allow" }
Approve every command yourself{ action: "bash", effect: "ask" } after your other rules
Keep it inside the code{ action: "webfetch", effect: "deny" }, { action: "websearch", effect: "deny" }

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.