Agents

One agent

Run a turn in one conversation, then attach to it, answer it, steer it or stop it

On this page(15 sections)

Say something to an agent
Watch a turn happen
Answer a question the agent asked
Interrupt a running turn
Stop a turn now
Reword a waiting message
Take back a waiting message
Let waiting messages go
Reschedule waiting messages
Run a refused turn again
Move a conversation to another account
Go back to an earlier message
Shortcut commands the agent knows
Choose what a new chat opens on
The last time each provider said no

The surface most callers are here for. Starting a turn answers with a run id and nothing else: the work happens inside the sandbox whether or not anybody stays connected, and attaching is how you watch it, from the beginning or from wherever you had got to. The rest is the things a person does to a turn in flight — answer a question it asked, redirect it, stop it, or put the whole conversation back to an earlier point. Everything here addresses one conversation by id.

15 calls. Pick one to open it, or use the list on the right.

POST/agentSay something to an agent

Answers at once with what became of the message: it starts a turn when the conversation is free, is said into the running turn where that turn takes words mid-way, and otherwise waits in the conversation's queue for the next turn, where every window sees it. The work runs inside the sandbox whether or not anybody stays connected; watch it by attaching. Naming a conversation that does not exist yet opens it. Give the message an id, and sending it again after a lost answer is met with what became of it the first time rather than a second delivery.

What you send

