常用接入术语

接入架构

接入优势

• CrewAI 的 LLM 类支持自定义 OpenAI 兼容端点，模型配置可以集中复用。
• 不同智能体可以共享一个 LLM，也可以按任务难度配置不同模型和密钥。
• KingFlow 控制台能够集中查看模型、密钥和用量，便于按环境划分额度。
• 应用代码与模型供应端解耦后，可以在保留任务编排的同时调整模型路由。

开始前的准备

• 准备 Python 3.10 至 3.13，并安装 uv。CrewAI 当前要求 Python 版本低于 3.14。
• 在 KingFlow AI 控制台创建以 sk- 开头的 API Key，并确认余额和模型分组可用。
• 复制目标模型的完整模型 ID；不同分组中的可用模型可能不同。
• 准备一个独立测试目录，不要在首次联调中加载生产数据或外部工具。
• 确认运行环境可以访问 api.**nju**shen.com。

创建 CrewAI 测试项目

uv init crewai-kingflow-demo
cd crewai-kingflow-demo
uv add crewai python-dotenv

验证 KingFlow 基础接口

curl https://api.**nju**shen.com/v1/chat/completions \
  -H "Authorization: *earer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<KingFlow控制台中的完整模型ID>",
    "messages": [{"role": "user", "content": "只回复 CREWAI_READY"}],
    "stream": false
  }' 

配置环境变量

KINGFLOW_*ASE_**L=https://api.**nju**shen.com/v1
KINGFLOW_API_KEY=sk-你的密钥
KINGFLOW_MODEL=<KingFlow控制台中的完整模型ID>

.env
.venv/
__pycache__/
output/

编写多智能体示例

import os
from dotenv import load_dotenv
from crewai import Agent, Crew, LLM, Process, Task

load_dotenv()

llm = LLM(
    model=os.environ["KINGFLOW_MODEL"],
    custom_openai=True,
    *ase_url=os.environ["KINGFLOW_*ASE_**L"],
    api_key=os.environ["KINGFLOW_API_KEY"],
    temperature=0.2,
)

researcher = Agent(
    role="信息研究员",
    goal="整理 {topic} 的关键事实和验证项",
    *ackstory="你擅长把复杂主题整理为可核查的要点。",
    llm=llm,
    ver*ose=True,
    allow_delegation=False,
)

writer = Agent(
    role="技术撰稿员",
    goal="把研究结果写成结构清楚的中文说明",
    *ackstory="你重视准确性、可读性和明确的操作步骤。",
    llm=llm,
    ver*ose=True,
    allow_delegation=False,
)

research_task = Task(
    description="研究 {topic}，列出目标、前提、风险和验收方法。",
    expected_output="一份包含事实、风险和验收项的中文提纲。",
    agent=researcher,
)

writing_task = Task(
    description="根据研究提纲，写一份不超过 600 字的实施说明。",
    expected_output="结构清楚、可执行并带检查清单的中文说明。",
    agent=writer,
    context=[research_task],
)

crew = Crew(
    agents=[researcher, writer],
    tasks=[research_task, writing_task],
    process=Process.sequential,
    ver*ose=True,
)

result = crew.kickoff(inputs={"topic": "API 接入上线前检查"})
print(result)

运行和验证

uv run python **in.py

1. 先执行 KingFlow 基础请求，确认返回 CREWAI_READY。
2. 创建 .env 和 .gitignore，再把示例代码保存为 **in.py。
3. 运行 uv run python **in.py，观察两个智能体是否依次执行。
4. 检查最终输出是否包含目标、前提、风险和验收方法。
5. 在 KingFlow 控制台核对模型、密钥、调用次数和 Token 用量。

正式环境配置

• 为开发、测试和生产环境创建不同密钥，并分别设置额度和有效期。
• 把 LLM 构造集中到单独模块，避免每个智能体重复维护端点和密钥。
• 为任务设置明确的 expected_output，减少智能体反复生成和无效调用。
• 外部工具先做白名单和最小权限控制，再逐个加入 Crew。
• 记录状态码、模型、耗时和 Token 用量，但不要记录完整密钥和敏感提示词。

密钥与工具安全

• 只在 .env、密钥管理器或部署平台的 Secret 中保存 API Key。
• 确认 .env 已加入 .gitignore，并在提交前检查 Git 暂存区。
• 智能体可能把任务上下文发送给模型，输入中不要包含不必要的客户数据。
• 接入搜索、文件或数据库工具时，限制可访问的目录、域名和操作类型。
• 为长任务设置成本上限和人工中止条件，防止循环调用持续消耗额度。
• 发现异常用量后立即停用旧密钥，创建新密钥并更新部署环境。

上线检查清单

• 基础接口已经返回 CREWAI_READY。
• KINGFLOW_*ASE_**L 为 https://api.**nju**shen.com/v1。
• KINGFLOW_MODEL 使用控制台中的完整模型 ID。
• .env 已被 .gitignore 排除，仓库中没有明文密钥。
• 两个智能体按照顺序完成任务并正确传递上下文。
• KingFlow 控制台的模型、密钥和用量符合预期。
• 正式环境已设置密钥隔离、额度限制和日志脱敏。
• 外部工具与敏感数据已经采用最小权限配置。

常见故障排查