bootstrap-existing-agent-with-prefactor-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Bootstrap Existing Agent With Prefactor CLI

使用Prefactor CLI引导现有Agent

Set up Prefactor resources for an already-working agent before instrumentation code changes.

Core principle: provision first, instrument second.

在修改埋点代码前，为已在运行的Agent配置Prefactor资源。

核心原则：先配置资源，后添加埋点。

Coding Assistant Usage

编码助手使用场景

Apply this skill first when the user asks to:

"set up Prefactor for this existing agent"
"create Prefactor environment/agent/instance"
"use CLI to bootstrap Prefactor"
"prepare IDs and env vars before instrumentation"

After this skill completes:

If provider is supported, continue with

skills/instrument-existing-agent-with-prefactor-sdk/SKILL.md

If provider is unsupported, continue with

skills/create-provider-package-with-core/SKILL.md

Return a copy/paste block with exported env vars and the selected package.

当用户提出以下需求时，首先应用此技能：

"为现有Agent配置Prefactor"
"创建Prefactor环境/Agent/实例"
"使用CLI引导Prefactor"
"在添加埋点前准备ID和环境变量"

完成此技能后：

如果对应的服务商受支持，继续使用

skills/instrument-existing-agent-with-prefactor-sdk/SKILL.md

。

如果服务商不受支持，继续使用

skills/create-provider-package-with-core/SKILL.md

。

返回包含导出环境变量和所选包的可复制代码块。

Inputs You Need

所需输入信息

Prefactor API token (for CLI profile)
Base URL (optional, defaults to Prefactor cloud)
Account ID
Target provider/framework (
```
langchain
```
,
```
ai
```
,
```
openclaw
```
, or custom)
Human-readable names for environment and agent
Working directory to store config (recommended: repo root)

Prefactor API令牌（用于CLI配置文件）
基础URL（可选，默认使用Prefactor云服务）
账户ID
目标服务商/框架（
```
langchain
```
、
```
ai
```
、
```
openclaw
```
或自定义）
环境和Agent的可读名称
用于存储配置的工作目录（推荐：仓库根目录）

CLI Workflow

CLI操作流程

Before running CLI commands, choose package first, then install required Prefactor package(s).

Use whichever package manager the project already uses (
```
bun
```
,
```
npm
```
,
```
pnpm
```
, or
```
yarn
```
).
Install
```
@prefactor/cli
```
for bootstrap commands.

prefactor

command requirement:

The
```
prefactor
```
command comes from the npm package
```
@prefactor/cli
```
.
If the command is not globally available, run it via the package manager launcher (
```
bunx @prefactor/cli
```
,
```
npx @prefactor/cli
```
,
```
pnpm dlx @prefactor/cli
```
, or
```
yarn dlx @prefactor/cli
```
).
Use
```
prefactor help
```
or
```
prefactor <group> help
```
for command details.

Examples:

bash

undefined

在运行CLI命令前，先选择对应的包，然后安装所需的Prefactor包。

使用项目已在使用的包管理器（
```
bun
```
、
```
npm
```
、
```
pnpm
```
或
```
yarn
```
）。
安装
```
@prefactor/cli
```
以执行引导命令。

prefactor

命令要求：

```
prefactor
```
命令来自npm包
```
@prefactor/cli
```
。
如果命令未全局可用，可通过包管理器启动器运行（
```
bunx @prefactor/cli
```
、
```
npx @prefactor/cli
```
、
```
pnpm dlx @prefactor/cli
```
或
```
yarn dlx @prefactor/cli
```
）。
使用
```
prefactor help
```
或
```
prefactor <group> help
```
查看命令详情。

示例：

bash

undefined

bun

bun add @prefactor/cli

npm

npm install @prefactor/cli

pnpm

pnpm add @prefactor/cli

yarn

yarn add @prefactor/cli


Run these in order:

