Document flow agent options (#6420)

* Document flow agent options

Document and type inline Flow agent options so authored flows can set:
* `llm.model`, `llm.max_tokens`, and `llm.max_completion_tokens`
* `planning_config.max_attempts`
* `allow_delegation`
* `max_iter`
* `max_rpm`
* `max_execution_time` in seconds

Also tell the flow skill to omit optional fields unless needed.

* Potential fix for pull request finding 'Unused import'

Co-authored-by: Copilot Autofix powered by AI <223894421+github-code-quality[bot]@users.noreply.github.com>

---------

Co-authored-by: Copilot Autofix powered by AI <223894421+github-code-quality[bot]@users.noreply.github.com>

lib/cli/src/crewai_cli/templates/declarative_flow/AGENTS.md

@@ -1,8 +1,3 @@
----
-name: flow-definition
-description: Create or edit CrewAI Flow declarations. Use when the user needs a YAML or JSON flow with methods, state, agents, crews, tools, outputs, or conditional branches.
----
-
 # Flow Definition
 
 You are writing a CrewAI Flow declaration for the user.
@@ -27,6 +22,8 @@ Do not include explanatory prose unless the user asks for it.
 6. Pass data with `${...}` mappings from `state` and completed `outputs`.
 7. Before final output, check every `listen`, `emit`, and `outputs.some_method` reference.
 
+Set optional fields only when you are confident they are needed. Otherwise, trust CrewAI defaults and omit them.
+
 Method names must match `^[A-Za-z_][A-Za-z0-9_]*$`.
 
 ## Choose One Action Per Method
@@ -42,6 +39,7 @@ Pick the simplest action that does the job.
 - `state` is the initial shared data shape. Action results do not automatically merge into `state`.
 - Read method results with `outputs.method_name` after that method can run.
 - `listen` targets a method name or a router-emitted event name.
+- Methods must not listen to their own method name.
 - Method names and emitted event names share one namespace. Avoid reusing the same string for both unless the user explicitly wants that.
 - Use `router: true` plus `emit` when one method chooses between named branches.
 - A router action must return exactly one emitted event string. It must not return JSON, a list, or an explanation.
@@ -93,6 +91,7 @@ Dynamic value rules:
 - Do not put more than one action under a method's `do`.
 - Do not make `do` a list.
 - Do not reference `outputs.some_method` before `some_method` can run.
+- Do not set a method's `listen` to its own method name.
 - Do not use the same string for an emitted event and a method name unless the user asks for it.
 - Do not use `emit` without `router: true`.
 - Do not rely on crew action-level `inputs` alone to ground agent behavior. Inputs that do not match placeholders are effectively unused by the prompt.
@@ -163,7 +162,7 @@ methods:
         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: "${outputs.research_brief.raw}"
+        input: "${'Reviewed research: ' + text(outputs, 'research_brief.raw')}"
   write_followup:
     listen: followup
     do:
@@ -186,6 +185,7 @@ Fields:
 - `name` (required): string. Unique flow name used in logs, events, and traces.
 - `description` (optional): string | null; default `null`. Human-readable summary of the flow.
 - `state` (required): [State](#json-schema-state-statetypejson_schema). State contract for the initial state and updates during execution.
+- `config` (optional): [Config (`config`)](#config-config); default generated default. Serializable flow-level execution configuration.
 - `methods` (required): map of string to [Method](#method-methods). Mapping of method names to method definitions.
 
 ### JSON Schema State (`state[type=json_schema]`)
@@ -241,10 +241,22 @@ Fields:
 - `goal` (required): string. Crew agent goal. Crew inputs are interpolated with `{name}` placeholders such as `{topic}`; this is not CEL. Example: `Research {topic}`
 - `backstory` (required): string. Crew agent backstory. Crew inputs are interpolated with `{name}` placeholders such as `{topic}`; this is not CEL. Example: `Expert at concise technical research.`
 - `settings` (optional): map of string to any. Additional agent settings passed to the loader. Example: `{"llm": "openai/gpt-4o-mini"}`
+- `llm` (optional): string or inline LLM config; default `null`. Language model that runs this crew agent. Use an object when setting LLM options such as `max_tokens`. Example: `{"max_tokens": 4096, "model": "openai/gpt-4o-mini"}`
+- `planning_config` (optional): object | null; default `null`. Agent planning configuration. Set `max_attempts` to limit planning refinement attempts before task execution. Example: `{"max_attempts": 3}`
+- `allow_delegation` (optional): boolean | null; default `null`. Enable agent to delegate and ask questions among each other. Example: `false`
+- `max_iter` (optional): integer | null; default `null`. Maximum iterations for an agent to execute a task Example: `25`
+- `max_rpm` (optional): integer | null; default `null`. Maximum number of requests per minute for the agent execution to be respected. Example: `10`
+- `max_execution_time` (optional): integer | null; default `null`. Maximum execution time in seconds for an agent to execute a task Example: `300`
 - `tools` (optional): list[string | map of string to any] | null; default `null`. Tool refs or serialized tool definitions available to this agent. String refs can use CrewAI tool names, `custom:<name>`, or fully qualified `module:Class` references. Example: `["crewai_tools:SerperDevTool", "custom:file_read"]`
 - `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"}]`
 
+#### LLM Definition
+
+Fields:
+- `model` (required): string. Model identifier used to instantiate the LLM. Example: `openai/gpt-4o-mini`
+- `max_tokens` (optional): integer | null; default `null`. Maximum number of tokens the LLM can generate. If null, CrewAI does not set an explicit output token cap and the provider's default applies. Example: `4096`
+
 #### Crew Task Definition (`methods.<name>.do[call=crew].with.tasks[]`)
 
 Fields:
@@ -269,11 +281,23 @@ Fields:
 - `goal` (required): string. Individual agent goal for the Flow agent action outside of a crew. Example: `Draft a concise customer reply`
 - `backstory` (required): string. Individual agent backstory used to shape behavior outside of a crew. Example: `Expert at resolving SaaS support questions.`
 - `settings` (optional): map of string to any. Additional agent settings passed to the loader. Example: `{"llm": "openai/gpt-4o-mini"}`
+- `llm` (optional): string or inline LLM config; default `null`. Language model that runs this agent. Use an object when setting LLM options such as `max_tokens`. Example: `{"max_tokens": 4096, "model": "openai/gpt-4o-mini"}`
+- `planning_config` (optional): object | null; default `null`. Agent planning configuration. Set `max_attempts` to limit planning refinement attempts before task execution. Example: `{"max_attempts": 3}`
+- `allow_delegation` (optional): boolean | null; default `null`. Enable agent to delegate and ask questions among each other. Example: `false`
+- `max_iter` (optional): integer | null; default `null`. Maximum iterations for an agent to execute a task Example: `25`
+- `max_rpm` (optional): integer | null; default `null`. Maximum number of requests per minute for the agent execution to be respected. Example: `10`
+- `max_execution_time` (optional): integer | null; default `null`. Maximum execution time in seconds for an agent to execute a task Example: `300`
 - `tools` (optional): list[string | map of string to any] | null; default `null`. Tool refs or serialized tool definitions available to this agent. String refs can use CrewAI tool names, `custom:<name>`, or fully qualified `module:Class` references. Example: `["crewai_tools:SerperDevTool", "custom:file_read"]`
 - `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. Input passed to the individual agent kickoff outside of a crew. Use a single string value, often a dynamic `${...}` expression. When an agent needs multiple fields, build one single-line CEL string with labels and separators, using `text(root, 'path')` for values that may be missing or null, for example `${'Ticket ID: ' + text(state, 'ticket_id') + '; Message: ' + text(state, 'message')}`. In YAML, avoid `\n` escapes inside `${...}` strings. Example: `${state.ticket.body}`
 
+#### LLM Definition
+
+Fields:
+- `model` (required): string. Model identifier used to instantiate the LLM. Example: `openai/gpt-4o-mini`
+- `max_tokens` (optional): integer | null; default `null`. Maximum number of tokens the LLM can generate. If null, CrewAI does not set an explicit output token cap and the provider's default applies. Example: `4096`
+
 ### Expression Action (`methods.<name>.do[call=expression]`)
 
 Shape:
@@ -283,11 +307,25 @@ Fields:
 - `call` (required): must be `expression`. Action discriminator. Use expression to evaluate a CEL expression.
 - `expr` (required): string. CEL expression evaluated against state, outputs, and local context.
 
+### Config (`config`)
+
+Fields:
+- `tracing` (optional): boolean | null; default `null`. Override for flow tracing; when omitted, execution defaults apply.
+- `stream` (optional): boolean; default `false`. Whether the flow should emit streaming events when supported.
+- `memory` (optional): map of string to any | null; default `null`. Serializable memory configuration passed to flow execution.
+- `input_provider` (optional): string | null; default `null`. Provider key used to supply initial state.
+- `suppress_flow_events` (optional): boolean; default `false`. Disable flow event emission for this definition.
+- `max_method_calls` (optional): integer; default `100`. Maximum number of method executions allowed during one kickoff.
+- `defer_trace_finalization` (optional): boolean; default `false`. Defer trace finalization so callers can complete tracing later.
+- `checkpoint` (optional): boolean | map of string to any | null; default `null`. Checkpointing configuration, or true to use default checkpointing.
+
 ### Cross-Field Rules
 
 - A method has exactly one `do` action object with one `call` discriminator.
 - `listen` targets method names and router-emitted event names in one shared namespace.
+- Methods cannot listen to their own method name.
 - A router method result must match one declared `emit` value.
 - Crew action-level `inputs` are the Crew kickoff inputs; use CEL-wrapped strings there for runtime values.
 - Crew agent/task interpolation uses `{name}` placeholders from evaluated crew inputs.
 - Agent `with.input` must be text. Use `${outputs.method_name.raw}` or a text field like `${outputs.method_name.json_dict.summary}`.
+