Agents

Agents are the core unit in Nexora. Each agent has a persona, system prompt, tool set, skills, and a provider chain.

List agents


GET /api/agents
Authorization: Bearer nxr_...

Response:


[
  {
    "id": "uuid",
    "name": "Research Assistant",
    "description": "Searches the web and summarizes findings",
    "agent_type": "assistant",
    "is_active": true,
    "tools": ["github", "web_search"],
    "skills": ["web_search", "summarize"],
    "created_at": "2026-01-01T00:00:00Z"
  }
]

Get agent


GET /api/agents/{agent_id}
Authorization: Bearer nxr_...

Create agent


POST /api/agents
Authorization: Bearer nxr_...
Content-Type: application/json
 
{
  "name": "Code Reviewer",
  "description": "Reviews pull requests and suggests improvements",
  "agent_type": "custom",
  "system_prompt": "You are an expert code reviewer...",
  "tools": ["github_read", "gitlab_read"],
  "skills": ["github_read"],
  "temperature": 0.3,
  "max_tokens": 8192,
  "max_subagents": 5,
  "max_concurrency": 2
}

Returns 201 Created with the agent object. agent_type defaults to custom if omitted.

Update agent


PATCH /api/agents/{agent_id}
Authorization: Bearer nxr_...
Content-Type: application/json
 
{
  "name": "Updated Name",
  "tools": ["github"]
}

Partial update — only provided fields change.

Delete agent


DELETE /api/agents/{agent_id}
Authorization: Bearer nxr_...

Returns 204 No Content. Soft-deleted agents can be restored.

Restore agent


PATCH /api/agents/{agent_id}/restore
Authorization: Bearer nxr_...

Agent schema

Field	Type	Description
`id`	`uuid`	Unique identifier
`name`	`string`	Display name
`description`	`string`	Short description
`agent_type`	`string`	One of `architect`, `assistant`, `coordinator`, `custom`, `devops`, `project_manager` (default `custom`)
`system_prompt`	`string`	Agent instructions
`soul`	`object`	Persona/identity config (free-form)
`tools`	`string[]`	Tool keys the agent can use
`skills`	`string[]`	Skill keys injected into system prompt
`model_pref`	`string?`	Preferred model identifier
`temperature`	`float`	LLM temperature (0–2, default 0.3)
`max_tokens`	`int`	Max tokens per response (default 8192)
`max_subagents`	`int`	Max sub-agents (default 5)
`max_concurrency`	`int`	Max concurrent sub-agents (default 2)
`mcps`	`object[]`	MCP server configs attached to the agent
`is_active`	`bool`	Whether the agent is enabled

Memories

Agents can store persistent memories that persist across conversations.

List memories


GET /api/agents/{agent_id}/memories
Authorization: Bearer nxr_...

Create memory


POST /api/agents/{agent_id}/memories
Authorization: Bearer nxr_...
Content-Type: application/json
 
{
  "content": "User prefers TypeScript over JavaScript",
  "type": "fact",
  "tags": ["preferences"],
  "priority": 3
}

type is one of fact, instruction, context, example (default fact). priority is 1–5 (default 3).

Update memory


PATCH /api/agents/{agent_id}/memories/{memory_id}
Authorization: Bearer nxr_...
Content-Type: application/json
 
{ "content": "Updated memory content" }

Delete memory


DELETE /api/agents/{agent_id}/memories/{memory_id}
Authorization: Bearer nxr_...

Builtin agents

Builtin agents ship with Nexora and are defined in seeds/agents/builtin/. List them as templates:


GET /api/agents/templates

(GET /api/agents/types/builtin returns the builtin persona types used to seed new agents.) Builtin agents cannot be deleted but can be cloned via create with the same fields.

Sub-agents

Agents can spawn sub-agents during a conversation. The orchestrator coordinates via Redis and aggregates results before resuming the parent.

Sub-agent delegation is automatic — the LLM emits a tool call in a special fence format. The platform intercepts it, dispatches the sub-agent, and resumes the parent with the result. No API call needed to trigger sub-agents.