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.
SLACK	Can be chosen by a workspace admin to answer in Slack. Only an agent shared with the workspace (WORKSPACE visibility) can be chosen.

A custom agent must have at least one surface — an agent enabled only for CHAT can't be fired by automations, and vice versa. In the agent builder these are the Chat, Automation and Slack choices under "Where can this agent be used?".

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.
• Slack — when a workspace admin chooses the agent under Settings → Integrations → Slack, it answers everyone who asks Nova in Slack, as the person asking. Requires the SLACK 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.
• My agent isn't offered for Slack. Add the SLACK surface and set its visibility to WORKSPACE.