{{name}} Flow

This project defines a declarative CrewAI Flow in src/{{folder_name}}/flow.yaml.

Install

crewai install

Run

crewai run

Edit the declarative flow definition at src/{{folder_name}}/flow.yaml to change the flow. Add reusable crews under src/{{folder_name}}/crews/, custom Python tools under src/{{folder_name}}/tools/, and shared knowledge files under src/{{folder_name}}/knowledge/.

核心信息只有三句：

- 流程定义在 `src/{{folder_name}}/flow.yaml`（`{{folder_name}}` 是创建项目时由 CLI 替换的项目文件夹名）；
- 先 `crewai install` 安装依赖，再 `crewai run` 执行；
- 修改 `flow.yaml` 即可改变流程，可复用的 Crew 放 `crews/`、自定义 Python 工具放 `tools/`、共享知识文件放 `knowledge/`。

这里的关键设计是：**流程逻辑完全由一份 YAML 文件承载**，而不是 Python 类。下面按“模板结构 → 声明语法 → 执行机制”三层展开。

## 项目骨架：模板由哪些文件组成

执行 `crewai create flow <name> --declarative`（非声明式则省略该标志）时，CLI 会进入 [create_flow.py](https://gitcode.com/GitHub_Trending/cr/crewAI/blob/b608a3595c95085225e9dd47432d74989f1a1d78/lib/cli/src/crewai_cli/create_flow.py?utm_source=gitcode_repo_files#L123-L159) 中的 `_create_declarative_flow()`：

- 创建 `src/<folder_name>/` 包目录，并固定创建 `crews`、`tools`、`knowledge`、`skills` 四个子目录（源码常量 `DECLARATIVE_FLOW_FOLDERS`）；
- 将模板目录 `templates/declarative_flow` 下的文件复制到新项目：`.gitignore`、`AGENTS.md`、`README.md`、`pyproject.toml` 落在项目根目录，`flow.yaml` 落在 `src/<folder_name>/` 下；
- 用 `{{name}}`、`{{flow_name}}`、`{{folder_name}}`、`{{crewai_tools_dependency}}` 四个占位符替换为实际值；
- 额外写入 `.env`（含 `OPENAI_API_KEY=YOUR_API_KEY` 占位）和空的 `__init__.py`。

其中 `pyproject.toml` 模板（[pyproject.toml](https://gitcode.com/GitHub_Trending/cr/crewAI/blob/b608a3595c95085225e9dd47432d74989f1a1d78/lib/cli/src/crewai_cli/templates/declarative_flow/pyproject.toml?utm_source=gitcode_repo_files)）声明了项目类型与定义文件位置，这是 `crewai run` 能“无参数找到 flow.yaml”的依据：

```toml
[project]
name = "{{folder_name}}"
version = "0.1.0"
requires-python = ">=3.10,<3.14"
dependencies = [
    "{{crewai_tools_dependency}}"
]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.hatch.build.targets.wheel]
packages = ["src/{{folder_name}}"]

[tool.crewai]
type = "flow"
definition = "src/{{folder_name}}/flow.yaml"

[tool.crewai] 段的 type = "flow" 与 definition 路径，就是 CLI 解析项目定义文件的入口配置。注意 Python 版本要求为 >=3.10,<3.14，创建项目后需要在此范围内运行。

模板内置的最小 flow.yaml（flow.yaml）是一个纯表达式示例，展示了声明文件的骨架：

schema: crewai.flow/v1
name: {{flow_name}}
description: A declarative CrewAI Flow.

state:
  type: dict
  default:
    topic: AI agents

methods:
  start:
    start: true
    do:
      call: expression
      expr: state.topic

它声明了 dict 类型的初始 state、一个带默认值 topic: AI agents，以及唯一一个 start: true 的入口方法 start，该方法执行 CEL 表达式 state.topic，把 state 中的 topic 作为流程结果输出。

flow.yaml 声明规范：state、methods 与三种动作

模板同时附带了一份面向编码 Agent 的完整写作规范 AGENTS.md，其中给出了 crewai.flow/v1 声明的完整字段参考与示例。这是编写声明式 Flow 的权威依据，下面按章节继承其核心内容。

顶层字段

字段	必填	说明
schema	可选	必须为 crewai.flow/v1（默认即该值），建议在声明中显式写出
name	必填	字符串，用于日志、事件与 trace 的唯一流程名
description	可选	人类可读的流程摘要
state	必填	初始状态与执行期间更新的状态契约
config	可选	流程级执行配置（见下文 Config 小节）
methods	必填	方法名 → 方法定义的映射

state 状态契约

state 支持 JSON Schema 形式声明：

state:
  type: json_schema
  json_schema:
    type: object
    properties:
      topic:
        type: string
      audience:
        type: string
    required:
      - topic
      - audience
  default:
    topic: AI agent orchestration
    audience: platform engineering leaders

• json_schema（必填）：用 JSON Schema 校验并文档化 state；
• default（可选）：初始化 state 的默认值。AGENTS.md 明确提醒：不要用 state.default 来表达必填，必填字段必须写进 json_schema.required——这一点与 CLI 运行时的输入解析行为一致（见“执行机制”一节）。

method 方法定义

每个方法（methods.<name>）的字段：

• description（可选）：方法摘要；
• do（必填）：单个动作对象，不允许把 do 写成列表；
• start（可选）：标记唯一入口，取 true；
• listen（可选）：在上游方法或 router 事件后触发本方法；
• router（可选，默认 false）：方法输出是否被解释为下一个事件名。router 动作必须恰好返回一个事件名字符串，不能返回 JSON、列表或解释性文字；
• emit（可选）：该 router 方法可发出的事件名列表，事件名应唯一且不得与方法名冲突。

方法名必须匹配 ^[A-Za-z_][A-Za-z0-9_]*$。

三种动作：expression / agent / crew

do 是以 call 字段判别的三选一联合类型：

1. call: expression —— 确定性计算与路由

do:
  call: expression
  expr: state.topic

expr 是 CEL 表达式，对 state、outputs 和局部上下文求值。适合简单读取、过滤、计算值与确定性路由——AGENTS.md 建议“能用 expression 算出来的路由就不要动用 agent”。

2. call: agent —— 单个 AI 工作者

do:
  call: agent
  with:
    role: Follow-up router
    goal: 'Return exactly one bare value: followup or done. Do not include explanation.'
    backstory: Skilled at routing reviewed research briefs.
    input: "Reviewed research: ${outputs.research_brief.raw}"

agent 动作的输入放在 with.input（必填，文本），不支持动作级 inputs 映射。适合分类、决策、摘要、写作等单点 AI 工作。

3. call: crew —— 多 Agent 协同

do:
  call: crew
  with:
    agents:
      researcher:
        role: Research analyst
        goal: Research {topic} for {audience}
        backstory: Expert at concise technical research.
    tasks:
      - name: research_task
        description: Research {topic} for {audience}.
        expected_output: Key findings and tradeoffs.
        agent: researcher
  inputs:
    topic: "${state.topic}"
    audience: "${state.audience}"

注意两套插值语言的区别：动作级 inputs 里的 ${...} 是 CEL 模板，把 Flow 数据带入 crew；而 agent 的 role/goal 与 task 的 description/expected_output 里用的是 {name} 占位符，对应 crew 输入值（不是 CEL）。with 内的 inputs 只作静态默认值；运行时数据一律走动作级 inputs。

CEL 表达式与动态值规则

AGENTS.md 对 CEL 的使用规则非常具体，直接决定声明能否跑对：

• 原始 CEL 写在 expr 里，不要包 ${...}；${...} 只在动作映射字符串内使用，如 query: "News about ${state.topic}"；
• 可用的两个变量：state（初始输入数据，如 state.ticket.subject）与 outputs（已完成方法的结果，如 outputs.classify_ticket）；
• 整个值只有一个 ${...} 时保留原类型（数字、布尔、对象、列表）：limit: "${state.limit}"；字符串里还有其他文本时结果是文本，非文本值会转成 JSON，null 变空文本；
• 不要用 CEL 的 + 拼接文本——把字面文本留在外面、逐值插值：写 Ticket: ${state.ticket_id}，不要拼字符串；
• crew 输出是对象：取文本用 ${outputs.research_brief.raw}，取结构化字段用 ${outputs.research_brief.json_dict.field} 或 ${outputs.research_brief.pydantic.field}；不要直接把整个 crew 输出塞给 agent 输入（如 ${outputs.research_brief}）；
• agent 输出也可以是对象：${outputs.classify_ticket.raw}、${outputs.classify_ticket.pydantic.category}。

方法连线规则（listen / router / emit）

• 结果不会自动合并进 state——读方法结果要用 outputs.method_name；
• listen 指向方法名或 router 发出的事件名，两者共享同一命名空间；
• 方法不能 listen 自己的方法名（包括 listen 的路由标签恰好与方法名相同的情形）；
• emit 必须配合 router: true；router 的结果必须命中 emit 中声明的某个事件名；
• 如果路由逻辑可以计算，优先 call: expression；用 agent 做 router 时，goal 里要明确“只返回一个裸值”。

一个完整的声明示例（Crew 研究 + 路由跟进）

AGENTS.md 附带的完整示例展示了“crew 产出 → agent 路由 → 按事件分支跟进”的常见形态，这里完整保留：

schema: crewai.flow/v1
name: ResearchReviewFlow
state:
  type: json_schema
  json_schema:
    type: object
    properties:
      topic:
        type: string
      audience:
        type: string
    required:
      - topic
      - audience
  default:
    topic: AI agent orchestration
    audience: platform engineering leaders
methods:
  research_brief:
    start: true
    do:
      call: crew
      with:
        agents:
          researcher:
            role: Research analyst
            goal: Research {topic} for {audience}
            backstory: Expert at concise technical research.
          reviewer:
            role: Strategy reviewer
            goal: Decide whether the research needs an executive follow-up
            backstory: Experienced at reviewing technical briefs for leaders.
        tasks:
          - name: research_task
            description: Research {topic} for {audience}.
            expected_output: Key findings and tradeoffs.
            agent: researcher
          - name: review_task
            description: Review the research and decide if an executive follow-up is needed.
            expected_output: 'A brief review ending with `needs_followup: true` or `needs_followup: false`.'
            agent: reviewer
        inputs:
          topic: Default topic
          audience: Default audience
      inputs:
        topic: "${state.topic}"
        audience: "${state.audience}"
  route_followup:
    listen: research_brief
    router: true
    emit:
      - followup
      - done
    do:
      call: agent
      with:
        role: Follow-up router
        goal: 'Return exactly one bare value: followup or done. Do not include explanation.'
        backstory: Skilled at routing reviewed research briefs.
        input: "Reviewed research: ${outputs.research_brief.raw}"
  write_followup:
    listen: followup
    do:
      call: agent
      with:
        role: Executive communications specialist
        goal: Draft a concise executive follow-up from the reviewed research
        backstory: Writes crisp follow-ups for technical leaders.
        input: "${outputs.research_brief.raw}"