Agent setup

Personas

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

On this page(8 sections)

The characters an agent can wear
Create or edit a persona
Delete a persona
What one persona carries
Write a persona's instructions
Read one of a persona's skills
Write one of a persona's skills
Delete one of a persona's skills

A persona 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 persona with the connected accounts it speaks for, what a conversation wearing it is allowed to do, and where it works.

What you send

Nothing. Call it as it is.

What comes back

Field	Type
`personas`The characters an agent can wear	object[]
`id`The persona's id	string
`label`What to call it on screen	string
`capabilities`Which connected accounts are its hands	string[]
`repos`Which repositories prefer this persona, so…	string[]
`powers`What a conversation wearing it may…	object
`files`What it may do with files:…	"none" \| "read" \| "write"
`shell`Whether it may run commands, and…	boolean
`code`Whether it may write and run…	boolean
`web`Whether it may fetch a page…	boolean
`browser`	boolean
`delegate`	boolean
`sandbox`	boolean
`connectors`	string[]
`computers`	string[]
`mcp`	string[]
`workspace`Where it works	object
`startIn`Which folder a conversation opens in	string
`folders`Which folders it may touch at…	string[]
`systemPromptMode`	"intentic" \| "claude" \| "custom"
`connected`Which 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.personas.list();

POST/personasCreate or edit a persona

Writes the whole card; sending an id that exists edits it. Nothing is connected, installed or spent by saving one, because a persona 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

Field	Type	Where
`id`requiredThe persona's id	string	body
`label`What to call it on screen	string	body
`capabilities`requiredWhich connected accounts are its hands	string[]	body
`repos`Which repositories prefer this persona, so…	string[]	body
`powers`What a conversation wearing it may…	object	body
`files`What it may do with files:…	"none" \| "read" \| "write"	body
`shell`Whether it may run commands, and…	boolean	body
`code`Whether it may write and run…	boolean	body
`web`Whether it may fetch a page…	boolean	body
`browser`	boolean	body
`delegate`	boolean	body
`sandbox`	boolean	body
`connectors`	string[]	body
`computers`	string[]	body
`mcp`	string[]	body
`workspace`Where it works	object	body
`startIn`Which folder a conversation opens in	string	body
`folders`Which folders it may touch at…	string[]	body
`systemPromptMode`	"intentic" \| "claude" \| "custom"	body

What comes back

Field	Type
`ok`Always true	true

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":["…","…"],"repos":["root","site"],"powers":{"files":"none","shell":true,"code":true,"web":true,"browser":true,"delegate":true,"sandbox":true,"connectors":["…","…"],"computers":["…","…"],"mcp":["…","…"]},"workspace":{"startIn":"…","folders":["…","…"]},"systemPromptMode":"intentic"}'

TypeScript

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

const result = await sandbox.personas.save({
  "id": "a1b2c3d4",
  "label": "Nightly changelog",
  "capabilities": [
    "…",
    "…"
  ],
  "repos": [
    "root",
    "site"
  ],
  "powers": {
    "files": "none",
    "shell": true,
    "code": true,
    "web": true,
    "browser": true,
    "delegate": true,
    "sandbox": true,
    "connectors": [
      "…",
      "…"
    ],
    "computers": [
      "…",
      "…"
    ],
    "mcp": [
      "…",
      "…"
    ]
  },
  "workspace": {
    "startIn": "…",
    "folders": [
      "…",
      "…"
    ]
  },
  "systemPromptMode": "intentic"
});

DELETE/personas/{id}Delete a persona

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

Field	Type	Where
`id`requiredWhich persona	string	address

What comes back

Field	Type
`ok`Always true	true

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.personas.remove({
  "id": "a1b2c3d4"
});

GET/personas/{id}/kitWhat one persona carries

The instructions this persona 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

Field	Type	Where
`id`requiredWhich persona	string	address

What comes back

Field	Type
`prompt`What this persona is told, on…	string
`skills`Skills only this persona's conversations can…	object[]
`name`The skill's name	string
`description`What it is for	string

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.personas.kit({
  "id": "a1b2c3d4"
});

POST/personas/{id}/promptWrite a persona's instructions

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

What you send

Field	Type	Where
`id`requiredWhich persona	string	address
`prompt`requiredWhat to tell this persona	string	body

What comes back

Field	Type
`ok`Always true	true

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.personas.savePrompt({
  "id": "a1b2c3d4",
  "prompt": "Update the changelog for the last five commits."
});

GET/personas/{id}/skills/readRead one of a persona's skills

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

What you send

Field	Type	Where
`id`requiredWhich persona	string	address
`name`requiredWhich skill	string	query

What comes back

Field	Type
`name`The skill's name	string
`description`What it is for	string
`body`The skill itself, in full	string

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.personas.readSkill({
  "id": "a1b2c3d4",
  "name": "nightly changelog"
});

POST/personas/{id}/skillsWrite one of a persona's skills

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

What you send

Field	Type	Where
`id`requiredWhich persona	string	address
`name`requiredWhat to call it	string	body
`description`requiredWhat it is for, which is…	string	body
`body`requiredThe skill itself	string	body

What comes back

Field	Type
`ok`Always true	true

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.personas.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 persona's skills

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

What you send

Field	Type	Where
`id`requiredWhich persona	string	address
`name`requiredWhich skill	string	body

What comes back

Field	Type
`ok`Always true	true

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.personas.removeSkill({
  "id": "a1b2c3d4",
  "name": "nightly changelog"
});