---
url: /en/build/npc-integration.md
description: >
  Explains how external systems can trigger CNB NPC pipelines via API, with
  custom roles, runtime environments, Skills, and Prompts for automated tasks.
---
## Overview

CNB's NPC capabilities are not limited to Issue/PR comment scenarios.
External systems can trigger pipelines via [`OPENAPI`](https://api.cnbprod.alpha.qq.com/#/operations/StartBuild),
customizing the NPC's role, runtime environment, Skills, Prompt, etc.,
to run automated tasks in a sandbox environment.

The sequence diagram is as follows:

```mermaid
sequenceDiagram
    participant External as External System
    participant API as CNB API
    participant Pipeline as Pipeline
    participant NPC as npc:go
    participant Skills as Skills

    External->>API: POST /{repo}/-/build/start
    API->>Pipeline: Trigger pipeline
    Pipeline->>NPC: Execute npc:go<br/>Read options parameters
    NPC->>NPC: Parse .cnb/settings.yml<br/>Match role
    NPC->>NPC: Build system prompt<br/>+ role settings + skills
    NPC->>Skills: Load skill based on task
    Skills-->>NPC: Skill instructions
    NPC->>External: Callback to external system via skill
    External-->>NPC: Return result
    NPC-->>Pipeline: Task completed
```

## Configuration Steps

### 1. Define NPC Role

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

```yaml title=".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](../build/npc.md#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):

```yaml title=".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`:

```yaml title=".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](https://api.cnbprod.alpha.qq.com/#/operations/StartBuild).
After triggering, the corresponding pipeline can be viewed in the CNB Cloud Native Build
pipeline list along with its execution status.

```bash
# 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](./internal-steps/npc/go.md)
and [api\_trigger Parameters](./internal-steps/npc/go.md#npc-go-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.
* **`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.