novo agents
start free

Capabilities

Capabilities switch built-in tools and behaviors on for an agent. New agents default to subagents: true, so a run can delegate focused work when that produces a better answer. See Subagents. Other optional capabilities are one-field additions: browser, workspace, web, media, MCP, GitHub, human review, and artifact delivery are built to drop into your product without standing up separate agent infrastructure.

Agents receive text plus staged file attachments. Media attachments become run-scoped artifacts. Cloud agents have a baseline read-only view_media tool for image, audio, and video artifacts; capabilities.mediaView only configures its output policy. The tool accepts exactly one source, either { artifactId } or { url } (a direct HTTPS link), and detects the media type automatically. By default (output: 'auto') it returns native media bytes when the current run can use them, and falls back to detailed text analysis otherwise. Add analysisPrompt to focus text analysis when analysis is returned. Set capabilities.mediaView.output = 'analysis' to always return text analysis, which is useful for cost control or deterministic behavior, since native media bytes consume model context tokens on every subsequent turn.

const agent = await novo.agents.create({
  context: 'You triage GitHub issues.',
  band: 'core',
  capabilities: {
    web: true,
    userInteraction: true,
  },
});

One vocabulary

Novo names capabilities with a single family vocabulary. Learn a family once and you can read it across config and policy surfaces.

| Family | Configure via | |---|---| | web | capabilities.web | | files | workspace.filesystem | | shell | workspace.shell | | documents | workspace.documents | | media editing | workspace.mediaEditing | | media generation | capabilities.media | | view media | capabilities.mediaView | | browser | capabilities.browser | | MCP tools | capabilities.mcp | | HTTP connections | capabilities.http | | GitHub | capabilities.github | | user interaction | capabilities.userInteraction | | subagents | capabilities.subagents | | skills | capabilities.skills |

Delegated subagents follow the same family safety boundaries, but consumers do not configure per-subagent routes. Novo routes advisor and worker tasks to the best available model/configuration for the job while keeping authority clamped to the parent. Advisors are read-only critique routes; workers are the execution routes that can receive additional authority. GitHub workflow authority, user interaction, and further delegation are never passed to a worker or advisor.

The file-operating families (files, shell, documents, and mediaEditing) are configured on the top-level workspace, not on capabilities. HTTP connections are configured through the SDK/API (novo.httpConnections) or the console adapters screen, then attached with capabilities.http. Everything else in the table below is a capabilities field.

The full list

| Capability | Shape | What it does | |---|---|---| | web | boolean | Search the web and fetch URLs. | | browser | boolean \| { authenticated?: { profileKey: string }; files?: boolean; tabs?: boolean } | Managed cloud browser. true enables the deterministic browser tools; files, tabs, and authenticated persistent profiles are explicit opt-ins. Pixel-coordinate fallback for canvas/WebGL is handled internally. | | userInteraction | boolean | The model can call ask_question to pause the run, surface a question, and wait for your interactions.resolve(...). See Human in the loop. | | subagents | boolean | Defaults on for new agents. Enables delegation to subagents and emits data-novo-task stream cards with worker streams. Subagent cost rolls into the run's budget. Set false to opt out. Each subagent inherits a read-only floor. Advisors stay read-only. Workers can receive additional authority under Novo's internal route policy, clamped to what the parent itself holds; github, user interaction, and further delegation are never delegated to a child. | | media | boolean \| { image?: boolean; video?: boolean; speech?: boolean; music?: boolean; soundEffect?: boolean } | Managed media generation. true enables all generators; the object form enables a subset for cost control. Tools: generate_image, generate_video, generate_speech, generate_music, generate_sound_effect. generate_video also iterates on a previously generated video when given its artifact id; each edit returns a new artifact. Billing is per modality: image per token, video and music per second, speech per character, sound effects per generation (or by duration when a fixed duration is requested). See pricing. | | mediaView | { output?: 'analysis' \| 'auto' } | Optional output policy for the baseline read-only view_media tool. Defaults to auto (native bytes when the caller model can consume them, else text analysis); set analysis to always return text. | | github | { connectionId: string; repositories?: string[]; git?: { branchPrefix?: string; baseBranches?: string[] }; allowedTools?: string[]; blockedTools?: string[]; approval?: 'once' \| 'always' \| 'never'; gatedTools?: string[] } | App-backed GitHub tools for repositories, code, issues, pull requests, search, commits, Actions, and optional account-scoped gists. Requires a managed workspace with filesystem, shell, and network access. Tokens are minted per operation in Novo's worker. | | mcp | { toolServerIds: string[] } | Wires registered MCP tool servers into this agent's toolset; their tools become callable as mcp__{server}__*. | | http | { connectionIds: string[] } | Wires registered HTTP connections into this agent's toolset; operations become callable as api__{connection}__*. |

