Agents

Agents are AI personas that participate in debate rounds. Each agent has a name, role, personality, and a detailed system prompt that defines how it reasons. Agents are workspace-scoped and persist across conversations.

List all agent personas in your workspace.

Response

{
  "agents": [
    {
      "id": "agent_xxx",
      "name": "Victoria Chen",
      "role": "CFO",
      "personality": "analytical, risk-averse, data-driven",
      "decisionStyle": "conservative",
      "isDevilsAdvocate": false,
      "createdAt": "2026-06-01T09:00:00Z"
    }
  ]
}

Create a new agent persona. Agents immediately participate in new debate rounds in this workspace.

Request body

Name	Type	Required	Description
`name`	`string`	required	Agent display name
`role`	`string`	required	Job title or functional role (e.g. "CFO", "Growth Lead")
`personality`	`string`	required	Comma-separated personality traits
`mission`	`string`	required	One-sentence mission statement guiding the agent's decisions
`decisionStyle`	`string`	required	"conservative" \| "aggressive" \| "analytical" \| "systematic"
`systemPrompt`	`string`	required	Full system prompt text for this agent's behavior
`isDevilsAdvocate`	`boolean`	optional	If true, agent always challenges the prevailing view

Response

{
  "agent": {
    "id": "agent_yyy",
    "name": "Aria",
    "role": "CTO",
    ...
  }
}

curl -X POST https://api.yourdomain.com/v1/agents \
  -H "x-api-key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Aria",
    "role": "CTO",
    "personality": "technical, visionary, pragmatic",
    "mission": "Ensure every decision is technically sound and scalable",
    "decisionStyle": "analytical",
    "systemPrompt": "You are Aria, a senior CTO..."
  }'

Update any field on an existing agent. All fields are optional — only supplied fields are updated.

Path / Query parameters

Name	Type	Required	Description
`id`	`string`	required	Agent ID

Request body

Name	Type	Required	Description
`name`	`string`	optional	New display name
`role`	`string`	optional	Updated role
`personality`	`string`	optional	Updated personality traits
`mission`	`string`	optional	Updated mission statement
`systemPrompt`	`string`	optional	Updated system prompt

Permanently delete an agent and all its memories from your workspace. Returns 204 No Content.

Path / Query parameters

Name	Type	Required	Description
`id`	`string`	required	Agent ID

Agent Memory

Each agent maintains a persistent memory of facts about the user gathered across conversations. You can read and add memory entries via the API to pre-populate context or inspect what an agent knows.

List all memory entries for an agent.

Path / Query parameters

Name	Type	Required	Description
`id`	`string`	required	Agent ID

Response

{
  "memory": [
    {
      "id": "mem_abc",
      "agentId": "agent_xxx",
      "key": "preferred_meeting_style",
      "value": "User prefers async first, then 30-min syncs",
      "createdAt": "2026-06-01T09:00:00Z"
    }
  ]
}

Add a memory entry to an agent. Useful for pre-seeding agent context before a conversation.

Path / Query parameters

Name	Type	Required	Description
`id`	`string`	required	Agent ID

Request body

Name	Type	Required	Description
`key`	`string`	required	Short snake_case label for this memory fact
`value`	`string`	required	The fact to remember (1-2 sentences max)

Response

{
  "memory": {
    "id": "mem_xyz",
    "agentId": "agent_xxx",
    "key": "risk_tolerance",
    "value": "User is highly risk-averse — prefers conservative financial advice",
    "createdAt": "2026-06-04T10:00:00Z"
  }
}

Delete a specific memory entry from an agent. Returns 204 No Content.

Path / Query parameters

Name	Type	Required	Description
`id`	`string`	required	Agent ID
`memoryId`	`string`	required	Memory entry ID