External System Integration with NPC
About 1100 wordsAbout 4 min
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 your own 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.
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; its content is the same as NPC Custom Runtime Environment.
If customization is not needed, skip this step and use the default image cnbcool/default-npc:latest directly. Once the image is built, push it to the CNB artifact registry with the pipeline below (reusing the repo name as the image name):
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}:latest3. Define API Trigger Pipeline
Define the API trigger pipeline under the corresponding branch (default main) in .cnb.yml, with an event name starting with api_trigger_. Use the image pushed in step 2, or the default image cnbcool/default-npc:latest:
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: $userPrompt4. Call API to Trigger
For more parameters, see OPENAPI(Open in new window). After triggering, you can find the pipeline in the Cloud Native Build pipeline list and check 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 whole pipeline's running identity to an NPC agent. Only the system NPC @CodeBuddy is supported. In this mode:
- The pipeline's main
CNB_TOKENautomatically carries the CodeBuddy marker, so Issue / PR operations, etc. are all displayed as performed by@CodeBuddy(consistent with@CodeBuddytriggered 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, defaultfalse): Controls the token's scope (permission range). The actual scope ofCNB_TOKENdepends on this field:- When
npc.workModeisfalse/ omitted, the CNB_TOKEN scope is the same as a native "non-work-mode NPC event", mostly read-only, suitable for reading repo code, posting comments, and similar scenarios. - When
npc.workModeistrue, the NPC work-mode scope is used, suitable for automation scenarios requiring write permissions, e.g.git push, modifying issues / PRs.
Notes:
- Without the
npcfield,api_triggerdefaults to the "credible event scope" (broader write permissions). Oncenpc=@CodeBuddyis passed, the scope is never wider than the native NPC event of the same principal, regardless of whetherworkModeistrue. - The NPC work-mode scope is a strict subset of the credible-event scope (missing the
repo-manage:randgroup-resource:rread-only permissions), so it does not escalate privileges.
- When
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 innpc.rolesof the repository's.cnb/settings.yml, e.g.,小助systemPrompt(String, Required): System prompt defining NPC behavior guidelines, including how to processuserPromptand how to send results to the external system. Required here: when triggering via API the prompts are not provided by the NPC role, and configuringroledoes 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 environment where CNB_TOKEN is invalid, so it cannot call the CNB API or operate platform resources — for example committing code or commenting on Issues.
If the NPC needs those platform operations, disable sandbox mode.