Managed video generation accepts a single prompt up to 2000 characters. Shorter one-scene prompts are more reliable: describe one scene with one primary motion, and split multi-beat narratives into separate video calls instead of asking one short clip to choreograph a whole sequence.

The file-operating families, documents (managed Office/PDF tools) and mediaEditing (managed image/audio/video editing), are configured on the managed workspace, not here, because they operate on real workspace files through Novo's managed processor.

Planning is not a capability because it is always on: every agent can call todo to track multi-step work, so there is no field to enable it. Its tool calls surface as ordinary tool-* chunks on the stream.

Artifact delivery is top-level config

Artifact delivery is not a capability because it does not change what tools the model can call. Configure it with top-level artifacts on the agent:

await novo.agents.update(agent.id, {
  artifacts: {
    stream: { urls: 'durable-only' },
    exports: {
      resultHandlerId: 'rh_drive',
      include: {
        generatedDeliverables: true,
        workspaceExports: true,
        browserScreenshots: false,
        browserDownloads: false,
      },
    },
    oversizedToolResults: { resultHandlerId: 'rh_archive' },
  },
});

artifacts.exports promotes generated image/video/audio/music/sound-effect outputs and explicit workspace_export_artifact({ path }) outputs to a result handler. Browser screenshots export only when include.browserScreenshots is true; browser downloads export only when include.browserDownloads is true. Ordinary document outputs, previews, render artifacts, extracted images, and oversized tool output are not part of this export path.

artifacts.oversizedToolResults is only for oversized tool-output recovery/archive. It is primary when workspace spill is unavailable, and archival/fallback when workspace spill is available.

artifacts.stream.urls defaults to durable-only: public/model-visible artifact refs use the handler durable URL when present or an id-only Novo transfer handle otherwise. Set include-novo-signed only if the consumer wants temporary Novo signed URLs in tool results and streams.

Filesystem and shell need a workspace

Use top-level workspace for new agents. Managed workspaces are hosted by Novo; remote workspaces point at your own registered environment.

const agent = await novo.agents.create({
  context: 'You refactor TypeScript projects.',
  band: 'core',
  workspace: {
    type: 'managed',
    seed: { type: 'git', url: 'https://github.com/acme/app.git' },
  },
});

For customer-owned runtimes, register an environment first, then use workspace: { type: 'remote', environmentId }:

const env = await novo.environments.register({
  type: 'http_workspace',
  name: 'workspace',
  url: 'https://workspace.acme.dev/novo',
  secret: 'env_secret_…',
});

const agent = await novo.agents.create({
  context: 'You refactor TypeScript projects.',
  band: 'core',
  workspace: { type: 'remote', environmentId: env.id },
});

Filesystem and shell tools are configured through top-level workspace, not capabilities.

GitHub capability

capabilities.github gives an agent Novo's first-party GitHub workflow tools through an organization-scoped GitHub App connection:

const authorization = await novo.githubConnections.authorize({
  name: 'acme-app',
});

// Send the operator to authorization.url, then wait for completed status.
const connection = (
  await novo.githubConnections.getAuthorization(authorization.id)
).connection;

const agent = await novo.agents.create({
  context: 'You triage issues and pull requests in acme/app.',
  band: 'core',
  workspace: { type: 'managed', filesystem: true, shell: true },
  capabilities: {
    github: {
      connectionId: connection.id,
      repositories: ['acme/app'],
    },
  },
});

Novo exposes the tools admitted by the connection and agent config. The family covers repository files and commits, issues and labels, pull requests and reviews, code search, Actions, and optional account-scoped gists. repositories narrows the connection grant for one agent. allowedTools and blockedTools provide mutually exclusive filters over the published tool catalog. Writes request approval by default; gatedTools accepts known write names when approval is once or always. Every GitHub-enabled agent has a managed working tree; use git.branchPrefix and git.baseBranches to narrow its publication policy.

The workspace extension tools clone and fetch only inside a scoped egress window that injects the short-lived authorization header. The remote remains a plain GitHub HTTPS URL. Local git status, git diff, git add, git commit, and project test commands work normally. Remote clone, fetch, and push go through github_checkout, github_checkout_pull_request, and github_push_branch so the credential never enters shell state.

