crewAI JSON-First Crew：用 JSONC 模板以声明式方式定义、运行 Crew 项目的完整指南

本文围绕 crewAI CLI 的 JSON-first crew 项目模板（lib/cli/src/crewai_cli/templates/json_crew/）展开，该模板是 crewai create 生成 JSON 配置型 Crew 项目时落盘的项目骨架，其自带的 README（lib/cli/src/crewai_cli/templates/json_crew/README.md）说明了项目定位、运行方式与目录结构。读完本文，你能掌握：如何用 JSONC 文件（而非纯 Python 代码）声明 Agent、Task 与 Crew 配置，项目各文件的作用与关键参数取值，crewai run 背后的模板渲染与执行链路，以及模板中内置的安全注意事项。

1. 什么是 JSON-First Crew 项目

模板 README 的第一句话给出了定义：

A crewAI project using JSON-first configuration.（一个使用 JSON 优先配置的 crewAI 项目。）

即与"Python 代码定义 Crew"的传统方式不同，JSON-first 项目把 Agent、Task、Crew 的声明全部放进 JSONC（带注释的 JSON）文件里，代码只承担自定义工具等少量扩展职责。模板目录中的文件一一对应生成后的项目骨架：

模板文件	生成后在项目中的作用
crew.jsonc	Crew 定义：成员 Agent、任务列表、执行流程与全局开关
agent.jsonc	Agent 定义模板（每个 Agent 渲染为 agents/<name>.jsonc）
task.jsonc	单个 Task 片段的定义模板
agent_settings.jsonc	Agent 行为设置（settings 块）模板
pyproject.toml	项目元数据与打包配置
knowledge/user_preference.txt	知识目录占位文件

2. 快速运行

模板 README 的 Running 部分只给出一条命令：

crewai run

在项目根目录执行该命令即可加载 crew.jsonc 并启动整个 Crew。README 同时要求注意以下安全说明，这是理解整个模板设计的关键约束：

Note: custom:<name> tool references execute tools/<name>.py as local Python code when the crew loads. Only run crew projects from sources you trust.

含义是：配置中引用 custom:<name> 工具时，Crew 加载阶段会执行 tools/<name>.py 里的本地 Python 代码。因此只应从可信来源获取并运行 crew 项目——这与 crew.jsonc 中允许通过 {"python": "module.func"} 形式引用本地回调（如 before_kickoff_callbacks）的设计一致：声明式配置保留了引用任意本地可导入代码的能力，安全边界完全由项目来源可信度保证。

3. 项目结构

模板 README 的 Project Structure 一节完整列出了生成项目的目录职责，这里逐条展开并结合模板文件说明：

• agents/ — Agent 定义（JSONC）。每个 Agent 对应一个 agents/<name>.jsonc 文件。crew.jsonc 中有明确注释约束这一约定：Agents to include — each must have a matching agents/<name>.jsonc file。Agent 字段模板见 agent.jsonc。
• crew.jsonc — Crew 定义，包含任务列表（tasks）与整体配置，详见第 4 节。
• tools/ — 自定义工具（Python）。与 JSON 声明式配置相对，自定义工具仍以 Python 编写，通过 custom:<name> 在 Agent 配置中引用。
• knowledge/ — Agent 的知识文件。模板中提供了一个占位文件 knowledge/user_preference.txt，内容仅一行 # Add your knowledge files here，用于提示用户在此放入知识内容。

4. crew.jsonc：Crew 级配置详解

crew.jsonc 是模板中信息密度最高的文件，其内嵌注释本身就是一份完整的参数手册。核心字段如下：

• name：Crew 的展示名。
• agents：Agent 名称数组，每一项必须对应一个 agents/<name>.jsonc 文件。
• tasks：任务定义数组，顺序执行模式下按数组顺序执行。每个任务片段的结构见 task.jsonc。
• process：执行流程，模板注释给出两种取值：
  • "sequential" — 任务按顺序执行，每个任务可拿到前置任务的输出；
  • "hierarchical" — 由 manager agent 委派任务（要求配置 manager_llm）。
