From fc49de7c693a8658c7e5d6d0f7a9732624e9bbb8 Mon Sep 17 00:00:00 2001 From: Gabe Date: Thu, 19 Nov 2026 13:46:44 -0300 Subject: [PATCH] docs: teach the flow skill to save and read artifacts --- .../templates/declarative_flow/AGENTS.md | 4 ++++ lib/crewai/src/crewai/flow/skill.py | 1 + .../flow/templates/flow_definition_skill.md.j2 | 4 ++++ lib/crewai/tests/test_flow_definition.py | 15 +++++++++++++++ 4 files changed, 24 insertions(+) diff --git a/lib/cli/src/crewai_cli/templates/declarative_flow/AGENTS.md b/lib/cli/src/crewai_cli/templates/declarative_flow/AGENTS.md index 9e28378dfe..59905d4097 100644 --- a/lib/cli/src/crewai_cli/templates/declarative_flow/AGENTS.md +++ b/lib/cli/src/crewai_cli/templates/declarative_flow/AGENTS.md @@ -33,6 +33,8 @@ Pick the simplest action that does the job. - Use `call: expression` for simple reads, filters, computed values, and deterministic routing. - Use `call: agent` for one AI worker that classifies, decides, summarizes, writes, or drafts. Put `role`, `goal`, `backstory`, and `input` under `with`. Do not add an action-level `inputs` map to an agent. - Use `call: crew` for coordinated AI work with multiple agents or tasks. Define the crew under `with`. Pass runtime values with the action-level `inputs` map. +- Save an agent's output as an artifact when people should open, download or share it (a report, a chart, a CSV). Set `artifact: true` under `with` to name it after the method and pick the kind from the output, or `artifact: {identifier: weekly-report, title: Weekly report, kind: html}` to set them. For a file the agent's tools write, add `file_path`; `image`, `pdf` and `file` kinds need it. Read its link later as `${outputs.method_name.artifact.url}`. +- Give an agent an artifact the run saved earlier with `input_files: {current_report: {artifact: }}` under `with`, adding `version` for an older one. Use it when a resumed flow revises what it saved before a human review. ## Wire Methods Explicitly @@ -315,6 +317,8 @@ Fields: - `apps` (optional): list[string] | null; default `null`. Platform apps available to this agent. Can contain app names such as `gmail` or app/action refs such as `gmail/send_email`. Example: `["gmail", "slack/send_message"]` - `mcps` (optional): list[string | map of string to any] | null; default `null`. MCP server refs or serialized MCP server configs available to this agent. String refs can use HTTPS URLs, connected MCP integration slugs, or refs with a `#tool_name` suffix for specific tools. Example: `["https://api.weather.com/mcp#get_current_weather", "snowflake", "stripe#list_invoices", {"cache_tools_list": true, "headers": {"Authorization": "Bearer your_token"}, "streamable": true, "url": "https://api.example.com/mcp"}]` - `input` (required): string. Agent prompt template. Insert Flow values with `${...}`, for example `Ticket: ${state.ticket_id}`. Example: `${state.ticket.body}` +- `input_files` (optional): map of string to object | null; default `null`. Files passed to the agent's kickoff, by name. Each points at an artifact this run saved, loaded when the step runs. Example: `{"current_report": {"artifact": "board-report"}}` +- `artifact` (optional): object | boolean | null; default `null`. Save the agent's final output as an artifact. True names it after the flow method and picks the kind from the output. Examples: `true`, `{"identifier": "report", "kind": "html", "title": "Report"}` #### LLM Definition diff --git a/lib/crewai/src/crewai/flow/skill.py b/lib/crewai/src/crewai/flow/skill.py index beae9f7341..e6fb35f214 100644 --- a/lib/crewai/src/crewai/flow/skill.py +++ b/lib/crewai/src/crewai/flow/skill.py @@ -71,6 +71,7 @@ def template_context( "examples_format": examples_format, "example": render_flow_example(examples_format), "example_language": examples_format, + "include_artifacts": "artifacts" not in skips, "include_each_action": "each" not in skips, "include_conversational": "conversational" not in skips, "include_hitl": "hitl" not in skips, diff --git a/lib/crewai/src/crewai/flow/templates/flow_definition_skill.md.j2 b/lib/crewai/src/crewai/flow/templates/flow_definition_skill.md.j2 index 2d8d09d054..47bd921b51 100644 --- a/lib/crewai/src/crewai/flow/templates/flow_definition_skill.md.j2 +++ b/lib/crewai/src/crewai/flow/templates/flow_definition_skill.md.j2 @@ -49,6 +49,10 @@ Pick the simplest action that does the job. - Use `call: agent` for one AI worker that classifies, decides, summarizes, writes, or drafts. Put `role`, `goal`, `backstory`, and `input` under `with`. Do not add an action-level `inputs` map to an agent. - Repository-backed agents may set `from_repository` and omit inline `role`, `goal`, and `backstory`. Explicitly provided fields override repository values. - Use `call: crew` for coordinated AI work with multiple agents or tasks. Define the crew under `with`. Pass runtime values with the action-level `inputs` map. +{% if include_artifacts %} +- Save an agent's output as an artifact when people should open, download or share it (a report, a chart, a CSV). Set `artifact: true` under `with` to name it after the method and pick the kind from the output, or `artifact: {identifier: weekly-report, title: Weekly report, kind: html}` to set them. For a file the agent's tools write, add `file_path`; `image`, `pdf` and `file` kinds need it. Read its link later as `${outputs.method_name.artifact.url}`. +- Give an agent an artifact the run saved earlier with `input_files: {current_report: {artifact: }}` under `with`, adding `version` for an older one. Use it when a resumed flow revises what it saved before a human review. +{% endif %} {% if include_each_action %} - Use `call: each` when the same ordered mini-pipeline must run once per item. Give every step a `name`. {% endif %} diff --git a/lib/crewai/tests/test_flow_definition.py b/lib/crewai/tests/test_flow_definition.py index 5097b42365..d230197721 100644 --- a/lib/crewai/tests/test_flow_definition.py +++ b/lib/crewai/tests/test_flow_definition.py @@ -1524,6 +1524,21 @@ def test_skill_conversational_skip_suppresses_both_sections(): assert "conversational-router" not in skill +def test_skill_explains_saving_and_reading_artifacts(): + skill = flow_definition.FlowDefinition.skill() + + assert "Save an agent's output as an artifact" in skill + assert "`artifact: true`" in skill + assert "{artifact: }" in skill + assert "outputs.method_name.artifact.url" in skill + + +def test_skill_artifacts_skip_drops_the_guidance(): + skill = flow_definition.FlowDefinition.skill(skips=["artifacts"]) + + assert "Save an agent's output as an artifact" not in skill + + def test_skill_can_render_json_examples(): skill = flow_definition.FlowDefinition.skill(examples_format="json")