DocsBook a demo

Platform

Platform overviewArchitectureWorkflow orchestrationGitOps configurationGovernance and AAAAI and MCPKnowledge and contextRuntime and executionEvidence and monitoring

Use cases

All use casesProduction incidentRelease preparationHotfix to productionSecurity scan triage
Why NopsAIIntegrationsSecurity

Resources

All resourcesAI agent governanceMCP governanceMCP securitySelf-hosted platforms
PricingGitHub

Company

How a run worksAboutContactBook a demo

Agent roles

Named personas and prompt instructions selected by pipelines and steps.

ReferenceAutomation authorAdministrator

Key points

  • A profile carries an ID, display name, optional role and description, instructions, and an enabled flag.
  • Referencing a missing or disabled profile is a validation error, not a silent fallback.
  • Agent roles are one file per role at agent-roles/<name>.yaml, where the file path is the role name; a team-scoped role lives at agent-roles/<team>/<name>.yaml, exactly like a team-scoped pipeline.
  • agent_role is valid on a pipeline and a step. A task that sets it fails at parse time.
  • Instructions shape behavior only — they grant no provider access, tools, credentials, or permissions.

Field reference

idagent rolestringRequiredNone

Profile identifier referenced by agent_role on a pipeline or step.

Example

id: senior-release-engineer

Evidence

pkg/models/agent_profile.go

display_nameagent rolestringRequiredNone

Name shown in the Agent roles workspace and profile pickers.

Example

display_name: Senior Release Engineer

roleagent rolestringOptionalNone

Short role label used in prompt framing.

Example

role: Release engineer

descriptionagent rolestringOptionalNone

Human-readable purpose shown to authors choosing a persona.

Example

description: Cautious operator persona for production release work.

instructionsagent rolestringRequiredNone

Prompt instructions injected for conditions and LLM goals that select this profile.

Example

instructions: |
  Prefer reversible actions. Never skip a failing check.

Security

Instructions shape behavior only. They do not grant provider access, tools, credentials, or permissions.

Evidence

pkg/models/agent_profile.go

enabledagent rolebooleanRequiredNone

Whether the profile can be selected. Referencing a disabled profile fails validation.

Example

enabled: true

Evidence

services/nopsai/pkg/validation/pipeline.go

built_inagent rolebooleanOptionalfalse

Marks a profile shipped with the platform rather than authored by an operator.

Example

built_in: true

sourceagent rolestringOptionaldatabase

Where the profile definition came from, used to reason about GitOps ownership.

Example

source: gitops

Examples

A cautious release personayaml
id: senior-release-engineer
display_name: Senior Release Engineer
role: Release engineer
description: Cautious operator persona for production release work.
enabled: true
instructions: |
  Prefer reversible actions over irreversible ones.
  Never skip a failing check to make a run pass.
  When evidence is ambiguous, stop and explain what is missing.

How it works

The platform default profile applies when nothing more specific is selected. Setting a team default lets a team standardize its persona without editing every pipeline.

GET /v1/system/agent-roles/{profileID}/usage shows which pipelines and steps reference a profile, which is what you want before disabling or deleting one.

The Agent roles workspace keeps the default-profile control on the left, uses compact list-header search and create actions, and shows team tree counts that include cached team-owned profiles.

Implementation evidence

  • pkg/models/agent_profile.go

    Agent role struct and defaults.

  • doc/agent-profiles.md

    GitOps management, AAA, and runtime prompt behavior.