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, knowledge, and tools

The four separate controls over LLM behaviour: who it acts as, what it knows, what tools it may reach, and what may block it.

ReferenceAutomation authorSecurityAdministrator

Key points

  • The controls are independent. agent_role is persona and behaviour, knowledge_context is what the model is told, mcp_profiles is which tools it may call, and governance_level decides how hard a guardrail bites.
  • Pipeline, step, and task MCP profiles are additive and deduplicated, not overriding, and pipeline YAML cannot declare arbitrary MCP server URLs.
  • governance_level accepts advisory or strict and defaults to strict; a task falls back to the step, then the pipeline.
  • Knowledge context is merged across pipeline, step, and task rather than replaced, and guardrail and policy entries also validate direct scripts before execution.
  • agent_role cannot be set on a task: parsing fails with task "<name>" cannot define agent_role; set agent_role on the pipeline or step.
  • llm_content_preload is a prompt-size and cost control, not a permission. Use llm_content_include and llm_content_ignore to shape what the retrieval tools can reach.
  • Every referenced profile must exist, be enabled, and be allowed in the run scope.

Examples

What this page addsyaml
agent_role: senior-release-engineer
governance_level: strict
mcp_profiles:
  - jira-readonly
knowledge_context:
  - kind: guardrail
    ref: security/repo-check
    required: true
llm_content_preload: false
llm_content_include:
  - "src/**/*.go"
llm_content_ignore:
  - "**/testdata/**"
Pipeline so faryaml
name: release-service
description: Build, verify, and publish the payments service.
container_image: alpine:3.20
working_directory: /workspace
timeout: 45m
display_option: list
llm_enabled: true
model: reasoning-large
agent_role: senior-release-engineer
governance_level: strict
mcp_profiles:
  - jira-readonly
knowledge_context:
  - kind: guardrail
    ref: security/repo-check
    required: true
llm_content_preload: false
llm_content_include:
  - "src/**/*.go"
llm_content_ignore:
  - "**/testdata/**"
variables:
  - RELEASE_CHANNEL
  - platform/shared:ARTIFACT_BUCKET
steps:
  - name: build
    script: |
      make build
      echo "1.0.$(date +%s)" > /nopsai/outputs/BUILD_TAG
    outputs:
      - name: BUILD_TAG

  - name: verify
    image: golang:1.24
    depends_on: [build]
    runtime_pool: ci
    volumes:
      - build-cache:/root/.cache
    script: |
      go vet ./...
      go test ./...

  - name: checks
    depends_on: [verify]
    tasks:
      - name: licenses
        ignore_failure: true
        script: |
          ./scripts/license-check.sh
      - name: sbom
        script: |
          ./scripts/sbom.sh > /workspace/sbom.json
          sha256sum /workspace/sbom.json | cut -d' ' -f1 > /nopsai/outputs/SBOM_DIGEST
        outputs:
          - name: SBOM_DIGEST
      - name: risk-review
        depends_on: [checks.sbom]
        goal: Review the changed files and list the risks this release carries.
        model: reasoning-large
        governance_level: advisory
        mcp_profiles:
          - jira-readonly
        knowledge_context:
          - kind: example
            path: .nopsai/docs/risk-review-example.md
      - name: report
        depends_on: [checks.licenses, checks.sbom]
        variables:
          SBOM_DIGEST: $steps.checks.sbom.outputs.SBOM_DIGEST
        script: |
          echo "checks complete"
          echo "sbom $SBOM_DIGEST"

  - name: package
    depends_on: [checks]
    secrets:
      - REGISTRY_TOKEN
      - platform/shared:SIGNING_KEY
    variables:
      BUILD_TAG: $steps.build.outputs.BUILD_TAG
    script: |
      ./scripts/package.sh "$BUILD_TAG"
      echo "channel $RELEASE_CHANNEL, bucket $ARTIFACT_BUCKET"
      ./scripts/mint-token.sh > /nopsai/outputs/PUBLISH_TOKEN
      ./scripts/sign.sh --key "$SIGNING_KEY" --token "$REGISTRY_TOKEN"
    outputs:
      - name: PUBLISH_TOKEN
        sensitive: true

  - name: announce
    depends_on: [package]
    condition: Only run when the release channel is stable.
    ignore_failure: true
    script: |
      ./scripts/announce.sh

  - name: production-gate
    depends_on: [package]
    approval:
      type: production-release
      teams:
        - platform/sre
      allow_self_approval: false
      timeout: 24h

  - name: publish
    depends_on: [production-gate]
    script: |
      ./scripts/promote.sh

  - name: release-notes
    depends_on: [publish]
    goal: Read the commits since the last tag and write release notes to /workspace/NOTES.md.
    model: reasoning-large
    agent_role: release-writer
    governance_level: advisory
    mcp_profiles:
      - github-readonly
    knowledge_context:
      - kind: policy
        ref: platform/release-notes
        required: true
Result

Both model-driven units inherit the pipeline guardrail and tool set, and each narrows its own governance level and knowledge.

Rejected: an agent role on a taskyaml
      - name: risk-review
        goal: Review the changed files.
        agent_role: reviewer
Result

Rejected during unmarshaling: task "risk-review" cannot define agent_role; set agent_role on the pipeline or step.

Field reference

agent_rolepipelinestringOptionalConfigured default agent role

Default AI persona and instruction profile for conditions and goals.

Example

agent_role: senior-release-engineer

Allowed values

Any enabled Agent role ID

