Nova Agent Builder

Nova Agent Builder lets a workspace user create their own custom Nova agent: a named, workspace-scoped assistant with its own instructions, capabilities, and knowledge scope.

The core principle: capabilities gate writes only

• Reads are always on. Every agent — system or custom — can always search objects, read types, run aggregations, read documentation and Docs pages, use the calculator, read date/time, look up user info, search the web, and read spaces. Not configurable.
• Writes are opt-in. What you configure on a custom agent is which write actions it may perform — nothing more.
• Admin/site/workflow writes are reserved for system agents and can never be enabled on a custom agent.

Building a custom agent is about narrowing behavior and scoping data (instructions + knowledge), and granting a small, safe set of write permissions (capabilities). It can always read.

Configuring a custom agent

Field	Required	Default	Meaning
name	Yes	—	Display name.
description	No	—	Short human description.
instructions	No	—	A free-text persona/behavior prompt, injected into the agent's system prompt at runtime.
visibility	No	PRIVATE	PRIVATE — only the creator can see and use it. WORKSPACE — everyone in the workspace can use it.
conversationStarters	No	none	Suggested prompts shown to users.
Capabilities (subAgentTypes)	No	none	The write permissions the agent may use — see below.
Surfaces	No	CHAT	Where the agent can run — see below.

Visibility default nuance

The create API defaults visibility to PRIVATE, even though the database column itself defaults to WORKSPACE — an agent created without explicitly setting visibility ends up PRIVATE. Always set it explicitly to avoid surprises.

Knowledge sources are configured separately, after creation.

Capabilities

Ten capabilities can be enabled on a custom agent — all object, comment, or Docs writes; none require admin access.

Capability	Allows
OBJECT_CREATE	Create objects
OBJECT_UPDATE	Update existing objects' attributes
OBJECT_TRANSITION	Move objects through workflow states
OBJECT_DELETE	Delete objects
COMMENT_CREATE	Post comments
COMMENT_UPDATE	Edit comments
COMMENT_DELETE	Delete comments
COMMENT_REACTION	Add/remove emoji reactions on comments
DOCS_CREATE	Create Docs pages
DOCS_UPDATE	Update Docs pages

The live, authoritative list is available at GET /external/v1/nova-agent/capabilities. Enabling anything outside this list (an admin/site/workflow write) is rejected with Capability <X> cannot be enabled on a custom agent.

Always-on reads (not configurable): search, types, aggregations, documentation, Docs, the calculator, date/time, user info, web search, and spaces.

Knowledge sources

Knowledge sources constrain what data the agent reasons over — every search and aggregation it performs stays inside the configured scope.

Source type	Input	Meaning
TYPE	a type ID	Scope to objects of one Starhive type. Rejected with Type <id> is not accessible in this workspace if the type isn't accessible to the caller.
STARQL_QUERY	a StarQL query	Scope to the results of that query.

Knowledge is additive — add as many sources as needed; each is managed and removable individually.

Surfaces

Surface	Meaning
CHAT	Available in interactive chat, with streamed responses.
AUTOMATION	Can be invoked headlessly by an automation trigger.

A custom agent must have at least one surface — an agent enabled only for CHAT can't be fired by automations, and vice versa.

Permissions and ownership

Action	Who's allowed
View a system agent	Everyone, in every workspace
View a WORKSPACE custom agent	Anyone in the same workspace
View a PRIVATE custom agent	Only the creator
Edit, delete, or change capabilities/knowledge	Only the creator — even for a WORKSPACE-visible agent
Edit a system agent	Nobody — rejected with System Nova agents cannot be modified

Deleting a custom agent is a soft delete: it's marked deleted and the deletion cascades to the agent's conversations, rather than hard-deleting anything.

Invoking a custom agent

• Chat — selected by ID in a conversation, runs through the streaming chat controller. Requires the CHAT surface.
• Automation — an automation/event trigger invokes the agent with the triggering object IDs prepended to the prompt as context, running as the triggering user, fire-and-forget. Requires the AUTOMATION surface.

FAQ

• Why can't my agent read a certain object? A bound knowledge source scopes it — and reads are always further bounded by the invoking user's own permissions.
• My agent can't write even though I enabled the capability. Check that the invoking user also has permission to perform that write — the agent acts as the user, not with elevated access.
• Colleagues can't see my agent. Visibility defaults to PRIVATE — set it to WORKSPACE.
• A colleague can use but not edit my workspace agent. By design — only the creator can edit.
• My automation can't trigger the agent. Add the AUTOMATION surface.