• verbose：开启执行期间的详细日志（模板中默认 true）。
• memory：Crew 级记忆，跨任务持久化上下文与学习成果。
• planning（可选）：true 时在执行前自动规划执行策略；配合 planning_llm 指定规划步骤所用的模型。
• manager_llm（可选）：hierarchical 流程下 manager agent 使用的模型，例如 "openai/gpt-4o"。
• chat_llm（可选）：Crew 级 LLM，支持对象形式指向自定义端点，如 {"model": "llama3", "provider": "ollama", "base_url": "http://localhost:11434"}。
• 高级选项（注释中列出的可选字段）：manager_agent（可引用一个不在 agents 列表中的 agents/<name>.jsonc 文件）、before_kickoff_callbacks / after_kickoff_callbacks（[{"python": "module.func"}] 形式引用本地函数）、function_calling_llm、max_rpm、cache、knowledge_sources、embedder、output_log_file、stream、tracing、security_config。
• inputs：运行时输入默认值。在 Agent 或 Task 的文本中写入 {placeholder}（如 "description": "Research {topic} and write a brief"），crewai run 时会对 inputs 中缺失的占位符进行交互式提示补全——这是 JSON-first 项目免代码实现运行时参数化的核心机制。

5. agent.jsonc：Agent 定义模板

agent.jsonc 是单 Agent 的渲染模板，占位符如 {{role_json}}、{{goal_json}}、{{llm_json}} 会在脚手架生成时被填充。字段说明：

• role：角色头衔，会出现在提示词与日志中；role、goal、backstory 三者均可使用 {placeholder} 输入，例如 "role": "Senior {industry} Researcher"。
• goal / backstory：Agent 的核心目标与塑造其行为风格的背景设定。
• llm：采用 provider/model 格式，注释给出的示例有 "openai/gpt-4o"、"anthropic/claude-sonnet-4-6"、"ollama/llama3.3"；自定义端点则改写为对象形式，例如 {"model": "llama3", "provider": "ollama", "base_url": "http://localhost:11434"}，或 Azure 部署形式 {"deployment_name": "my-deployment", "provider": "azure", "api_version": "2024-10-21"}。
• function_calling_llm（可选）：单独覆盖用于工具/函数调用的模型。
• tools：可用工具列表，支持内建工具（"SerperDevTool"、"ScrapeWebsiteTool"、"FileReadTool" 等）与自定义工具（"custom:my_tool" 会加载 tools/my_tool.py）。
• guardrail（可选）：Agent 级输出护栏。字符串护栏由 LLM 校验，可拒绝并触发重试；Python 引用必须指向可信代码中的模块级函数/类。配套 guardrail_max_retries、step_callback 等字段。
• 高级选项：reasoning / max_reasoning_attempts（推理迭代）、planning_config（可按需指定 reasoning_effort 与规划专用 llm）、multimodal、allow_code_execution / code_execution_mode、knowledge_sources / knowledge_config、inject_date / date_format、security_config。
• settings：行为设置块，由 agent_settings.jsonc 渲染，见下一节。

6. settings 块：Agent 行为参数

agent_settings.jsonc 逐项注释了 Agent 级可调参数：

参数	作用
verbose	显示详细执行日志（模板默认 false）
allow_delegation	允许该 Agent 把任务委派给 Crew 内其他 Agent
max_iter	每个任务的最大推理迭代次数，防止死循环（示例值 25）
max_tokens	Agent 响应生成的最大 token 数
max_execution_time	最大执行时间（秒）
max_rpm	每分钟最大 LLM 请求数（限流）
memory	Agent 级记忆，跨任务持久
cache	缓存工具结果，避免重复调用
respect_context_window	上下文超过模型窗口时自动摘要压缩
max_retry_limit	执行出错时的最大重试次数（示例值 2）
规划开关	任务执行前的分步规划（由模板占位符 {{planning_line}} 渲染）
use_system_prompt	LLM 调用中是否包含 system prompt

7. task.jsonc：任务片段模板

task.jsonc 定义了 crew.jsonc 中 tasks 数组内每个元素的形态（渲染时多个片段以 {{tasks_fragments}} 拼入 crew 定义）：