Field	Type	Where
`prompt`requiredWhat to say to the agent	string	body
`errand`What the words are for, when…	"land-conflict" \| "verify-nudge" \| "land-breakage" \| "land-fix" … (10)	body
`messageId`Your id for this message	string	body
`title`A title for a conversation this…	string	body
`attachments`Files to hand the agent along…	string[]	body
`mentions`Workspace paths the prompt mentions with…	string[]	body
`agent`Which model provider serves this turn	string	body
`harness`Which agentic loop runs the turn	"native" \| "claude-code"	body
`account`Which of that provider's connected accounts…	string	body
`actsAs`Which persona the turn speaks as…	string	body
`sessionId`Resume this provider session instead of…	string	body
`conversationId`The conversation this turn belongs to	string	body
`isolated`Work in this conversation's own private…	boolean	body
`startIn`Which folder the conversation opens in,…	string	body
`placement`Where this conversation runs: this sandbox…	object	body
`when kind is "local"`	shape	body
`when kind is "runner"`	shape	body
`id`required	string	body
`worktreeBase`Pin a new private copy to…	object[]	body
`repo`required	string	body
`base`required	string	body
`autoLand`Whether this turn's work merges into…	boolean	body
`runRole`What started this turn, when it…	"commit-message" \| "session-title" \| "safety-judge" \| "loop-verdict" … (13)	body
`origin`Set by the sandbox alone: this…	object	body
`automationId`required	string	body
`provider`required	string	body
`channelId`	string	body
`author`	string	body
`forkOf`Where this conversation was cut from,…	object	body
`conversationId`requiredThe conversation this one was cut…	string	body
`keep`requiredHow many of that conversation's messages…	integer	body
`files`requiredWhich files the fork opens on:…	"then" \| "now"	body
`model`Which model to use	string	body
`unattended`Nobody is watching this turn: a…	boolean	body
`outsideWake`Content from outside caused this turn,…	string	body
`permissionMode`How tool calls are gated: ask…	"default" \| "plan" \| "bypassPermissions"	body
`allowedTools`Narrow the turn to these tools	string[]	body
`effort`How hard the model should think,…	string	body
`thinking`Whether to show the model's reasoning…	boolean	body
`fast`Ask for the same work at…	boolean	body
`autoPicked`Whether this turn's model was chosen…	boolean	body
`editorContext`What the user has open in…	object	body
`file`requiredThe file open in the editor,…	string	body
`startLine`First line of the selection, counting…	integer	body
`endLine`Last line of the selection, counting…	integer	body
`selection`The selected text itself	string	body
`sendAt`Hold this message until then (epoch…	integer	body
`sendAfter`Hold this message until the conversation…	string	body
`conversationAutoLand`Whether this conversation's finished work merges…	boolean	body
`continues`Carry the conversation on from where…	true	body

What comes back

Field	Type
`delivered`What became of the message: it…	"started" \| "steered" \| "queued"
`run`The run the message is in:…	string
`duplicate`The sandbox had already taken a…	true

Try itanswered in this tab

curl

curl -X POST "$SANDBOX/agent" \
  -H "x-intentic-control: $INTENTIC_TOKEN" \
  -H "content-type: application/json" \
  -d '{"prompt":"Update the changelog for the last five commits.","errand":"land-conflict","messageId":"a1b2c3d4","title":"Update the changelog","attachments":["…","…"],"mentions":["…","…"],"agent":"…","harness":"native","account":"work","actsAs":"…","sessionId":"a1b2c3d4","conversationId":"nightly-changelog","isolated":true,"startIn":"…","placement":{"kind":"local"},"worktreeBase":[{"repo":"root","base":"…"},{"repo":"site","base":"…"}],"autoLand":true,"runRole":"commit-message","origin":{"automationId":"a1b2c3d4","provider":"claude","channelId":"a1b2c3d4","author":"Ada Lovelace"},"forkOf":{"conversationId":"nightly-changelog","keep":0,"files":"then"},"model":"claude-sonnet-4-6","unattended":true,"outsideWake":"…","permissionMode":"default","allowedTools":["…","…"],"effort":"…","thinking":true,"fast":true,"autoPicked":true,"editorContext":{"file":"…","startLine":1,"endLine":1,"selection":"…"},"sendAt":1,"sendAfter":"…","conversationAutoLand":true,"continues":true}'

TypeScript

import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.agent.run({
  "prompt": "Update the changelog for the last five commits.",
  "errand": "land-conflict",
  "messageId": "a1b2c3d4",
  "title": "Update the changelog",
  "attachments": [
    "…",
    "…"
  ],
  "mentions": [
    "…",
    "…"
  ],
  "agent": "…",
  "harness": "native",
  "account": "work",
  "actsAs": "…",
  "sessionId": "a1b2c3d4",
  "conversationId": "nightly-changelog",
  "isolated": true,
  "startIn": "…",
  "placement": {
    "kind": "local"
  },
  "worktreeBase": [
    {
      "repo": "root",
      "base": "…"
    },
    {
      "repo": "site",
      "base": "…"
    }
  ],
  "autoLand": true,
  "runRole": "commit-message",
  "origin": {
    "automationId": "a1b2c3d4",
    "provider": "claude",
    "channelId": "a1b2c3d4",
    "author": "Ada Lovelace"
  },
  "forkOf": {
    "conversationId": "nightly-changelog",
    "keep": 0,
    "files": "then"
  },
  "model": "claude-sonnet-4-6",
  "unattended": true,
  "outsideWake": "…",
  "permissionMode": "default",
  "allowedTools": [
    "…",
    "…"
  ],
  "effort": "…",
  "thinking": true,
  "fast": true,
  "autoPicked": true,
  "editorContext": {
    "file": "…",
    "startLine": 1,
    "endLine": 1,
    "selection": "…"
  },
  "sendAt": 1,
  "sendAfter": "…",
  "conversationAutoLand": true,
  "continues": true
});

POST/agent/attachWatch a turn happenstream

Streams everything the agent does: its words, the tools it reaches for, and the answers it gets. It opens with the turn's transcript whole as it stands, then sends every change as it lands, so a reload or a dropped connection loses nothing: attaching again hands over the whole transcript again. The window that started the turn holds no special claim, and any number of watchers on any number of devices see the same thing.

What you send

Field	Type	Where
`conversationId`requiredWhich conversation to watch	string	body
`run`The run you were watching	string	body

What comes back

Field	Type
`when event is "message"`	shape
`data`	object
`when kind is "attached"`	shape
`run`The run's id	string
`startedAt`When it started, in milliseconds, so…	number
`seq`How many frames the run has…	number
`rows`The turn's rows as they stand:…	object[]
`when kind is "patch"`	shape
`seq`Its position in the run, counting…	number
`patch`	object
`when kind is "fact"`	shape
`seq`Its position in the run, counting…	number
`fact`	object
`when kind is "end"`	shape
`id`	string
`retry`	number
`when event is "done"`	shape
`data`	unknown
`id`	string
`retry`	number
`when event is "error"`	shape
`data`	unknown
`id`	string
`retry`	number

Try itanswered in this tab

curl

curl -N -X POST "$SANDBOX/agent/attach" \
  -H "x-intentic-control: $INTENTIC_TOKEN" \
  -H "content-type: application/json" \
  -d '{"conversationId":"nightly-changelog","run":"run_8c2f41d9"}'

TypeScript

import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.agent.attach({
  "conversationId": "nightly-changelog",
  "run": "run_8c2f41d9"
});

POST/agent/replyAnswer a question the agent asked

Un-parks a turn that is waiting on you: approving a plan, choosing between options, or permitting a tool. The turn picks up where it stopped.

What you send

Field	Type	Where
`when kind is "plan"`	shape	body
`requestId`requiredWhich card you are answering, from…	string	body
`approve`requiredWhether to go ahead	boolean	body
`feedback`Why not, which goes back to…	string	body
`when kind is "question"`	shape	body
`requestId`requiredWhich card you are answering	string	body
`answers`What you chose, keyed by the…	object	body
`attachments`Files that go with your own-words…	object	body
`cancelled`Dismissing it instead, which tells the…	boolean	body
`when kind is "permission"`	shape	body
`requestId`requiredWhich card you are answering	string	body
`decision`requiredOnce allows this call alone; always…	"once" \| "always" \| "everything" \| "deny"	body
`feedback`Why not, which goes back to…	string	body
`child`For a request to start a…	object	body
`provider`requiredWhich provider serves it	string	body
`model`requiredWhich of that provider's models	string	body
`harness`Which agentic loop runs it	"native" \| "claude-code"	body
`account`Which of that provider's connected accounts…	string	body
`effort`How hard it thinks, where the…	string	body
`thinking`Whether it reasons before it answers,…	boolean	body
`fast`Whether it asks for the faster…	boolean	body
`when kind is "browser_help"`	shape	body
`requestId`requiredWhich card you are answering	string	body
`helped`requiredWhether you cleared it	boolean	body
`note`Anything the agent should know, which…	string	body
`when kind is "terminal_help"`	shape	body
`requestId`requiredWhich card you are answering	string	body
`helped`requiredWhether you did it	boolean	body
`note`Anything the agent should know, which…	string	body
`when kind is "capability_offer"`	shape	body
`requestId`requiredWhich card you are answering	string	body
`connect`requiredYes keeps the agent waiting while…	boolean	body
`when kind is "payment_offer"`	shape	body
`requestId`requiredWhich card you are answering	string	body
`approve`requiredYes releases exactly one payment	boolean	body
`when kind is "credential_offer"`	shape	body
`requestId`requiredWhich card you are answering	string	body
`approve`requiredYes releases it, as far as…	boolean	body

What comes back

Field	Type
`ok`Always true	true

Try itanswered in this tab

curl

curl -X POST "$SANDBOX/agent/reply" \
  -H "x-intentic-control: $INTENTIC_TOKEN" \
  -H "content-type: application/json" \
  -d '{"kind":"plan","requestId":"a1b2c3d4","approve":true,"feedback":"…"}'

TypeScript

import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.agent.reply({
  "kind": "plan",
  "requestId": "a1b2c3d4",
  "approve": true,
  "feedback": "…"
});

POST/agent/steerInterrupt a running turn

Slips a message into a turn already under way, without stopping it. This is how you redirect an agent mid-thought rather than waiting for it to finish being wrong. Give the message an id, and sending it again after a lost answer is met with what became of it the first time rather than saying it twice.

What you send

Field	Type	Where
`conversationId`requiredWhich running conversation to interrupt	string	body
`text`requiredWhat to say to it	string	body
`messageId`Your id for this message	string	body
`attachments`Files to send with it, as…	string[]	body
`mentions`Workspace paths the message mentions with…	string[]	body
`editorContext`What you have open, folded in…	object	body
`file`requiredThe file open in the editor,…	string	body
`startLine`First line of the selection, counting…	integer	body
`endLine`Last line of the selection, counting…	integer	body
`selection`The selected text itself	string	body

What comes back

Field	Type
`delivered`What became of the message: it…	"started" \| "steered" \| "queued"
`run`The run the message is in:…	string
`duplicate`The sandbox had already taken a…	true

Try itanswered in this tab

curl

curl -X POST "$SANDBOX/agent/steer" \
  -H "x-intentic-control: $INTENTIC_TOKEN" \
  -H "content-type: application/json" \
  -d '{"conversationId":"nightly-changelog","text":"export const start = () => listen(PORT);\n","messageId":"a1b2c3d4","attachments":["…","…"],"mentions":["…","…"],"editorContext":{"file":"…","startLine":1,"endLine":1,"selection":"…"}}'

TypeScript

import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.agent.steer({
  "conversationId": "nightly-changelog",
  "text": "export const start = () => listen(PORT);\n",
  "messageId": "a1b2c3d4",
  "attachments": [
    "…",
    "…"
  ],
  "mentions": [
    "…",
    "…"
  ],
  "editorContext": {
    "file": "…",
    "startLine": 1,
    "endLine": 1,
    "selection": "…"
  }
});

POST/agent/stopStop a turn now

Cancels the running turn inside the sandbox. Whatever it had already written to disk stays written, and whatever waits in the conversation's queue is held there, for everyone, until somebody resumes it. Name the run you mean: a stop that arrives after that run has ended cancels nothing, rather than whatever turn started next.

What you send

Field	Type	Where
`conversationId`requiredWhich conversation's running turn to cancel	string	body
`run`requiredThe run you mean to cancel,…	string	body

What comes back

Field	Type
`stopped`Whether a turn was cancelled	boolean
`running`The run that is live instead…	string

Try itanswered in this tab

curl

curl -X POST "$SANDBOX/agent/stop" \
  -H "x-intentic-control: $INTENTIC_TOKEN" \
  -H "content-type: application/json" \
  -d '{"conversationId":"nightly-changelog","run":"run_8c2f41d9"}'

TypeScript

import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.agent.stop({
  "conversationId": "nightly-changelog",
  "run": "run_8c2f41d9"
});

POST/agent/queue/editReword a waiting message

Changes what a message waiting in the conversation's queue says, keeping its place. Name the revision you read it at: if somebody changed it since, on this device or another, nothing is changed and you are told so.

What you send

Field	Type	Where
`conversationId`requiredWhose queue	string	body
`id`requiredWhich waiting message	string	body
`revision`requiredThe message's revision as you read…	integer	body
`text`requiredWhat the message should say instead	string	body

What comes back

Field	Type
`items`What waits, in the order it…	object[]
`id`The message's id: what its sender…	string
`text`The words, as they will go…	string
`attachments`Files that go with it, as…	string[]
`voice`Who it is from: a person,…	"person" \| "sandbox" \| "agent"
`queuedAt`When it joined the queue, in…	number
`revision`The queue's revision when this message…	integer
`revision`Moves with every change to the…	integer
`paused`Why nothing goes out by itself:…	"stopped" \| "refused" \| "scheduled"
`until`When scheduled messages go out by…	number
`after`The conversation whose finished work must…	string

Try itanswered in this tab

curl

curl -X POST "$SANDBOX/agent/queue/edit" \
  -H "x-intentic-control: $INTENTIC_TOKEN" \
  -H "content-type: application/json" \
  -d '{"conversationId":"nightly-changelog","id":"a1b2c3d4","revision":0,"text":"export const start = () => listen(PORT);\n"}'

TypeScript

import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.agent.queueEdit({
  "conversationId": "nightly-changelog",
  "id": "a1b2c3d4",
  "revision": 0,
  "text": "export const start = () => listen(PORT);\n"
});

POST/agent/queue/removeTake back a waiting message

Removes a message from the conversation's queue before the agent gets it. Name the revision you read it at: a message somebody reworded since is left alone, so you never take back words you have not seen.

What you send

Field	Type	Where
`conversationId`requiredWhose queue	string	body
`id`requiredWhich waiting message	string	body
`revision`requiredThe message's revision as you read…	integer	body

What comes back

Field	Type
`items`What waits, in the order it…	object[]
`id`The message's id: what its sender…	string
`text`The words, as they will go…	string
`attachments`Files that go with it, as…	string[]
`voice`Who it is from: a person,…	"person" \| "sandbox" \| "agent"
`queuedAt`When it joined the queue, in…	number
`revision`The queue's revision when this message…	integer
`revision`Moves with every change to the…	integer
`paused`Why nothing goes out by itself:…	"stopped" \| "refused" \| "scheduled"
`until`When scheduled messages go out by…	number
`after`The conversation whose finished work must…	string

Try itanswered in this tab

curl

curl -X POST "$SANDBOX/agent/queue/remove" \
  -H "x-intentic-control: $INTENTIC_TOKEN" \
  -H "content-type: application/json" \
  -d '{"conversationId":"nightly-changelog","id":"a1b2c3d4","revision":0}'

TypeScript

import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.agent.queueRemove({
  "conversationId": "nightly-changelog",
  "id": "a1b2c3d4",
  "revision": 0
});

POST/agent/queue/resumeLet waiting messages go

Releases a queue held after a stop or a refusal: what waits goes out now as one turn when nothing is running, or after the running turn otherwise. Name who serves that turn when the conversation has been re-pointed since the messages were queued.

What you send

Field	Type	Where
`conversationId`requiredWhose queue to let go	string	body
`routing`Who serves the turn the waiting…	object	body
`agent`requiredWhich provider serves the re-run	string	body
`harness`requiredWhich agentic loop runs it	"native" \| "claude-code"	body
`account`Which of that provider's accounts pays…	string	body
`model`Which model	string	body
`carry`When the account changes, keep the…	boolean	body

What comes back

Field	Type
`run`The turn the waiting messages started	string
`queue`The queue the release left: what…	object
`items`What waits, in the order it…	object[]
`id`The message's id: what its sender…	string
`text`The words, as they will go…	string
`attachments`Files that go with it, as…	string[]
`voice`Who it is from: a person,…	"person" \| "sandbox" \| "agent"
`queuedAt`When it joined the queue, in…	number
`revision`The queue's revision when this message…	integer
`revision`Moves with every change to the…	integer
`paused`Why nothing goes out by itself:…	"stopped" \| "refused" \| "scheduled"
`until`When scheduled messages go out by…	number
`after`The conversation whose finished work must…	string

Try itanswered in this tab

curl

curl -X POST "$SANDBOX/agent/queue/resume" \
  -H "x-intentic-control: $INTENTIC_TOKEN" \
  -H "content-type: application/json" \
  -d '{"conversationId":"nightly-changelog","routing":{"agent":"…","harness":"native","account":"work","model":"claude-sonnet-4-6","carry":true}}'

TypeScript

import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.agent.queueResume({
  "conversationId": "nightly-changelog",
  "routing": {
    "agent": "…",
    "harness": "native",
    "account": "work",
    "model": "claude-sonnet-4-6",
    "carry": true
  }
});

POST/agent/queue/scheduleReschedule waiting messages

Books what waits in the conversation's queue to go out by itself at another instant, or once another conversation has finished and its work has landed, holding it until then. Works on a queue that is held for any reason, or on messages waiting behind a running turn. A time already past, or a conversation with nothing left to land, lets them go now.

What you send

Field	Type	Where
`conversationId`requiredWhose queue	string	body
`sendAt`Send what waits at this instant…	integer	body
`sendAfter`Send what waits once that conversation…	string	body

What comes back

Field	Type
`items`What waits, in the order it…	object[]
`id`The message's id: what its sender…	string
`text`The words, as they will go…	string
`attachments`Files that go with it, as…	string[]
`voice`Who it is from: a person,…	"person" \| "sandbox" \| "agent"
`queuedAt`When it joined the queue, in…	number
`revision`The queue's revision when this message…	integer
`revision`Moves with every change to the…	integer
`paused`Why nothing goes out by itself:…	"stopped" \| "refused" \| "scheduled"
`until`When scheduled messages go out by…	number
`after`The conversation whose finished work must…	string

Try itanswered in this tab

curl

curl -X POST "$SANDBOX/agent/queue/schedule" \
  -H "x-intentic-control: $INTENTIC_TOKEN" \
  -H "content-type: application/json" \
  -d '{"conversationId":"nightly-changelog","sendAt":1,"sendAfter":"…"}'

TypeScript

import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.agent.queueSchedule({
  "conversationId": "nightly-changelog",
  "sendAt": 1,
  "sendAfter": "…"
});

POST/agent/resumeRun a refused turn again

Sends the same turn again when the model provider's allowance refused it, with everything it originally carried except who serves it: the caller may name a different provider, harness or account, which is the usual answer to a spent allowance. It repeats the request rather than adding a new message to the conversation, so pressing it twice costs nothing and the agent is never told to continue work it has not started.

What you send

Field	Type	Where
`conversationId`requiredWhich conversation's held turn to run…	string	body
`routing`Who serves the re-run, when the…	object	body
`agent`requiredWhich provider serves the re-run	string	body
`harness`requiredWhich agentic loop runs it	"native" \| "claude-code"	body
`account`Which of that provider's accounts pays…	string	body
`model`Which model	string	body
`carry`When the account changes, keep the…	boolean	body

What comes back

Field	Type
`run`The id of the run that…	string

Try itanswered in this tab

curl

curl -X POST "$SANDBOX/agent/resume" \
  -H "x-intentic-control: $INTENTIC_TOKEN" \
  -H "content-type: application/json" \
  -d '{"conversationId":"nightly-changelog","routing":{"agent":"…","harness":"native","account":"work","model":"claude-sonnet-4-6","carry":true}}'

TypeScript

import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.agent.resume({
  "conversationId": "nightly-changelog",
  "routing": {
    "agent": "…",
    "harness": "native",
    "account": "work",
    "model": "claude-sonnet-4-6",
    "carry": true
  }
});

POST/agent/accountMove a conversation to another account

Points the conversation at another connected account of the provider it runs on, for every turn from now on. It starts nothing by itself: with `run`, a turn held by a spent allowance or a stop runs again at once on that account, which is how a refused turn continues elsewhere. Without `carry` the next turn opens a fresh session seeded from the record.

What you send

Field	Type	Where
`conversationId`requiredWhich conversation to move	string	body
`account`requiredWhich of the conversation's provider's connected…	string	body
`carry`Keep the provider session across the…	boolean	body
`run`Also run a turn that a…	boolean	body

What comes back

Field	Type
`run`The run that re-ran a held…	string

Try itanswered in this tab

curl

curl -X POST "$SANDBOX/agent/account" \
  -H "x-intentic-control: $INTENTIC_TOKEN" \
  -H "content-type: application/json" \
  -d '{"conversationId":"nightly-changelog","account":"work","carry":true,"run":true}'

TypeScript

import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.agent.switchAccount({
  "conversationId": "nightly-changelog",
  "account": "work",
  "carry": true,
  "run": true
});

POST/agent/rewindGo back to an earlier message

Puts the files back as they stood at that point, drops every message after it, and forgets what the model remembered, so the next thing you say starts from there cleanly. Refused while a turn is running, because a restore cannot overwrite files an agent is editing; refused for a message with no saved state to return to; and refused when that position no longer holds the message you named, because the conversation moved since you read it.

What you send

Field	Type	Where
`conversationId`requiredWhich conversation to rewind	string	body
`index`requiredWhich message to go back to,…	integer	body
`messageId`requiredThe id of the message at…	string	body

What comes back

Field	Type
`snapshot`The saved point the files were…	string
`dropped`How many messages were removed	integer

Try itanswered in this tab

curl

curl -X POST "$SANDBOX/agent/rewind" \
  -H "x-intentic-control: $INTENTIC_TOKEN" \
  -H "content-type: application/json" \
  -d '{"conversationId":"nightly-changelog","index":0,"messageId":"a1b2c3d4"}'

TypeScript

import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.agent.rewind({
  "conversationId": "nightly-changelog",
  "index": 0,
  "messageId": "a1b2c3d4"
});

GET/agent/commandsShortcut commands the agent knows

The commands a provider published the last time one of its turns ran, so a composer can offer them before this conversation has run anything. A running turn's own list wins over this one.

What you send

Field	Type	Where
`agent`Whose commands to read	string	query

What comes back

Field	Type
`commands`The shortcut commands, as the provider…	object[]
`name`What to type, without the leading…	string
`description`What it does	string
`hint`What its argument should look like,…	string

Try itanswered in this tab

curl

curl "$SANDBOX/agent/commands" \
  -H "x-intentic-control: $INTENTIC_TOKEN"

TypeScript

import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.agent.commands();

POST/agent/route-chatChoose what a new chat opens on

Reads a new chat's opening message once and answers whichever of two questions it still has: the model, effort and account that conversation should run on, from what is connected and still has allowance left, and which of this sandbox's personas should handle it. `model` and `persona` on the ask say which halves to answer, and only those are put to the model. Asked once per chat, on the message actually sent, and never again: every turn after it runs on what the chat is wearing, which you are free to change. Answers with nothing, and a reason, whenever it cannot choose — a chat is never held up by this.

What you send

Field	Type	Where
`prompt`requiredThe message a new chat is…	string	body
`paths`Workspace paths the message names: uploads,…	string[]	body
`folder`The workspace folder the chat was…	string	body
`editorContext`Whether the message carries a file…	boolean	body
`planMode`Whether the chat opens in plan…	boolean	body
`model`requiredWhether to choose the model, effort…	boolean	body
`persona`requiredWhether to choose the persona: true…	boolean	body

What comes back

Field	Type
`persona`The persona half's answer, present only…	object
`id`The persona this message belongs to,…	string
`reason`Why, in the one clause a…	string
`model`The model half's answer, present only…	object
`pick`What the conversation should run on,…	object
`provider`Which provider serves the conversation	string
`model`Which of its models	string
`effort`How hard it should think, where…	string
`account`Which connected account pays, by its…	string
`reason`Why, in the one clause a…	string
`judge`Which model answered, as `provider:model`, so…	string

Try itanswered in this tab

curl

curl -X POST "$SANDBOX/agent/route-chat" \
  -H "x-intentic-control: $INTENTIC_TOKEN" \
  -H "content-type: application/json" \
  -d '{"prompt":"Update the changelog for the last five commits.","paths":["src/app.ts","README.md"],"folder":"…","editorContext":true,"planMode":true,"model":true,"persona":true}'

TypeScript

import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.agent.routeChat({
  "prompt": "Update the changelog for the last five commits.",
  "paths": [
    "src/app.ts",
    "README.md"
  ],
  "folder": "…",
  "editorContext": true,
  "planMode": true,
  "model": true,
  "persona": true
});

GET/agent/refusalsThe last time each provider said no

What each model provider most recently refused and why. Read this alongside an account's usage: the usage says how full it was when last checked, this says whether it has since started turning work away.

What you send

Nothing. Call it as it is.

What comes back

Field	Type
`refusals`The most recent refusal per provider	object

Try itanswered in this tab

curl

curl "$SANDBOX/agent/refusals" \
  -H "x-intentic-control: $INTENTIC_TOKEN"

TypeScript

import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.agent.refusals();