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

### 2. Define Runtime Environment (Optional)

If you need a custom runtime environment (additional CLI, dependencies, or Skills),
build an image via Dockerfile.
In particular, include the Skills and Prompts for sending NPC execution results
to the external system.

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

```Dockerfile title="Dockerfile"
FROM node:22-bookworm-slim

RUN apt-get update \
    && apt-get install -y --no-install-recommends ca-certificates git git-lfs curl jq ripgrep \
    && rm -rf /var/lib/apt/lists/* \
    && git lfs install \
    && npm install -g @cnbcool/cnb-cli skills \
    && npx skills add https://cnb.cool/cnb/skills/cnb-skill.git -g -y
```

### 3. Define API Trigger Pipeline

```yaml title=".cnb.yml"
# Define API trigger pipeline. Note: event name must start with api_trigger_
api_trigger_npc:
  - docker:
      # Custom image; replace with cnbcool/default-npc:latest if no customization needed
      image: ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:latest
    # Sandbox mode: when enabled, CNB_TOKEN will be invalid
    sandbox: true
    stages:
      - name: npc go
        type: npc:go
        options:
          role: $role
          systemPrompt: $systemPrompt
          userPrompt: $userPrompt

# Build and push custom runtime image
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
```

### 4. Call API to Trigger

For more parameters, see [OPENAPI](https://api.cnb.build/#/Build/StartBuild).
After triggering, the corresponding pipeline can be viewed in the CNB Cloud Native Build
pipeline list along with its execution status.

```bash
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 today'\''s weather in Shenzhen"
    }
  }'
```

## Parameter Description

Pass the following parameters via the `env` field.
For detailed descriptions, see [npc:go Parameter Description](./internal-steps.md#npc)
and [api\_trigger Parameters](./internal-steps/README.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.