intentic
Download the app
Download the app
Agent setup

Roles

Named characters an agent can wear: the accounts it speaks for and what it is told

On this page(8 sections)

A role records a decision about accounts that already exist: which of them this character speaks for, what a conversation wearing it may do, and what it is told. The kit routes edit the files behind one — its own instructions, and the skills only its conversations reach.

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

GET/personasThe characters an agent can wear

Each role with the connected accounts it speaks for, where a conversation wearing it opens, and what it is told. What it may reach is the access profiles that list it.

What you send

Nothing. Call it as it is.

What comes back

FieldType
rolesThe characters an agent can wearobject[]
idThe role's idstring
labelWhat to call it on screenstring
capabilitiesWhich signed-in accounts it speaks through:…string[]
briefWhat this role is for, in…string
workspaceWhere a conversation wearing it opensobject
startInWhich folder a conversation opens instring
contextWhich part of the workspace a…object
reposWhich nested repositories a conversation on…string[]
briefingWhich of the notes the sandbox…object
omitWhich of the notes the sandbox…"map" | "context" | "skills" | "search" … (9)[]
modelsWhich models a conversation wearing it…object[]
providerWhich provider serves this workstring
modelWhich of its modelsstring
effortHow hard this model should think,…string
thinkingWhether this model reasons before it…boolean
fastAsk for this model's work at…boolean
harnessWhich agentic loop runs it"native" | "claude-code" | "codex" | "opencode" … (7)
systemPromptMode"intentic" | "claude" | "custom"
connectedWhich accounts are actually connected right…string[]
Try itanswered in this tab
curl
curl "$SANDBOX/personas" \
  -H "x-intentic-control: $INTENTIC_TOKEN"
TypeScript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.roles.list();
POST/personasCreate or edit a role

Writes the whole card; sending an id that exists edits it. Nothing is connected, installed or spent by saving one, because a role only records a decision about accounts that already exist. It is stored as a file you can equally well edit by hand, which is why this writes the card whole rather than patching a field: a round trip through a screen should leave a change a reviewer recognises.

What you send

FieldTypeWhere
idrequiredThe role's idstringbody
labelWhat to call it on screenstringbody
capabilitiesrequiredWhich signed-in accounts it speaks through:…string[]body
briefWhat this role is for, in…stringbody
workspaceWhere a conversation wearing it opensobjectbody
startInWhich folder a conversation opens instringbody
contextWhich part of the workspace a…objectbody
reposrequiredWhich nested repositories a conversation on…string[]body
briefingWhich of the notes the sandbox…objectbody
omitrequiredWhich of the notes the sandbox…"map" | "context" | "skills" | "search" … (9)[]body
modelsWhich models a conversation wearing it…object[]body
providerrequiredWhich provider serves this workstringbody
modelrequiredWhich of its modelsstringbody
effortHow hard this model should think,…stringbody
thinkingWhether this model reasons before it…booleanbody
fastAsk for this model's work at…booleanbody
harnessWhich agentic loop runs it"native" | "claude-code" | "codex" | "opencode" … (7)body
systemPromptMode"intentic" | "claude" | "custom"body

What comes back

FieldType
okAlways truetrue
Try itanswered in this tab
curl
curl -X POST "$SANDBOX/personas" \
  -H "x-intentic-control: $INTENTIC_TOKEN" \
  -H "content-type: application/json" \
  -d '{"id":"a1b2c3d4","label":"Nightly changelog","capabilities":["…","…"],"brief":"…","workspace":{"startIn":"…"},"context":{"repos":["root","site"]},"briefing":{"omit":["map","context"]},"models":[{"provider":"claude","model":"claude-sonnet-4-6","effort":"…","thinking":true,"fast":true,"harness":"native"},{"provider":"claude","model":"claude-haiku-4-6","effort":"…","thinking":true,"fast":true,"harness":"claude-code"}],"systemPromptMode":"intentic"}'
TypeScript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.roles.save({
  "id": "a1b2c3d4",
  "label": "Nightly changelog",
  "capabilities": [
    "…",
    "…"
  ],
  "brief": "…",
  "workspace": {
    "startIn": "…"
  },
  "context": {
    "repos": [
      "root",
      "site"
    ]
  },
  "briefing": {
    "omit": [
      "map",
      "context"
    ]
  },
  "models": [
    {
      "provider": "claude",
      "model": "claude-sonnet-4-6",
      "effort": "…",
      "thinking": true,
      "fast": true,
      "harness": "native"
    },
    {
      "provider": "claude",
      "model": "claude-haiku-4-6",
      "effort": "…",
      "thinking": true,
      "fast": true,
      "harness": "claude-code"
    }
  ],
  "systemPromptMode": "intentic"
});
DELETE/personas/{id}Delete a role