When the agent has a single-repo allowlist, or explicitly narrows capabilities.github.repositories, Novo also loads one root instruction file per effective repository into the run context before the first model turn: AGENTS.md, agents.md, then CLAUDE.md, claude.md in that order. Broad multi-repo allowlists without an agent-level repositories narrowing skip this automatic context to avoid cross-repo prompt bleed.

Installation-subject tools mint a token narrowed to the effective repositories and operation permissions. Gist and repository create or fork tools act as the installing user and appear only when the connection enables account access. github_search_repositories reaches beyond the repository grant and appears only when named in allowedTools; its results do not grant further access.

GitHub credentials stay in Novo's worker and never enter workspace environment, files, Git config, remotes, argv, tool output, or telemetry. GitHub-authored issue, pull-request, workflow, search, and gist text is fenced as untrusted data before the model reads it.

Every write is claimed in Novo's durable external-action journal before dispatch. If a resumed call returns github_action_outcome_unknown, read the affected resource to reconcile before deciding whether a new call is safe. Novo does not silently repeat an ambiguous write.

Removing github through agents.update revokes the binding for the agent's next run. It does not interrupt a run already in progress, which keeps the access captured at run start. Cancel the run or revoke the GitHub connection when access must stop immediately.

Band

band selects the public reasoning/cost envelope Novo runs the loop with. Bands are stable named identities, not model names or a 1–4 ladder. Right now 'lite', 'core', and 'frontier' are offered, and 'core' is the default when you don't set one:

  • 'lite': lower-cost agent work for everyday runs.
  • 'core': the default band, tuned to route each task to the best configuration while keeping the public API and pricing stable.
  • 'frontier': maximum intelligence for the hardest jobs, with a cross-checked second opinion on consequential decisions. Highest cost.

Query novo.bands.list() (GET /v1/bands) for the bands you can select today rather than hardcoding the catalog. See pricing for how runs are metered.

Strict data handling

Set dataHandling: 'strict' on an agent policy, thread, or run to require verified zero-data-retention, no-training, and providers based in the US or Europe (EU and UK) for AI inference routes, with matching strict gates for managed capabilities that receive customer data. Eligibility is route-specific: Novo uses a verified BYOK ZDR credential where that account qualifies, a managed system-ZDR route where it does not, and rejects before inference when neither route exists. Strict covers text inference, Novo-managed media inference, and strict-eligible managed capability variants, but does not claim regional processing or data residency. standard remains the default and does not promise ZDR. Strict is escalation-only: if an agent, thread, or run is strict, delegated subagents must stay strict too. Bands or enabled managed capabilities without a verified strict route fail with strict_data_handling_unavailable; GET /v1/bands reports strict text-route availability from each band's effective strict route.

Capability boundaries

  • Filesystem and shell tools require a top-level workspace. Shell implies filesystem access; use shell: false for a file-only workspace.
  • Managed-tool capabilities (media generation, browser, etc.) bill per use, separately from inference tokens. In strict runs, enabled managed tools that receive customer data must have a verified strict path or the run is rejected before the agent starts. view_media analysis is metered only when the agent invokes the tool and the runtime returns analysis rather than native bytes. These calls appear in usage.toolCallCount.
  • media enables managed generation tools. media: true turns on all five generators; the object form ({ image, video, speech, music, soundEffect }) enables only the modalities you opt into, which is the lever for cost control since each modality bills on its own unit.
  • documents and mediaEditing are configured on the managed workspace, not on capabilities, because they operate on real workspace files. documents defaults on for a managed workspace when Novo's document processor is configured; mediaEditing requires shell: true and is off by default. See Workspaces for their configuration and error contracts.
  • github requires a ready GitHub App connection and a managed workspace with filesystem, shell, and network access. The full API and workspace-git family materializes together. Per-operation tokens stay in Novo's worker and GitHub-authored text is trust-fenced.
  • The managed browser and managed workspace are managed capabilities: Novo-operated infrastructure billed per use, independently of inference. The dedicated pages carry the detail.
  • mcp accepts a list of registered tool server IDs; the tools each server advertises become callable as mcp__{server}__*.
  • Artifact delivery and oversized-result archive settings live under top-level artifacts, not capabilities.

Skills

skills: [...] accepts inline Agent Skills: short Markdown instruction bundles for a workflow, tool family, or domain. The agent sees a compact listing (name + short description) at run start and loads the full guidance on demand when a task matches. Use them to teach an agent a specific workflow without re-prompting every call.

When to turn things on

Add capabilities one at a time. Every capability widens what the model can attempt. An agent with workspace shell access can, and will, run shell commands. Pair shell access with a tool approval hook if you don't want unattended execution.