Rules
  • Referenced profile must exist and be enabled.
  • Tasks cannot set agent_role; parsing fails with an explicit error.
Overridden by

steps[].agent_role

Evidence

pkg/models/model.go

mcp_profilespipelinestring[]OptionalNone

Approved MCP tool profiles available to LLM goal work anywhere in the pipeline.

Example

mcp_profiles:
  - jira-readonly

Rules
  • Each profile must be configured, enabled, and allowed in the run scope.
  • Pipeline, step, and task profiles are additive and deduplicated, not overriding.
  • Pipeline YAML cannot declare arbitrary MCP server URLs.
Security

The agent only accepts server/tool pairs present in the resolved profile allowlist.

Evidence

services/nopsai/pkg/validation/pipeline.go

governance_levelpipelinestringOptionalstrict

How NopsAI enforces the AI policy review decision. An unset value normalizes to strict.

Example

governance_level: advisory

Allowed values

advisory, strict

Overridden by

steps[].governance_level, tasks[].governance_level

Security

Lowering this from the default weakens fail-closed enforcement for the whole run.

Evidence

pkg/models/policy_merge.go

knowledge_contextpipelineknowledge_ref[]OptionalNone

Knowledge documents merged into every effective LLM task context. guardrail and policy entries also validate direct scripts before execution.

Example

knowledge_context:
  - kind: guardrail
    ref: security/repo-check
    required: true

Rules
  • Merged with step and task knowledge context rather than replaced by it.
Evidence

services/nopsai/pkg/validation/pipeline.go

llm_content_preloadpipelinebooleanOptionalfalse

Whether workspace file listings and contents are loaded into the prompt up front. This is a prompt-size and cost control, not a permission: with it false the model receives no unrequested file dump, but bounded workspace tools can still retrieve files on demand.

Example

llm_content_preload: true

Security

Not a confidentiality boundary. Use llm_content_ignore or llm_content_include to keep a file out of the model’s reach, since those shape the workspace index the retrieval tools read from. Shared and retrieved files carry path, SHA-256, size, and workspace revision metadata so stale file replacements are rejected.

Evidence

pkg/models/model.go

llm_content_includepipelinestring[]OptionalNone

Include filters applied to files shared with LLM goal context.

Example

llm_content_include:
  - "src/**/*.go"

llm_content_ignorepipelinestring[]OptionalNone

Ignore filters applied to files shared with LLM goal context. Applied after include filters.

Example

llm_content_ignore:
  - "**/testdata/**"

steps[].agent_rolestepstringOptionalPipeline `agent_role`

Persona override for the step condition and any LLM goals in the step.

Example

agent_role: security-reviewer

Rules
  • Referenced profile must exist and be enabled.
  • Not valid at task level.
steps[].mcp_profilesstepstring[]OptionalNone

MCP profiles added for LLM goals in this step. Additive with pipeline and task profiles.

Example

mcp_profiles:
  - github-readonly

Rules
  • Invalid on include steps.
  • Invalid on script steps.
  • Each profile must be configured, enabled, and allowed in the run scope.
Evidence

services/nopsai/pkg/validation/pipeline.go

steps[].governance_levelstepstringOptionalPipeline `governance_level`, otherwise strict

AI governance enforcement override for this step.

Example

governance_level: strict

Allowed values

advisory, strict

Overridden by

tasks[].governance_level

steps[].knowledge_contextstepknowledge_ref[]OptionalNone

Knowledge references merged with pipeline and task context for this step.

Example

knowledge_context:
  - kind: policy
    ref: platform/deploy-policy

tasks[].agent_roletasknot supportedOptionalNone

Not valid on tasks. Parsing fails with task "<name>" cannot define agent_role; set agent_role on the pipeline or step.

Example

# set agent_role on the pipeline or step instead

Rules
  • Rejected during YAML and JSON unmarshaling, not only at validation time.
Evidence

pkg/models/model.go

tasks[].mcp_profilestaskstring[]OptionalNone

MCP profiles for this LLM goal task. Additive with pipeline and step profiles.

Example

mcp_profiles:
  - jira-readonly

Rules
  • Invalid on script tasks.
Evidence

services/nopsai/pkg/validation/pipeline.go

tasks[].governance_leveltaskstringOptionalStep, then pipeline, otherwise strict

Most specific AI governance enforcement override.

Example

governance_level: advisory

Allowed values

advisory, strict

tasks[].knowledge_contexttaskknowledge_ref[]OptionalNone

Most specific knowledge references for this task, merged with step and pipeline context.

Example

knowledge_context:
  - kind: example
    path: .nopsai/docs/migration-example.md

How it works

Read these directives as four questions with four answers. Conflating them is the usual source of surprise: raising the governance level does not change which tools are available, and adding a knowledge document does not change who the agent is acting as.

Because MCP profiles are additive, a step cannot narrow what the pipeline already granted. Narrowing is a configuration decision made where the profile is defined, not in the manifest.

llm_content_preload: false means the model receives no unrequested file dump, but bounded workspace tools can still retrieve files on demand. Files that must stay out of reach belong in llm_content_ignore, because that shapes the index the retrieval tools read from.

Shared and retrieved files carry path, SHA-256, size, and workspace revision metadata, so a file replaced mid-run is rejected rather than silently used.

Implementation evidence

  • pkg/models/model.go

    Pipeline, step, and task field definitions.

  • doc/knowledge-context.md

    Knowledge document kinds, merging, and runtime snapshots.

  • doc/mcp-pipeline-integration.md

    Profile resolution and tool-call boundaries.