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", "email"],
    "skills": ["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": "assistant",
  "system_prompt": "You are an expert code reviewer...",
  "persona_id": "uuid-optional",
  "tools": ["github", "gitlab"],
  "skills": ["code-review"],
  "temperature": 0.3,
  "max_tokens": 4096,
  "provider_chain_id": "uuid-optional"
}

Returns 201 Created with the agent object.

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`
`system_prompt`	`string`	Agent instructions
`persona_id`	`uuid?`	Optional persona
`tools`	`string[]`	Tool keys the agent can use
`skills`	`string[]`	Skill keys injected into system prompt
`temperature`	`float`	LLM temperature (0–2)
`max_tokens`	`int`	Max tokens per response
`provider_chain_id`	`uuid?`	Provider chain for this 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",
  "memory_type": "preference"
}

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:


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

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.