• name：任务标识；description：任务要完成的事，支持 {placeholder} 输入，缺失值在 crewai run 时提示补全。
• expected_output：对输出形态的明确描述。
• 护栏：guardrail（单条规则）或 guardrails（多条），失败时最多重试 guardrail_max_retries 次，例如 "guardrail": "Every factual claim needs context support."。
• 高级选项：type（如 "ConditionalTask" 配合 condition 引用本地条件函数）、output_json / output_pydantic / response_model（结构化输出）、converter_cls、markdown、input_files（如 {"brief": "data/brief.txt"}）、security_config。
• agent：该任务由哪个 Agent 执行；尾部注释还列出了可选的 tools、human_input、async_execution 字段，以及由模板占位符渲染的 context_block / output_file_block 扩展位。

8. 打包与项目元数据：pyproject.toml

pyproject.toml 模板揭示了该项目类型的打包约定：

• Python 版本要求：requires-python = ">=3.10,<3.14"。
• 依赖：仅一条 {{crewai_tools_dependency}}，由脚手架按当前 CLI 版本填充为对应版本的 crewAI 工具包依赖。
• 构建：hatchling 作为构建后端；wheel 的 only-include = ["agents", "crew.jsonc", "tools", "knowledge", "skills"] 精确圈定需要随包发布的声明文件与目录。
• [tool.crewai] 段是 JSON-first 项目的核心标识：

[tool.crewai]
type = "crew"
definition = "crew.jsonc"

即声明本项目是 crew 类型、定义文件为 crew.jsonc。crewai run 正是读取这一配置来定位并加载 Crew 定义的——这解释了为什么 README 中"运行"部分只需一条 crewai run 命令，无需指定入口脚本。

9. 从模板到项目：脚手架渲染链路

从源码结构看，create_json_crew.py 是这一模板的消费方：

• 文件顶部注明其职责为 Scaffold a new JSON-first crew project.，并定义 _TEMPLATES_DIR = Path(__file__).parent / "templates" / "json_crew"（第 100 行），即直接指向本文分析的模板目录。
• 它维护了 12 个模型服务商（OpenAI、Anthropic、Gemini、Groq、Ollama、Bedrock、Azure、NVIDIA NIM、Hugging Face、Cerebras、SambaNova、IBM watsonx，见第 33-46 行 _PROVIDERS）及各自的候选模型清单；注释说明选择器优先通过 model_catalog.get_provider_models 从厂商 API 实时拉取模型，_PROVIDER_MODELS 是无 API Key 时的离线兜底。
• 渲染环节复用 utils.render_template 处理 {{name_json}}、{{settings_block}}、{{tasks_fragments}} 等占位符，同时写入 .env（write_env_file）、可选初始化 Git（initialize_if_git_available）并创建项目遥测 ID（get_or_create_project_id）。
• 在 CLI 入口处，cli.py 中可以看到 from crewai_cli.create_json_crew import create_json_crew 并按 create_json_crew(name, provider, skip_provider) 调用，说明创建命令会透传用户选择的服务商与是否跳过提供商选择。

也就是说，README 中描述的每个目录、crewai run 的可行性，都由"模板目录 + 渲染器 + [tool.crewai] 配置"这条链路共同保证：脚手架负责填充占位符生成可运行项目，crewai run 再依据 definition = "crew.jsonc" 反序列化出完整 Crew。

10. 小结

crewAI 的 JSON-first crew 模板把"写代码定义 Crew"降级为可选路径：Agent 的目标与护栏、Task 的描述与结构化输出、Crew 的执行流程与记忆开关，全部收敛为带注释的 JSONC 声明；[tool.crewai] 配置让 crewai run 成为唯一必需的启动命令；{placeholder} + inputs 机制进一步实现免代码的参数化。理解这套模板的关键在于三个文件——crew.jsonc（Crew 装配）、agent.jsonc（Agent 声明）、task.jsonc（任务片段）——以及 README 中那条不可忽略的安全边界：custom:<name> 工具与 {"python": ...} 回调都会执行本地 Python 代码，因此只能运行可信来源的 crew 项目。