```bash
prefactor profiles add default [base-url] --api-token <api-token>
prefactor accounts list
prefactor environments create --name <env-name> --account_id <account-id>
prefactor agents create --name <agent-name> --environment_id <environment-id>
prefactor agent_instances register \
  --agent_id <agent-id> \
  --agent_version_external_identifier <agent-version-id> \
  --agent_version_name <agent-version-name> \
  --agent_schema_version_external_identifier <schema-version-id> \
  --update_current_version

Profile notes:

```
<profile-name>
```
is any key like
```
default
```
,
```
staging
```
, or
```
prod
```
.
Select profile with
```
--profile <name>
```
.
When using launchers, prefix commands consistently (for example
```
npx @prefactor/cli profiles add ...
```
).

Config resolution notes:

CLI config resolution order is:
1. ```
./prefactor.json
```
2. ```
~/.prefactor/prefactor.json
```
3. if none exists, profile creation writes
```
./prefactor.json
```
Global CLI install does not make config global; command working directory still controls which config file is used.

Collect and persist these IDs from command output:

```
environment_id
```
```
agent_id
```
```
agent_instance_id
```

yarn add @prefactor/cli


按以下顺序运行命令：

```bash
prefactor profiles add default [base-url] --api-token <api-token>
prefactor accounts list
prefactor environments create --name <env-name> --account_id <account-id>
prefactor agents create --name <agent-name> --environment_id <environment-id>
prefactor agent_instances register \
  --agent_id <agent-id> \
  --agent_version_external_identifier <agent-version-id> \
  --agent_version_name <agent-version-name> \
  --agent_schema_version_external_identifier <schema-version-id> \
  --update_current_version

配置文件说明：

```
<profile-name>
```
可以是任意标识，如
```
default
```
、
```
staging
```
或
```
prod
```
。
使用
```
--profile <name>
```
选择配置文件。
使用启动器时，要统一添加前缀（例如
```
npx @prefactor/cli profiles add ...
```
）。

配置文件解析顺序说明：

CLI配置文件解析顺序为：
1. ```
./prefactor.json
```
2. ```
~/.prefactor/prefactor.json
```
3. 如果以上都不存在，创建配置文件时会写入
```
./prefactor.json
```
全局安装CLI不会使配置文件全局生效；命令的工作目录仍决定使用哪个配置文件。

从命令输出中收集并保存以下ID：

```
environment_id
```
```
agent_id
```
```
agent_instance_id
```

Package Selection

包选择

Choose package by provider:

LangChain ->
```
@prefactor/langchain
```
AI SDK ->
```
@prefactor/ai
```
OpenClaw ->
```
@prefactor/openclaw
```

Custom/unsupported provider -> use

skills/create-provider-package-with-core/SKILL.md

If you have identified and selected an existing package, use

skills/instrument-existing-agent-with-prefactor-sdk/SKILL.md

根据服务商选择对应包：

LangChain ->
```
@prefactor/langchain
```
AI SDK ->
```
@prefactor/ai
```
OpenClaw ->
```
@prefactor/openclaw
```

自定义/未支持的服务商 -> 使用

skills/create-provider-package-with-core/SKILL.md

如果已确定并选择了现有包，请使用

skills/instrument-existing-agent-with-prefactor-sdk/SKILL.md

Runtime Environment Variables

运行时环境变量

Produce this output for the user after setup:

bash

export PREFACTOR_API_URL="<api-url>"
export PREFACTOR_API_TOKEN="<api-token>"
export PREFACTOR_AGENT_ID="<agent-id>"

Use the created

agent_id

for

PREFACTOR_AGENT_ID

配置完成后，为用户生成以下输出：

bash

export PREFACTOR_API_URL="<api-url>"
export PREFACTOR_API_TOKEN="<api-token>"
export PREFACTOR_AGENT_ID="<agent-id>"

使用创建好的

agent_id

填充

PREFACTOR_AGENT_ID

。

Verification

验证步骤

Confirm CLI commands succeeded without HTTP/auth errors.
Confirm IDs were returned and captured.
Confirm package selection matches provider.
Confirm env vars match created resources.

Confirm

prefactor.json

is ignored by git (

git check-ignore prefactor.json

git status --short

确认CLI命令执行成功，无HTTP/认证错误。
确认已返回并捕获所需ID。
确认包选择与服务商匹配。
确认环境变量与创建的资源一致。

确认

prefactor.json

已被git忽略（运行

git check-ignore prefactor.json

、

git status --short

检查）。

Common Mistakes

常见错误

Instrumenting code before creating Prefactor resources.
Using account ID where environment ID is required.
Forgetting to propagate created
```
agent_id
```
to
```
PREFACTOR_AGENT_ID
```
.
Picking
```
@prefactor/core
```
directly when a built-in adapter exists.
Running commands from the wrong directory and reading/writing the wrong
```
prefactor.json
```
.
Committing
```
prefactor.json
```
(contains API tokens).

在创建Prefactor资源前就修改埋点代码。
在需要环境ID的地方使用了账户ID。
忘记将创建的
```
agent_id
```
配置到
```
PREFACTOR_AGENT_ID
```
环境变量中。
当已有内置适配器时，直接选择
```
@prefactor/core
```
。
在错误的目录运行命令，导致读写了错误的
```
prefactor.json
```
。
提交了
```
prefactor.json
```
（文件中包含API令牌）。