Takes away the character, never the accounts: every login it named stays connected. Its own prompt and skills go with it, since a folder nothing can reach is worse than deleting what somebody just asked to delete. Anything still pointed at it goes quiet rather than falling back to speaking as everyone.

What you send

FieldTypeWhere
idrequiredWhich rolestringaddress

What comes back

FieldType
okAlways truetrue
Try itanswered in this tab
curl
curl -X DELETE "$SANDBOX/personas/a1b2c3d4" \
  -H "x-intentic-control: $INTENTIC_TOKEN"
TypeScript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.roles.remove({
  "id": "a1b2c3d4"
});
GET/personas/{id}/kitWhat one role carries

The instructions this role is given and the skills only its conversations can reach. A different question from what the agent knows generally, with a different answer.

What you send

FieldTypeWhere
idrequiredWhich rolestringaddress

What comes back

FieldType
promptWhat this role is told, on…string
skillsSkills only this role's conversations can…object[]
nameThe skill's namestring
descriptionWhat it is forstring
Try itanswered in this tab
curl
curl "$SANDBOX/personas/a1b2c3d4/kit" \
  -H "x-intentic-control: $INTENTIC_TOKEN"
TypeScript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.roles.kit({
  "id": "a1b2c3d4"
});
POST/personas/{id}/promptWrite a role's instructions

Sets what this role is told. Saving an empty one removes it entirely rather than storing a blank, so the role simply falls back to the sandbox's own instructions.

What you send

FieldTypeWhere
idrequiredWhich rolestringaddress
promptrequiredWhat to tell this rolestringbody

What comes back

FieldType
okAlways truetrue
Try itanswered in this tab
curl
curl -X POST "$SANDBOX/personas/a1b2c3d4/prompt" \
  -H "x-intentic-control: $INTENTIC_TOKEN" \
  -H "content-type: application/json" \
  -d '{"prompt":"Update the changelog for the last five commits."}'
TypeScript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.roles.savePrompt({
  "id": "a1b2c3d4",
  "prompt": "Update the changelog for the last five commits."
});
GET/personas/{id}/skills/readRead one of a role's skills

The full text of a single skill belonging to this role.

What you send

FieldTypeWhere
idrequiredWhich rolestringaddress
namerequiredWhich skillstringquery

What comes back

FieldType
nameThe skill's namestring
descriptionWhat it is forstring
bodyThe skill itself, in fullstring
Try itanswered in this tab
curl
curl "$SANDBOX/personas/a1b2c3d4/skills/read?name=nightly%20changelog" \
  -H "x-intentic-control: $INTENTIC_TOKEN"
TypeScript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.roles.readSkill({
  "id": "a1b2c3d4",
  "name": "nightly changelog"
});
POST/personas/{id}/skillsWrite one of a role's skills

Creates or replaces a skill by name. There is nothing to switch on: a role's skill is available exactly when that role is worn, which is what belonging to it has to mean.

What you send

FieldTypeWhere
idrequiredWhich rolestringaddress
namerequiredWhat to call itstringbody
descriptionrequiredWhat it is for, which is…stringbody
bodyrequiredThe skill itselfstringbody

What comes back

FieldType
okAlways truetrue
Try itanswered in this tab
curl
curl -X POST "$SANDBOX/personas/a1b2c3d4/skills" \
  -H "x-intentic-control: $INTENTIC_TOKEN" \
  -H "content-type: application/json" \
  -d '{"name":"nightly changelog","description":"Runs every night and opens a pull request when anything changed.","body":"…"}'
TypeScript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.roles.saveSkill({
  "id": "a1b2c3d4",
  "name": "nightly changelog",
  "description": "Runs every night and opens a pull request when anything changed.",
  "body": "…"
});
POST/personas/{id}/skills/removeDelete one of a role's skills

Removes a single skill from this role and leaves the rest of its kit alone.

What you send

FieldTypeWhere
idrequiredWhich rolestringaddress
namerequiredWhich skillstringbody

What comes back

FieldType
okAlways truetrue
Try itanswered in this tab
curl
curl -X POST "$SANDBOX/personas/a1b2c3d4/skills/remove" \
  -H "x-intentic-control: $INTENTIC_TOKEN" \
  -H "content-type: application/json" \
  -d '{"name":"nightly changelog"}'
TypeScript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.roles.removeSkill({
  "id": "a1b2c3d4",
  "name": "nightly changelog"
});
More in Agent setup

Type to search every page, in the docs and the API reference.