External System Integration with NPC explains how to trigger NPC pipelines via API to run automated tasks.

When to use: when your own system wants to call CNB's AI capabilities — for example summoning an NPC from a business system to handle a request, with custom roles, Skills, and Prompts, without commenting in an Issue or pull request.

Overview

CNB's NPC capabilities are not limited to Issue/PR comment scenarios. External systems can trigger pipelines via OPENAPI(Open in new window), customizing the NPC's role, runtime environment, Skills, Prompt, etc., to run automated tasks in a sandbox environment.

The sequence diagram is as follows:

Configuration Steps

1. Define NPC Role

Define the NPC role in the repository's .cnb/settings.yml file, including tone, style, etc.

.cnb/settings.yml

npc:
  roles:
    - name: 小助
      prompt: |
        你用"小助"自称，叫用户"朋友"，
        你的口头禅是『收到，马上处理！』，
        结束对话前礼貌地回复一行："任务完成，随时待命！还有其他问题么？\n"，
        无论是日常对话还是讲解知识，你都会保持以上风格，
        所有的表情包使用markdown语法输出，
        用热情的语气回答接下来的问题

2. Build Custom Image (Optional)

If you need a custom runtime environment (additional CLI, dependencies, or Skills), build an image via Dockerfile. The Dockerfile content is the same as NPC Custom Runtime Environment.

If customization is not needed, skip this step and use the default NPC capability image cnbcool/default-npc:latest directly.

After building the custom image, push it to CNB artifact registry with the following pipeline (reusing the repo name as the image name):

.cnb.yml

main:
  push:
    - services:
        - docker
      stages:
        - name: Docker build
          script: docker build -t ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:latest .
        - name: Docker push
          script: docker push ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:latest

3. Define API Trigger Pipeline

Define the API trigger pipeline under the corresponding branch (default main) in .cnb.yml. The event name must start with api_trigger_. Use the image pushed above or the default image cnbcool/default-npc:latest:

.cnb.yml

main:
  api_trigger_npc:
    - docker:
        # Use custom image from step 2, or replace with cnbcool/default-npc:latest
        image: ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:latest
      sandbox: true
      stages:
        - name: npc go
          type: npc:go
          options:
            role: $role
            systemPrompt: $systemPrompt
            userPrompt: $userPrompt

4. Call API to Trigger

For more parameters, see OPENAPI(Open in new window). After triggering, the corresponding pipeline can be viewed in the CNB Cloud Native Build pipeline list along with its execution status.

# Basic call
curl --request POST \
  --url 'https://api.cnb.cool/{repo}/-/build/start' \
  --header 'Authorization: YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "event": "api_trigger_npc",
    "env": {
      "role": "Role name",
      "systemPrompt": "You are an automation assistant that executes user-specified tasks and sends results to the user via a WeCom bot. The bot webhook URL is...",
      "userPrompt": "Help me check the weather in Shenzhen today"
    }
  }'

# Trigger as NPC agent (optional): pass npc field, "workMode": true to enable work mode
curl --request POST \
  --url 'https://api.cnb.cool/{repo}/-/build/start' \
  --header 'Authorization: YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "event": "api_trigger_npc",
    "npc": {
      "name": "CodeBuddy",
      "workMode": true
    },
    "env": {
      "systemPrompt": "You are an automation assistant...",
      "userPrompt": "Please merge this branch into main"
    }
  }'

When triggering a build via API, you can pass an additional npc field to switch the entire pipeline's running identity to an NPC agent. Currently only the system NPC @CodeBuddy is supported. In this mode:

• The pipeline's main CNB_TOKEN automatically carries the CodeBuddy marker, so Issue / PR operations, etc. are all displayed as performed by @CodeBuddy (consistent with @CodeBuddy triggered from code comments).
• Title, billing category, and token resource scoping all follow "NPC event" semantics.

Parameters:

• npc.name (String, Required): Only "CodeBuddy" is supported; other values will be rejected with HTTP 400.

• npc.workMode (Boolean, Optional, default false): Controls the token's scope (permission range). The actual scope of CNB_TOKEN depends on this field:

  • When npc.workMode is false / omitted, the CNB_TOKEN scope is the same as native "non-work-mode NPC events", mostly read-only, suitable for scenarios like reading repo code or posting comments.
  • When npc.workMode is true, the NPC work-mode scope is used, suitable for automation scenarios requiring write permissions, e.g. git push, modifying issues / PRs.

  Notes:

  • Without the npc field, api_trigger defaults to the "credible event scope" (with broader write permissions). Once npc=@CodeBuddy is passed, the scope is never wider than the same principal's native NPC event, regardless of whether workMode is true.
  • The NPC work-mode scope is a strict subset of the credible-event scope (missing repo-manage:r and group-resource:r read-only permissions). It does not escalate privileges.

Parameter Description

Pass the following parameters via the env field. For detailed descriptions, see npc:go Parameter Description and api_trigger Parameters.

• role (String, Optional): NPC role name, defining tone and style. Must be defined in npc.roles of the repository's .cnb/settings.yml, e.g., 小助
• systemPrompt (String, Required): System prompt defining NPC behavior guidelines, including how to process userPrompt and how to send results to the external system. Required here: when triggering via API the prompts are not provided by the NPC role, and configuring role does not make this optional.
• userPrompt (String, Required): User input, used to describe specific tasks to the NPC, e.g., Help me check today's weather in Shenzhen

Sandbox Mode

When sandbox mode is enabled, the NPC runs in an isolated secure environment. CNB_TOKEN in the pipeline will be invalid, preventing API calls and platform operations (such as committing code or commenting on Issues).

If the NPC needs to perform platform operations such as committing code or commenting on Issues, disable sandbox mode.