mirror of
https://github.com/crewAIInc/crewAI.git
synced 2026-04-30 14:52:36 +00:00
pass 1 for ai readable
This commit is contained in:
lorenzejay
@@ -79,6 +79,78 @@
|
||||
"en/quickstart"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "AI Docs",
|
||||
"pages": [
|
||||
"en/ai/overview",
|
||||
{
|
||||
"group": "Flows",
|
||||
"icon": "arrow-progress",
|
||||
"pages": [
|
||||
"en/ai/flows/index",
|
||||
"en/ai/flows/reference",
|
||||
"en/ai/flows/patterns",
|
||||
"en/ai/flows/troubleshooting",
|
||||
"en/ai/flows/examples"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Agents",
|
||||
"icon": "user",
|
||||
"pages": [
|
||||
"en/ai/agents/index",
|
||||
"en/ai/agents/reference",
|
||||
"en/ai/agents/patterns",
|
||||
"en/ai/agents/troubleshooting",
|
||||
"en/ai/agents/examples"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Crews",
|
||||
"icon": "users",
|
||||
"pages": [
|
||||
"en/ai/crews/index",
|
||||
"en/ai/crews/reference",
|
||||
"en/ai/crews/patterns",
|
||||
"en/ai/crews/troubleshooting",
|
||||
"en/ai/crews/examples"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "LLMs",
|
||||
"icon": "microchip-ai",
|
||||
"pages": [
|
||||
"en/ai/llms/index",
|
||||
"en/ai/llms/reference",
|
||||
"en/ai/llms/patterns",
|
||||
"en/ai/llms/troubleshooting",
|
||||
"en/ai/llms/examples"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Memory",
|
||||
"icon": "database",
|
||||
"pages": [
|
||||
"en/ai/memory/index",
|
||||
"en/ai/memory/reference",
|
||||
"en/ai/memory/patterns",
|
||||
"en/ai/memory/troubleshooting",
|
||||
"en/ai/memory/examples"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Tools",
|
||||
"icon": "wrench",
|
||||
"pages": [
|
||||
"en/ai/tools/index",
|
||||
"en/ai/tools/reference",
|
||||
"en/ai/tools/patterns",
|
||||
"en/ai/tools/troubleshooting",
|
||||
"en/ai/tools/examples"
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Guides",
|
||||
"pages": [
|
||||
@@ -331,6 +403,7 @@
|
||||
"en/learn/human-input-on-execution",
|
||||
"en/learn/human-in-the-loop",
|
||||
"en/learn/human-feedback-in-flows",
|
||||
"en/learn/flowstate-chat-history",
|
||||
"en/learn/kickoff-async",
|
||||
"en/learn/kickoff-for-each",
|
||||
"en/learn/llm-connections",
|
||||
@@ -483,7 +556,6 @@
|
||||
{
|
||||
"group": "Examples",
|
||||
"pages": [
|
||||
"en/examples/example",
|
||||
"en/examples/cookbooks"
|
||||
]
|
||||
}
|
||||
@@ -1482,6 +1554,18 @@
|
||||
"source": "/api-reference",
|
||||
"destination": "/en/api-reference/introduction"
|
||||
},
|
||||
{
|
||||
"source": "/",
|
||||
"destination": "/en/introduction"
|
||||
},
|
||||
{
|
||||
"source": "/en",
|
||||
"destination": "/en/introduction"
|
||||
},
|
||||
{
|
||||
"source": "/en/examples/example",
|
||||
"destination": "/en/examples/cookbooks"
|
||||
},
|
||||
{
|
||||
"source": "/introduction",
|
||||
"destination": "/en/introduction"
|
||||
@@ -1578,4 +1662,4 @@
|
||||
"reddit": "https://www.reddit.com/r/crewAIInc/"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
12
docs/en/ai/agents/examples.mdx
Normal file
12
docs/en/ai/agents/examples.mdx
Normal file
@@ -0,0 +1,12 @@
|
||||
---
|
||||
title: "Agents: Examples"
|
||||
description: "Runnable examples for robust agent configuration and execution."
|
||||
icon: "rocket-launch"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Example links
|
||||
|
||||
- [/en/guides/agents/crafting-effective-agents](/en/guides/agents/crafting-effective-agents)
|
||||
- [/en/learn/customizing-agents](/en/learn/customizing-agents)
|
||||
- [/en/learn/coding-agents](/en/learn/coding-agents)
|
||||
32
docs/en/ai/agents/index.mdx
Normal file
32
docs/en/ai/agents/index.mdx
Normal file
@@ -0,0 +1,32 @@
|
||||
---
|
||||
title: "Agents: Concepts"
|
||||
description: "Agent role contracts, task boundaries, and decision criteria for robust agent behavior."
|
||||
icon: "user"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## When to use
|
||||
|
||||
- You need specialized behavior with explicit role and goal.
|
||||
- You need tool-enabled execution under constraints.
|
||||
|
||||
## When not to use
|
||||
|
||||
- Static transformations are enough without model reasoning.
|
||||
- Task can be solved by deterministic code only.
|
||||
|
||||
## Core decisions
|
||||
|
||||
| Decision | Choose this when |
|
||||
|---|---|
|
||||
| Single agent | Narrow scope, low coordination needs |
|
||||
| Multi-agent crew | Distinct expertise and review loops needed |
|
||||
| Tool-enabled agent | Model needs external actions or data |
|
||||
|
||||
## Canonical links
|
||||
|
||||
- Reference: [/en/ai/agents/reference](/en/ai/agents/reference)
|
||||
- Patterns: [/en/ai/agents/patterns](/en/ai/agents/patterns)
|
||||
- Troubleshooting: [/en/ai/agents/troubleshooting](/en/ai/agents/troubleshooting)
|
||||
- Examples: [/en/ai/agents/examples](/en/ai/agents/examples)
|
||||
- Existing docs: [/en/concepts/agents](/en/concepts/agents)
|
||||
17
docs/en/ai/agents/patterns.mdx
Normal file
17
docs/en/ai/agents/patterns.mdx
Normal file
@@ -0,0 +1,17 @@
|
||||
---
|
||||
title: "Agents: Patterns"
|
||||
description: "Practical agent patterns for role design, tool boundaries, and reliable outputs."
|
||||
icon: "diagram-project"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Patterns
|
||||
|
||||
1. Role + reviewer pair
|
||||
- One agent drafts, one agent validates.
|
||||
|
||||
2. Tool-bounded agent
|
||||
- Restrict tool list to minimal action set.
|
||||
|
||||
3. Structured output agent
|
||||
- Force JSON or schema output for automation pipelines.
|
||||
22
docs/en/ai/agents/reference.mdx
Normal file
22
docs/en/ai/agents/reference.mdx
Normal file
@@ -0,0 +1,22 @@
|
||||
---
|
||||
title: "Agents: Reference"
|
||||
description: "Reference for agent fields, prompt contracts, tool usage, and output constraints."
|
||||
icon: "book"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Agent contract
|
||||
|
||||
- `role`: stable operating identity
|
||||
- `goal`: measurable completion objective
|
||||
- `backstory`: bounded style and context
|
||||
- `tools`: allowed action surface
|
||||
|
||||
## Output contract
|
||||
|
||||
- Prefer structured outputs for machine workflows.
|
||||
- Define failure behavior for missing tool data.
|
||||
|
||||
## Canonical source
|
||||
|
||||
Primary API details live in [/en/concepts/agents](/en/concepts/agents).
|
||||
12
docs/en/ai/agents/troubleshooting.mdx
Normal file
12
docs/en/ai/agents/troubleshooting.mdx
Normal file
@@ -0,0 +1,12 @@
|
||||
---
|
||||
title: "Agents: Troubleshooting"
|
||||
description: "Diagnose and fix common agent reliability and instruction-following failures."
|
||||
icon: "circle-exclamation"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Common issues
|
||||
|
||||
- Hallucinated tool results: require tool-call evidence in output.
|
||||
- Prompt drift: tighten role and success criteria.
|
||||
- Verbose but low-signal output: enforce concise schema output.
|
||||
12
docs/en/ai/crews/examples.mdx
Normal file
12
docs/en/ai/crews/examples.mdx
Normal file
@@ -0,0 +1,12 @@
|
||||
---
|
||||
title: "Crews: Examples"
|
||||
description: "Runnable crew examples for sequential and hierarchical execution."
|
||||
icon: "rocket-launch"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Example links
|
||||
|
||||
- [/en/guides/crews/first-crew](/en/guides/crews/first-crew)
|
||||
- [/en/learn/sequential-process](/en/learn/sequential-process)
|
||||
- [/en/learn/hierarchical-process](/en/learn/hierarchical-process)
|
||||
26
docs/en/ai/crews/index.mdx
Normal file
26
docs/en/ai/crews/index.mdx
Normal file
@@ -0,0 +1,26 @@
|
||||
---
|
||||
title: "Crews: Concepts"
|
||||
description: "When to use crews, process selection, delegation boundaries, and collaboration strategy."
|
||||
icon: "users"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## When to use
|
||||
|
||||
- You need multiple agents with specialized roles.
|
||||
- You need staged execution and reviewer loops.
|
||||
|
||||
## Process decision table
|
||||
|
||||
| Process | Best for |
|
||||
|---|---|
|
||||
| Sequential | Linear pipelines and deterministic ordering |
|
||||
| Hierarchical | Manager-controlled planning and delegation |
|
||||
|
||||
## Canonical links
|
||||
|
||||
- Reference: [/en/ai/crews/reference](/en/ai/crews/reference)
|
||||
- Patterns: [/en/ai/crews/patterns](/en/ai/crews/patterns)
|
||||
- Troubleshooting: [/en/ai/crews/troubleshooting](/en/ai/crews/troubleshooting)
|
||||
- Examples: [/en/ai/crews/examples](/en/ai/crews/examples)
|
||||
- Existing docs: [/en/concepts/crews](/en/concepts/crews)
|
||||
12
docs/en/ai/crews/patterns.mdx
Normal file
12
docs/en/ai/crews/patterns.mdx
Normal file
@@ -0,0 +1,12 @@
|
||||
---
|
||||
title: "Crews: Patterns"
|
||||
description: "Production crew patterns for decomposition, review loops, and hybrid orchestration with Flows."
|
||||
icon: "diagram-project"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Patterns
|
||||
|
||||
1. Researcher + writer + reviewer
|
||||
2. Manager-directed hierarchical crew
|
||||
3. Flow-orchestrated multi-crew pipeline
|
||||
21
docs/en/ai/crews/reference.mdx
Normal file
21
docs/en/ai/crews/reference.mdx
Normal file
@@ -0,0 +1,21 @@
|
||||
---
|
||||
title: "Crews: Reference"
|
||||
description: "Reference for crew composition, process semantics, task context passing, and execution modes."
|
||||
icon: "book"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Crew contract
|
||||
|
||||
- `agents`: available executors
|
||||
- `tasks`: work units with expected output
|
||||
- `process`: ordering and delegation semantics
|
||||
|
||||
## Runtime
|
||||
|
||||
- `kickoff()` for synchronous runs
|
||||
- `kickoff_async()` for async execution
|
||||
|
||||
## Canonical source
|
||||
|
||||
Primary API details live in [/en/concepts/crews](/en/concepts/crews).
|
||||
12
docs/en/ai/crews/troubleshooting.mdx
Normal file
12
docs/en/ai/crews/troubleshooting.mdx
Normal file
@@ -0,0 +1,12 @@
|
||||
---
|
||||
title: "Crews: Troubleshooting"
|
||||
description: "Common multi-agent coordination failures and practical fixes."
|
||||
icon: "circle-exclamation"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Common issues
|
||||
|
||||
- Agents overlap on responsibilities: tighten role boundaries.
|
||||
- Output inconsistency: standardize expected outputs per task.
|
||||
- Slow runs: reduce unnecessary handoffs and model size.
|
||||
17
docs/en/ai/flows/examples.mdx
Normal file
17
docs/en/ai/flows/examples.mdx
Normal file
@@ -0,0 +1,17 @@
|
||||
---
|
||||
title: "Flows: Examples"
|
||||
description: "Runnable end-to-end examples for production flow orchestration."
|
||||
icon: "rocket-launch"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Canonical examples
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Flowstate Chat History" icon="comments" href="/en/learn/flowstate-chat-history">
|
||||
Persistent chat history with summary compaction and memory scope.
|
||||
</Card>
|
||||
<Card title="Flows Concepts Example" icon="arrow-progress" href="/en/concepts/flows">
|
||||
Full API and feature-oriented flow examples, including routers and persistence.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
39
docs/en/ai/flows/index.mdx
Normal file
39
docs/en/ai/flows/index.mdx
Normal file
@@ -0,0 +1,39 @@
|
||||
---
|
||||
title: "Flows: Concepts"
|
||||
description: "When to use Flows, when not to use them, and key design constraints for production orchestration."
|
||||
icon: "arrow-progress"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## When to use
|
||||
|
||||
- You need deterministic orchestration, branching, and resumable execution.
|
||||
- You need explicit state transitions across steps.
|
||||
- You need persistence, routing, and event-driven control.
|
||||
|
||||
## When not to use
|
||||
|
||||
- A single prompt/response interaction is enough.
|
||||
- You only need one agent call without orchestration logic.
|
||||
|
||||
## Core decisions
|
||||
|
||||
| Decision | Choose this when |
|
||||
|---|---|
|
||||
| Unstructured state | Fast prototyping, highly dynamic fields |
|
||||
| Structured state | Stable contracts, team development, type safety |
|
||||
| `@persist()` | Long-running workflows and recovery requirements |
|
||||
| Router labels | Deterministic branch handling |
|
||||
|
||||
## Canonical links
|
||||
|
||||
- Reference: [/en/ai/flows/reference](/en/ai/flows/reference)
|
||||
- Patterns: [/en/ai/flows/patterns](/en/ai/flows/patterns)
|
||||
- Troubleshooting: [/en/ai/flows/troubleshooting](/en/ai/flows/troubleshooting)
|
||||
- Examples: [/en/ai/flows/examples](/en/ai/flows/examples)
|
||||
|
||||
## Existing docs
|
||||
|
||||
- [/en/concepts/flows](/en/concepts/flows)
|
||||
- [/en/guides/flows/mastering-flow-state](/en/guides/flows/mastering-flow-state)
|
||||
- [/en/learn/flowstate-chat-history](/en/learn/flowstate-chat-history)
|
||||
29
docs/en/ai/flows/patterns.mdx
Normal file
29
docs/en/ai/flows/patterns.mdx
Normal file
@@ -0,0 +1,29 @@
|
||||
---
|
||||
title: "Flows: Patterns"
|
||||
description: "Production flow patterns: triage routing, flowstate chat history, and human-in-the-loop checkpoints."
|
||||
icon: "diagram-project"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Recommended patterns
|
||||
|
||||
1. Triage router flow
|
||||
- Inputs: normalized request payload
|
||||
- Output: deterministic route label + action
|
||||
- Reference: [/en/concepts/flows](/en/concepts/flows)
|
||||
|
||||
2. Flowstate chat history
|
||||
- Inputs: `session_id`, `last_user_message`
|
||||
- Output: assistant reply + compact context state
|
||||
- Reference: [/en/learn/flowstate-chat-history](/en/learn/flowstate-chat-history)
|
||||
|
||||
3. Human feedback gates
|
||||
- Inputs: generated artifact + reviewer feedback
|
||||
- Output: approved/rejected/revision path
|
||||
- Reference: [/en/learn/human-feedback-in-flows](/en/learn/human-feedback-in-flows)
|
||||
|
||||
## Pattern requirements
|
||||
|
||||
- declare explicit input schema
|
||||
- define expected output shape
|
||||
- list failure modes and retries
|
||||
34
docs/en/ai/flows/reference.mdx
Normal file
34
docs/en/ai/flows/reference.mdx
Normal file
@@ -0,0 +1,34 @@
|
||||
---
|
||||
title: "Flows: Reference"
|
||||
description: "API-oriented reference for Flow decorators, lifecycle semantics, state, routing, and persistence."
|
||||
icon: "book"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Decorators
|
||||
|
||||
- `@start()` entrypoint, optional conditional trigger
|
||||
- `@listen(...)` downstream method subscription
|
||||
- `@router(...)` label-based deterministic routing
|
||||
- `@persist()` automatic state persistence checkpoints
|
||||
|
||||
## Runtime contracts
|
||||
|
||||
- `kickoff(inputs=...)` initializes or updates run inputs.
|
||||
- final output is the value from the last completed method.
|
||||
- `self.state` always has an auto-generated `id`.
|
||||
|
||||
## State contracts
|
||||
|
||||
- Use typed state for durable workflows.
|
||||
- Keep control fields explicit (`route`, `status`, `retry_count`).
|
||||
- Avoid storing unbounded raw transcripts in state.
|
||||
|
||||
## Resume and recovery
|
||||
|
||||
- Use persistence for recoverable runs.
|
||||
- Keep idempotent step logic for safe retries.
|
||||
|
||||
## Canonical source
|
||||
|
||||
Primary API details live in [/en/concepts/flows](/en/concepts/flows).
|
||||
28
docs/en/ai/flows/troubleshooting.mdx
Normal file
28
docs/en/ai/flows/troubleshooting.mdx
Normal file
@@ -0,0 +1,28 @@
|
||||
---
|
||||
title: "Flows: Troubleshooting"
|
||||
description: "Common flow failures, causes, and fixes for state, routing, persistence, and resumption."
|
||||
icon: "circle-exclamation"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Common issues
|
||||
|
||||
### Branch did not trigger
|
||||
|
||||
- Cause: router label mismatch.
|
||||
- Fix: align returned label with `@listen("label")` exactly.
|
||||
|
||||
### State fields missing
|
||||
|
||||
- Cause: untyped dynamic writes or missing inputs.
|
||||
- Fix: switch to typed state and validate required fields at `@start()`.
|
||||
|
||||
### Context window blow-up
|
||||
|
||||
- Cause: raw message accumulation.
|
||||
- Fix: use sliding window + summary compaction pattern.
|
||||
|
||||
### Resume behavior inconsistent
|
||||
|
||||
- Cause: non-idempotent side effects in retried steps.
|
||||
- Fix: make side-effecting calls idempotent and record execution markers in state.
|
||||
12
docs/en/ai/llms/examples.mdx
Normal file
12
docs/en/ai/llms/examples.mdx
Normal file
@@ -0,0 +1,12 @@
|
||||
---
|
||||
title: "LLMs: Examples"
|
||||
description: "Concrete examples for model setup, routing, and output-control patterns."
|
||||
icon: "rocket-launch"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Example links
|
||||
|
||||
- [/en/concepts/llms](/en/concepts/llms)
|
||||
- [/en/learn/llm-connections](/en/learn/llm-connections)
|
||||
- [/en/learn/custom-llm](/en/learn/custom-llm)
|
||||
27
docs/en/ai/llms/index.mdx
Normal file
27
docs/en/ai/llms/index.mdx
Normal file
@@ -0,0 +1,27 @@
|
||||
---
|
||||
title: "LLMs: Concepts"
|
||||
description: "Model selection strategy, cost-quality tradeoffs, and reliability posture for CrewAI systems."
|
||||
icon: "microchip-ai"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## When to use advanced LLM configuration
|
||||
|
||||
- You need predictable quality, latency, and cost control.
|
||||
- You need model routing by task type.
|
||||
|
||||
## Core decisions
|
||||
|
||||
| Decision | Choose this when |
|
||||
|---|---|
|
||||
| Single model | Small systems with uniform task profile |
|
||||
| Routed models | Mixed workloads with different quality/cost needs |
|
||||
| Structured output | Automation pipelines and strict parsing needs |
|
||||
|
||||
## Canonical links
|
||||
|
||||
- Reference: [/en/ai/llms/reference](/en/ai/llms/reference)
|
||||
- Patterns: [/en/ai/llms/patterns](/en/ai/llms/patterns)
|
||||
- Troubleshooting: [/en/ai/llms/troubleshooting](/en/ai/llms/troubleshooting)
|
||||
- Examples: [/en/ai/llms/examples](/en/ai/llms/examples)
|
||||
- Existing docs: [/en/concepts/llms](/en/concepts/llms)
|
||||
17
docs/en/ai/llms/patterns.mdx
Normal file
17
docs/en/ai/llms/patterns.mdx
Normal file
@@ -0,0 +1,17 @@
|
||||
---
|
||||
title: "LLMs: Patterns"
|
||||
description: "Model routing, reliability defaults, and structured outputs for production AI workflows."
|
||||
icon: "diagram-project"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Patterns
|
||||
|
||||
1. Role-based model routing
|
||||
2. Reliability defaults (`timeout`, `max_retries`, low temperature)
|
||||
3. JSON-first outputs for machine consumption
|
||||
4. Responses API for multi-turn reasoning flows
|
||||
|
||||
## Reference
|
||||
|
||||
- [/en/concepts/llms#production-llm-patterns](/en/concepts/llms#production-llm-patterns)
|
||||
25
docs/en/ai/llms/reference.mdx
Normal file
25
docs/en/ai/llms/reference.mdx
Normal file
@@ -0,0 +1,25 @@
|
||||
---
|
||||
title: "LLMs: Reference"
|
||||
description: "Provider-agnostic LLM configuration reference for CrewAI projects."
|
||||
icon: "book"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Common parameters
|
||||
|
||||
- `model`
|
||||
- `temperature`
|
||||
- `max_tokens`
|
||||
- `timeout`
|
||||
- `max_retries`
|
||||
- `response_format`
|
||||
|
||||
## Contract guidance
|
||||
|
||||
- Set low temperature for extraction/classification.
|
||||
- Use structured outputs for downstream automation.
|
||||
- Set explicit timeout and retry policy for production.
|
||||
|
||||
## Canonical source
|
||||
|
||||
Primary API details live in [/en/concepts/llms](/en/concepts/llms).
|
||||
12
docs/en/ai/llms/troubleshooting.mdx
Normal file
12
docs/en/ai/llms/troubleshooting.mdx
Normal file
@@ -0,0 +1,12 @@
|
||||
---
|
||||
title: "LLMs: Troubleshooting"
|
||||
description: "Fix common model behavior failures: drift, latency spikes, malformed output, and cost overruns."
|
||||
icon: "circle-exclamation"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Common issues
|
||||
|
||||
- Malformed JSON: enforce `response_format` and validate at boundary.
|
||||
- Latency spikes: route heavy tasks to smaller models when acceptable.
|
||||
- Cost growth: add budget-aware model routing and truncation rules.
|
||||
11
docs/en/ai/memory/examples.mdx
Normal file
11
docs/en/ai/memory/examples.mdx
Normal file
@@ -0,0 +1,11 @@
|
||||
---
|
||||
title: "Memory: Examples"
|
||||
description: "Runnable examples for scoped storage and semantic retrieval in CrewAI."
|
||||
icon: "rocket-launch"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Example links
|
||||
|
||||
- [/en/concepts/memory](/en/concepts/memory)
|
||||
- [/en/learn/flowstate-chat-history](/en/learn/flowstate-chat-history)
|
||||
24
docs/en/ai/memory/index.mdx
Normal file
24
docs/en/ai/memory/index.mdx
Normal file
@@ -0,0 +1,24 @@
|
||||
---
|
||||
title: "Memory: Concepts"
|
||||
description: "Designing recall systems with scope boundaries and state-vs-memory separation."
|
||||
icon: "database"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## When to use memory
|
||||
|
||||
- You need semantic recall across runs.
|
||||
- You need long-term context outside immediate flow state.
|
||||
|
||||
## When to use state instead
|
||||
|
||||
- Data is only needed for current control flow.
|
||||
- Data must remain deterministic and explicit per step.
|
||||
|
||||
## Canonical links
|
||||
|
||||
- Reference: [/en/ai/memory/reference](/en/ai/memory/reference)
|
||||
- Patterns: [/en/ai/memory/patterns](/en/ai/memory/patterns)
|
||||
- Troubleshooting: [/en/ai/memory/troubleshooting](/en/ai/memory/troubleshooting)
|
||||
- Examples: [/en/ai/memory/examples](/en/ai/memory/examples)
|
||||
- Existing docs: [/en/concepts/memory](/en/concepts/memory)
|
||||
17
docs/en/ai/memory/patterns.mdx
Normal file
17
docs/en/ai/memory/patterns.mdx
Normal file
@@ -0,0 +1,17 @@
|
||||
---
|
||||
title: "Memory: Patterns"
|
||||
description: "Practical memory patterns for session recall, scoped retrieval, and hybrid flow-state designs."
|
||||
icon: "diagram-project"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Patterns
|
||||
|
||||
1. Session-scoped recall (`/chat/{session_id}`)
|
||||
2. Project-scoped knowledge (`/project/{project_id}`)
|
||||
3. Hybrid pattern: flow state for control, memory for long-tail context
|
||||
|
||||
## Reference
|
||||
|
||||
- [/en/learn/flowstate-chat-history](/en/learn/flowstate-chat-history)
|
||||
- [/en/guides/flows/mastering-flow-state](/en/guides/flows/mastering-flow-state)
|
||||
23
docs/en/ai/memory/reference.mdx
Normal file
23
docs/en/ai/memory/reference.mdx
Normal file
@@ -0,0 +1,23 @@
|
||||
---
|
||||
title: "Memory: Reference"
|
||||
description: "Reference for remember/recall contracts, scopes, and retrieval tuning."
|
||||
icon: "book"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## API surface
|
||||
|
||||
- `remember(content, scope=...)`
|
||||
- `recall(query, limit=...)`
|
||||
- `extract_memories(text)`
|
||||
- `scope(path)` and `subscope(name)`
|
||||
|
||||
## Scope rules
|
||||
|
||||
- use `/{entity_type}/{identifier}` paths
|
||||
- keep hierarchy shallow
|
||||
- isolate sessions by stable identifiers
|
||||
|
||||
## Canonical source
|
||||
|
||||
Primary API details live in [/en/concepts/memory](/en/concepts/memory).
|
||||
12
docs/en/ai/memory/troubleshooting.mdx
Normal file
12
docs/en/ai/memory/troubleshooting.mdx
Normal file
@@ -0,0 +1,12 @@
|
||||
---
|
||||
title: "Memory: Troubleshooting"
|
||||
description: "Diagnose poor recall quality, scope leakage, and stale memory retrieval."
|
||||
icon: "circle-exclamation"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Common issues
|
||||
|
||||
- Irrelevant recall: tighten scopes and query wording.
|
||||
- Missing recall: check scope path and recency weighting.
|
||||
- Scope leakage: avoid shared broad scopes for unrelated workflows.
|
||||
54
docs/en/ai/overview.mdx
Normal file
54
docs/en/ai/overview.mdx
Normal file
@@ -0,0 +1,54 @@
|
||||
---
|
||||
title: "AI-First Documentation"
|
||||
description: "Canonical, agent-optimized documentation map for Flows, Agents, Crews, LLMs, Memory, and Tools."
|
||||
icon: "sitemap"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Purpose
|
||||
|
||||
This section is the canonical map for AI agents and developers.
|
||||
|
||||
Use it when you need:
|
||||
- one source of truth per domain
|
||||
- predictable page structure
|
||||
- runnable patterns with explicit inputs and outputs
|
||||
|
||||
## Domain Packs
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Flows" icon="arrow-progress" href="/en/ai/flows/index">
|
||||
State, routing, persistence, resume, and orchestration lifecycle.
|
||||
</Card>
|
||||
<Card title="Agents" icon="user" href="/en/ai/agents/index">
|
||||
Agent contracts, tool boundaries, prompt roles, and output discipline.
|
||||
</Card>
|
||||
<Card title="Crews" icon="users" href="/en/ai/crews/index">
|
||||
Multi-agent execution, process choice, delegation, and coordination.
|
||||
</Card>
|
||||
<Card title="LLMs" icon="microchip-ai" href="/en/ai/llms/index">
|
||||
Model configuration contracts, routing, reliability defaults, and providers.
|
||||
</Card>
|
||||
<Card title="Memory" icon="database" href="/en/ai/memory/index">
|
||||
Retrieval semantics, scope design, and state-vs-memory architecture.
|
||||
</Card>
|
||||
<Card title="Tools" icon="wrench" href="/en/ai/tools/index">
|
||||
Tool safety, schema contracts, retries, and integration patterns.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## Writing Contract
|
||||
|
||||
Every domain follows the same structure:
|
||||
1. Concepts (`index`)
|
||||
2. Reference (`reference`)
|
||||
3. Patterns (`patterns`)
|
||||
4. Troubleshooting (`troubleshooting`)
|
||||
5. Examples (`examples`)
|
||||
|
||||
## Deprecation Policy
|
||||
|
||||
When a page is replaced:
|
||||
- keep a redirect for the old URL
|
||||
- keep one canonical destination
|
||||
- avoid duplicated conceptual prose
|
||||
12
docs/en/ai/tools/examples.mdx
Normal file
12
docs/en/ai/tools/examples.mdx
Normal file
@@ -0,0 +1,12 @@
|
||||
---
|
||||
title: "Tools: Examples"
|
||||
description: "Practical examples for tool-driven agents and crews."
|
||||
icon: "rocket-launch"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Example links
|
||||
|
||||
- [/en/tools/overview](/en/tools/overview)
|
||||
- [/en/learn/create-custom-tools](/en/learn/create-custom-tools)
|
||||
- [/en/learn/tool-hooks](/en/learn/tool-hooks)
|
||||
25
docs/en/ai/tools/index.mdx
Normal file
25
docs/en/ai/tools/index.mdx
Normal file
@@ -0,0 +1,25 @@
|
||||
---
|
||||
title: "Tools: Concepts"
|
||||
description: "Tool selection strategy, safety boundaries, and reliability rules for agentic execution."
|
||||
icon: "wrench"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## When to use tools
|
||||
|
||||
- Agents need external data or side effects.
|
||||
- Deterministic systems must be integrated into agent workflows.
|
||||
|
||||
## Tool safety rules
|
||||
|
||||
- define clear input schemas
|
||||
- validate outputs before downstream use
|
||||
- isolate privileged tools behind policy checks
|
||||
|
||||
## Canonical links
|
||||
|
||||
- Reference: [/en/ai/tools/reference](/en/ai/tools/reference)
|
||||
- Patterns: [/en/ai/tools/patterns](/en/ai/tools/patterns)
|
||||
- Troubleshooting: [/en/ai/tools/troubleshooting](/en/ai/tools/troubleshooting)
|
||||
- Examples: [/en/ai/tools/examples](/en/ai/tools/examples)
|
||||
- Existing docs: [/en/concepts/tools](/en/concepts/tools)
|
||||
12
docs/en/ai/tools/patterns.mdx
Normal file
12
docs/en/ai/tools/patterns.mdx
Normal file
@@ -0,0 +1,12 @@
|
||||
---
|
||||
title: "Tools: Patterns"
|
||||
description: "Tool execution patterns for retrieval, action safety, and response grounding."
|
||||
icon: "diagram-project"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Patterns
|
||||
|
||||
1. Read-first then write pattern
|
||||
2. Validation gate before side effects
|
||||
3. Fallback tool chains for degraded mode
|
||||
22
docs/en/ai/tools/reference.mdx
Normal file
22
docs/en/ai/tools/reference.mdx
Normal file
@@ -0,0 +1,22 @@
|
||||
---
|
||||
title: "Tools: Reference"
|
||||
description: "Reference for tool invocation contracts, argument schemas, and runtime safeguards."
|
||||
icon: "book"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Tool contract
|
||||
|
||||
- deterministic input schema
|
||||
- stable output schema
|
||||
- explicit error behavior
|
||||
|
||||
## Runtime safeguards
|
||||
|
||||
- timeout and retry policy
|
||||
- idempotency for side effects
|
||||
- validation before commit
|
||||
|
||||
## Canonical source
|
||||
|
||||
Primary API details live in [/en/concepts/tools](/en/concepts/tools).
|
||||
12
docs/en/ai/tools/troubleshooting.mdx
Normal file
12
docs/en/ai/tools/troubleshooting.mdx
Normal file
@@ -0,0 +1,12 @@
|
||||
---
|
||||
title: "Tools: Troubleshooting"
|
||||
description: "Common tool-call failures and fixes for schema mismatch, retries, and side effects."
|
||||
icon: "circle-exclamation"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Common issues
|
||||
|
||||
- Schema mismatch: align tool args with declared model output schema.
|
||||
- Repeated side effects: add idempotency keys.
|
||||
- Tool timeouts: define retries with bounded backoff.
|
||||
@@ -21,80 +21,106 @@ Flows allow you to create structured, event-driven workflows. They provide a sea
|
||||
|
||||
## Getting Started
|
||||
|
||||
Let's create a simple Flow where you will use OpenAI to generate a random city in one task and then use that city to generate a fun fact in another task.
|
||||
The example below shows a realistic Flow for support-ticket triage. It demonstrates features teams use in production: typed state, routing, memory access, and persistence.
|
||||
|
||||
```python Code
|
||||
|
||||
from crewai.flow.flow import Flow, listen, start
|
||||
from dotenv import load_dotenv
|
||||
from litellm import completion
|
||||
from crewai.flow.flow import Flow, listen, router, start
|
||||
from crewai.flow.persistence import persist
|
||||
from pydantic import BaseModel, Field
|
||||
|
||||
|
||||
class ExampleFlow(Flow):
|
||||
model = "gpt-4o-mini"
|
||||
class SupportTriageState(BaseModel):
|
||||
ticket_id: str = ""
|
||||
customer_tier: str = "standard" # standard | enterprise
|
||||
issue: str = ""
|
||||
urgency: str = "normal"
|
||||
route: str = ""
|
||||
draft_reply: str = ""
|
||||
internal_notes: list[str] = Field(default_factory=list)
|
||||
|
||||
|
||||
@persist()
|
||||
class SupportTriageFlow(Flow[SupportTriageState]):
|
||||
@start()
|
||||
def generate_city(self):
|
||||
print("Starting flow")
|
||||
# Each flow state automatically gets a unique ID
|
||||
print(f"Flow State ID: {self.state['id']}")
|
||||
def ingest_ticket(self):
|
||||
# kickoff(inputs={...}) is merged into typed state fields
|
||||
print(f"Flow State ID: {self.state.id}")
|
||||
|
||||
response = completion(
|
||||
model=self.model,
|
||||
messages=[
|
||||
{
|
||||
"role": "user",
|
||||
"content": "Return the name of a random city in the world.",
|
||||
},
|
||||
],
|
||||
self.remember(
|
||||
f"Ticket {self.state.ticket_id}: {self.state.issue}",
|
||||
scope=f"/support/{self.state.ticket_id}",
|
||||
)
|
||||
|
||||
random_city = response["choices"][0]["message"]["content"]
|
||||
# Store the city in our state
|
||||
self.state["city"] = random_city
|
||||
print(f"Random City: {random_city}")
|
||||
issue = self.state.issue.lower()
|
||||
if "security" in issue or "breach" in issue:
|
||||
self.state.urgency = "critical"
|
||||
elif self.state.customer_tier == "enterprise":
|
||||
self.state.urgency = "high"
|
||||
else:
|
||||
self.state.urgency = "normal"
|
||||
|
||||
return random_city
|
||||
return self.state.issue
|
||||
|
||||
@listen(generate_city)
|
||||
def generate_fun_fact(self, random_city):
|
||||
response = completion(
|
||||
model=self.model,
|
||||
messages=[
|
||||
{
|
||||
"role": "user",
|
||||
"content": f"Tell me a fun fact about {random_city}",
|
||||
},
|
||||
],
|
||||
@router(ingest_ticket)
|
||||
def route_ticket(self):
|
||||
issue = self.state.issue.lower()
|
||||
if "security" in issue or "breach" in issue:
|
||||
self.state.route = "security"
|
||||
return "security_review"
|
||||
if self.state.customer_tier == "enterprise" or self.state.urgency == "high":
|
||||
self.state.route = "priority"
|
||||
return "priority_queue"
|
||||
self.state.route = "standard"
|
||||
return "standard_queue"
|
||||
|
||||
@listen("security_review")
|
||||
def handle_security(self):
|
||||
self.state.internal_notes.append("Escalated to Security Incident Response")
|
||||
self.state.draft_reply = (
|
||||
"We have escalated your case to our security team and will update you shortly."
|
||||
)
|
||||
return self.state.draft_reply
|
||||
|
||||
fun_fact = response["choices"][0]["message"]["content"]
|
||||
# Store the fun fact in our state
|
||||
self.state["fun_fact"] = fun_fact
|
||||
return fun_fact
|
||||
@listen("priority_queue")
|
||||
def handle_priority(self):
|
||||
history = self.recall("SLA commitments for enterprise support", limit=2)
|
||||
self.state.internal_notes.append(
|
||||
f"Loaded {len(history)} memory hits for priority handling"
|
||||
)
|
||||
self.state.draft_reply = (
|
||||
"Your ticket has been prioritized and assigned to a senior support engineer."
|
||||
)
|
||||
return self.state.draft_reply
|
||||
|
||||
@listen("standard_queue")
|
||||
def handle_standard(self):
|
||||
self.state.internal_notes.append("Routed to standard support queue")
|
||||
self.state.draft_reply = "Thanks for reporting this. Our team will follow up soon."
|
||||
return self.state.draft_reply
|
||||
|
||||
|
||||
|
||||
flow = ExampleFlow()
|
||||
flow.plot()
|
||||
result = flow.kickoff()
|
||||
|
||||
print(f"Generated fun fact: {result}")
|
||||
flow = SupportTriageFlow()
|
||||
flow.plot("support_triage_flow")
|
||||
result = flow.kickoff(
|
||||
inputs={
|
||||
"ticket_id": "TCK-1024",
|
||||
"customer_tier": "enterprise",
|
||||
"issue": "Cannot access SSO after enabling new policy",
|
||||
}
|
||||
)
|
||||
print("Final reply:", result)
|
||||
print("Route:", flow.state.route)
|
||||
print("Notes:", flow.state.internal_notes)
|
||||
```
|
||||
|
||||
In the above example, we have created a simple Flow that generates a random city using OpenAI and then generates a fun fact about that city. The Flow consists of two tasks: `generate_city` and `generate_fun_fact`. The `generate_city` task is the starting point of the Flow, and the `generate_fun_fact` task listens for the output of the `generate_city` task.
|
||||
In this example, one flow demonstrates several core features together:
|
||||
1. `@start()` initializes and normalizes state for downstream steps.
|
||||
2. `@router()` performs deterministic branching into labeled routes.
|
||||
3. Route listeners implement lane-specific behavior (`security`, `priority`, `standard`).
|
||||
4. `@persist()` keeps the flow state recoverable between runs.
|
||||
5. Built-in memory methods (`remember`, `recall`) add durable context beyond a single method call.
|
||||
|
||||
Each Flow instance automatically receives a unique identifier (UUID) in its state, which helps track and manage flow executions. The state can also store additional data (like the generated city and fun fact) that persists throughout the flow's execution.
|
||||
|
||||
When you run the Flow, it will:
|
||||
1. Generate a unique ID for the flow state
|
||||
2. Generate a random city and store it in the state
|
||||
3. Generate a fun fact about that city and store it in the state
|
||||
4. Print the results to the console
|
||||
|
||||
The state's unique ID and stored data can be useful for tracking flow executions and maintaining context between tasks.
|
||||
|
||||
**Note:** Ensure you have set up your `.env` file to store your `OPENAI_API_KEY`. This key is necessary for authenticating requests to the OpenAI API.
|
||||
This pattern mirrors typical production workflows where request classification, policy-aware routing, and auditable state all happen in one orchestrated flow.
|
||||
|
||||
### @start()
|
||||
|
||||
@@ -117,15 +143,15 @@ The `@listen()` decorator can be used in several ways:
|
||||
1. **Listening to a Method by Name**: You can pass the name of the method you want to listen to as a string. When that method completes, the listener method will be triggered.
|
||||
|
||||
```python Code
|
||||
@listen("generate_city")
|
||||
def generate_fun_fact(self, random_city):
|
||||
@listen("upstream_method")
|
||||
def downstream_method(self, upstream_result):
|
||||
# Implementation
|
||||
```
|
||||
|
||||
2. **Listening to a Method Directly**: You can pass the method itself. When that method completes, the listener method will be triggered.
|
||||
```python Code
|
||||
@listen(generate_city)
|
||||
def generate_fun_fact(self, random_city):
|
||||
@listen(upstream_method)
|
||||
def downstream_method(self, upstream_result):
|
||||
# Implementation
|
||||
```
|
||||
|
||||
|
||||
@@ -106,6 +106,102 @@ There are different places in CrewAI code where you can specify the model to use
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Production LLM Patterns
|
||||
|
||||
The basics above show how to configure one model. In real systems, you usually combine several LLM patterns for cost, quality, and reliability.
|
||||
|
||||
### Pattern 1: Route models by agent role
|
||||
|
||||
Use faster/cheaper models for extraction and heavier models for synthesis or critical decisions.
|
||||
|
||||
```python Code
|
||||
from crewai import Agent, Crew, Process, Task
|
||||
|
||||
researcher = Agent(
|
||||
role="Researcher",
|
||||
goal="Collect factual inputs quickly",
|
||||
backstory="Fast information-gathering specialist",
|
||||
llm="openai/gpt-4o-mini",
|
||||
)
|
||||
|
||||
reviewer = Agent(
|
||||
role="Reviewer",
|
||||
goal="Validate claims and produce final answer",
|
||||
backstory="Careful editor focused on correctness",
|
||||
llm="provider/model-id",
|
||||
)
|
||||
|
||||
crew = Crew(
|
||||
agents=[researcher, reviewer],
|
||||
tasks=[
|
||||
Task(
|
||||
description="Find the latest policy changes and list the key points",
|
||||
expected_output="Bullet list of validated policy changes",
|
||||
agent=researcher,
|
||||
),
|
||||
Task(
|
||||
description="Review findings and produce a final executive summary",
|
||||
expected_output="Concise, decision-ready summary",
|
||||
agent=reviewer,
|
||||
),
|
||||
],
|
||||
process=Process.sequential,
|
||||
)
|
||||
```
|
||||
|
||||
### Pattern 2: Set reliability defaults once
|
||||
|
||||
Configure retry, timeout, and deterministic sampling in one reusable `LLM` object.
|
||||
|
||||
```python Code
|
||||
from crewai import LLM
|
||||
|
||||
reliable_llm = LLM(
|
||||
model="openai/gpt-4o-mini",
|
||||
temperature=0.1,
|
||||
timeout=45,
|
||||
max_retries=3,
|
||||
max_tokens=1200,
|
||||
seed=7,
|
||||
)
|
||||
```
|
||||
|
||||
Use this for extraction, classification, and policy-sensitive tasks where variance should be low.
|
||||
|
||||
### Pattern 3: Use structured outputs for machine-readable responses
|
||||
|
||||
For downstream automation, force JSON-shaped outputs rather than free-form prose.
|
||||
|
||||
```python Code
|
||||
from crewai import LLM
|
||||
|
||||
json_llm = LLM(
|
||||
model="openai/gpt-4o",
|
||||
response_format={"type": "json"},
|
||||
temperature=0.0,
|
||||
)
|
||||
```
|
||||
|
||||
This reduces parser fragility in pipelines that feed APIs, databases, or workflow routers.
|
||||
|
||||
### Pattern 4: Use OpenAI Responses API for multi-turn reasoning flows
|
||||
|
||||
When you need built-in tools, response chaining, or reasoning-model workflows, enable the Responses API explicitly.
|
||||
|
||||
```python Code
|
||||
from crewai import LLM
|
||||
|
||||
reasoning_llm = LLM(
|
||||
model="openai/o4-mini",
|
||||
api="responses",
|
||||
auto_chain=True,
|
||||
store=True,
|
||||
reasoning_effort="medium",
|
||||
)
|
||||
```
|
||||
|
||||
This is especially useful in long-running assistants where you want conversation continuity and controllable reasoning depth.
|
||||
|
||||
## Provider Configuration Examples
|
||||
|
||||
CrewAI supports a multitude of LLM providers, each offering unique features, authentication methods, and model capabilities.
|
||||
|
||||
@@ -156,6 +156,7 @@ class ResearchFlow(Flow):
|
||||
```
|
||||
|
||||
See the [Flows documentation](/concepts/flows) for more on memory in Flows.
|
||||
For a production-style conversational pattern that combines Flow state and memory, see [Flowstate Chat History](/en/learn/flowstate-chat-history).
|
||||
|
||||
|
||||
## Hierarchical Scopes
|
||||
|
||||
@@ -8,6 +8,10 @@ mode: "wide"
|
||||
## Quickstarts & Demos
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Flowstate Chat History" icon="comments" href="/en/learn/flowstate-chat-history">
|
||||
Manage chat sessions with sliding-window history, summary compaction, and persisted Flow state.
|
||||
</Card>
|
||||
|
||||
<Card title="Collaboration" icon="people-arrows" href="https://github.com/crewAIInc/crewAI-quickstarts/blob/main/Collaboration/crewai_collaboration.ipynb">
|
||||
Coordinate multiple agents on shared tasks. Includes notebook with end-to-end collaboration pattern.
|
||||
</Card>
|
||||
|
||||
@@ -34,6 +34,10 @@ mode: "wide"
|
||||
## Flows
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Flowstate Chat History" icon="comments" href="/en/learn/flowstate-chat-history">
|
||||
Stateful chat pattern with compacted context and persisted session state.
|
||||
</Card>
|
||||
|
||||
<Card title="Content Creator Flow" icon="pen" href="https://github.com/crewAIInc/crewAI-examples/tree/main/flows/content_creator_flow">
|
||||
Multi‑crew content generation with routing.
|
||||
</Card>
|
||||
|
||||
@@ -47,6 +47,23 @@ CrewAI offers two ways to manage state in your flows:
|
||||
|
||||
Let's examine each approach in detail.
|
||||
|
||||
### Flow State vs Memory: When to use each
|
||||
|
||||
Both features keep context, but they solve different problems.
|
||||
|
||||
| Dimension | Flow State (`self.state`) | Memory (`self.remember` / `self.recall`) |
|
||||
|---|---|---|
|
||||
| Primary purpose | Track execution and deterministic workflow data | Store and retrieve semantic knowledge across interactions |
|
||||
| Data shape | Explicit fields (dict/Pydantic model) | Text records with inferred scopes and ranked recall |
|
||||
| Typical lifetime | Current flow run (or persisted checkpoints) | Long-term knowledge over many runs |
|
||||
| Access pattern | Direct reads/writes (`self.state.field`) | Query-based retrieval (`self.recall("...")`) |
|
||||
| Best for | Routing flags, counters, intermediate outputs, chat window | Durable facts, prior outcomes, reusable context |
|
||||
| Chat use | Recent turns + running summary + control flags | Long-tail memory outside context window |
|
||||
|
||||
Practical rule:
|
||||
- Use **state** for what your control flow depends on right now.
|
||||
- Use **memory** for what you may want to retrieve later by meaning.
|
||||
|
||||
## Unstructured State Management
|
||||
|
||||
Unstructured state uses a dictionary-like approach, offering flexibility and simplicity for straightforward applications.
|
||||
|
||||
@@ -27,8 +27,11 @@ mode: "wide"
|
||||
</div>
|
||||
|
||||
<div style={{ display: 'flex', flexWrap: 'wrap', gap: 12, justifyContent: 'center' }}>
|
||||
<a className="button button-primary" href="/en/quickstart">Get started</a>
|
||||
<a className="button" href="/en/changelog">View changelog</a>
|
||||
<a className="button button-primary" href="/en/installation">Install</a>
|
||||
<a className="button" href="/en/quickstart">Quickstart</a>
|
||||
<a className="button" href="/en/guides/crews/first-crew">First Crew</a>
|
||||
<a className="button" href="/en/guides/flows/first-flow">First Flow</a>
|
||||
<a className="button" href="/en/concepts/llms">LLM Setup</a>
|
||||
<a className="button" href="/en/api-reference/introduction">API Reference</a>
|
||||
</div>
|
||||
|
||||
@@ -36,17 +39,49 @@ mode: "wide"
|
||||
|
||||
<div style={{ marginTop: 32 }} />
|
||||
|
||||
## Get started
|
||||
## Start in 3 steps
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Introduction" href="/en/introduction" icon="sparkles">
|
||||
Overview of CrewAI concepts, architecture, and what you can build with agents, crews, and flows.
|
||||
</Card>
|
||||
<Card title="Installation" href="/en/installation" icon="wrench">
|
||||
<Card title="1) Install" href="/en/installation" icon="wrench">
|
||||
Install via `uv`, configure API keys, and set up the CLI for local development.
|
||||
</Card>
|
||||
<Card title="Quickstart" href="/en/quickstart" icon="rocket">
|
||||
Spin up your first crew in minutes. Learn the core runtime, project layout, and dev loop.
|
||||
<Card title="2) Run Quickstart" href="/en/quickstart" icon="rocket">
|
||||
Launch your first working crew with a minimal project and iterate from there.
|
||||
</Card>
|
||||
<Card title="3) Pick a path" href="/en/ai/overview" icon="sitemap">
|
||||
Continue with canonical domain packs for Flows, Agents, Crews, LLMs, Memory, and Tools.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## Most-used pages
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="First Crew" href="/en/guides/crews/first-crew" icon="users">
|
||||
Build a production-style crew with role/task configuration and execution flow.
|
||||
</Card>
|
||||
<Card title="First Flow" href="/en/guides/flows/first-flow" icon="arrow-progress">
|
||||
Build event-driven orchestration with state, listeners, and routing.
|
||||
</Card>
|
||||
<Card title="Flowstate Chat History" href="/en/learn/flowstate-chat-history" icon="comments">
|
||||
Stateful chat history pattern with persistence and summary compaction.
|
||||
</Card>
|
||||
<Card title="Agents" href="/en/concepts/agents" icon="user">
|
||||
Agent role design, tool boundaries, and output contracts.
|
||||
</Card>
|
||||
<Card title="Crews" href="/en/concepts/crews" icon="users-gear">
|
||||
Multi-agent collaboration patterns and process semantics.
|
||||
</Card>
|
||||
<Card title="Flows" href="/en/concepts/flows" icon="code-branch">
|
||||
Deterministic orchestration, state lifecycle, persistence, and resume.
|
||||
</Card>
|
||||
<Card title="LLMs" href="/en/concepts/llms" icon="microchip-ai">
|
||||
Model setup, provider config, routing patterns, and reliability defaults.
|
||||
</Card>
|
||||
<Card title="Memory" href="/en/concepts/memory" icon="database">
|
||||
Semantic recall, scope strategy, and state-vs-memory architecture.
|
||||
</Card>
|
||||
<Card title="Tools" href="/en/tools/overview" icon="wrench">
|
||||
Tool categories, integration surfaces, and practical usage patterns.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@@ -90,7 +125,11 @@ mode: "wide"
|
||||
</CardGroup>
|
||||
|
||||
<Callout title="Explore real-world patterns" icon="github">
|
||||
Browse the <a href="/en/examples/cookbooks">examples and cookbooks</a> for end-to-end reference implementations across agents, flows, and enterprise automations.
|
||||
Browse the <a href="/en/examples/cookbooks">examples and cookbooks</a> for end-to-end reference implementations across agents, flows, and enterprise automations. For a practical conversational pattern, start with <a href="/en/learn/flowstate-chat-history">Flowstate Chat History</a>.
|
||||
</Callout>
|
||||
|
||||
<Callout title="AI-First Docs" icon="sitemap">
|
||||
Use the <a href="/en/ai/overview">AI-First Documentation map</a> for canonical domain packs across Flows, Agents, Crews, LLMs, Memory, and Tools.
|
||||
</Callout>
|
||||
|
||||
## Stay connected
|
||||
|
||||
@@ -16,6 +16,52 @@ It empowers developers to build production-ready multi-agent systems by combinin
|
||||
|
||||
With over 100,000 developers certified through our community courses, CrewAI is the standard for enterprise-ready AI automation.
|
||||
|
||||
## Start Here
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Install" href="/en/installation" icon="wrench">
|
||||
Set up CrewAI, configure API keys, and prepare your local environment.
|
||||
</Card>
|
||||
<Card title="Quickstart" href="/en/quickstart" icon="rocket">
|
||||
Run your first working crew with a minimal setup.
|
||||
</Card>
|
||||
<Card title="First Crew" href="/en/guides/crews/first-crew" icon="users-gear">
|
||||
Build a production-style crew with roles, tasks, and execution flow.
|
||||
</Card>
|
||||
<Card title="First Flow" href="/en/guides/flows/first-flow" icon="arrow-progress">
|
||||
Build event-driven orchestration with state, listeners, and routers.
|
||||
</Card>
|
||||
<Card title="LLM Setup" href="/en/concepts/llms" icon="microchip-ai">
|
||||
Configure providers, models, and reliability defaults.
|
||||
</Card>
|
||||
<Card title="API Reference" href="/en/api-reference/introduction" icon="book">
|
||||
Use kickoff, resume, and status endpoints for production integrations.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## Most-used Docs
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Agents" href="/en/concepts/agents" icon="user">
|
||||
Role design, tool boundaries, and output contracts.
|
||||
</Card>
|
||||
<Card title="Crews" href="/en/concepts/crews" icon="users">
|
||||
Multi-agent coordination and process choices.
|
||||
</Card>
|
||||
<Card title="Flows" href="/en/concepts/flows" icon="code-branch">
|
||||
Deterministic orchestration, state, persistence, and resume.
|
||||
</Card>
|
||||
<Card title="Memory" href="/en/concepts/memory" icon="database">
|
||||
Scope strategy and semantic recall across runs.
|
||||
</Card>
|
||||
<Card title="Flowstate Chat History" href="/en/learn/flowstate-chat-history" icon="comments">
|
||||
Stateful chat context with summary compaction and persistence.
|
||||
</Card>
|
||||
<Card title="AI-First Docs Map" href="/en/ai/overview" icon="sitemap">
|
||||
Canonical domain packs for Flows, Agents, Crews, LLMs, Memory, and Tools.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## The CrewAI Architecture
|
||||
|
||||
CrewAI's architecture is designed to balance autonomy with control.
|
||||
@@ -130,7 +176,7 @@ For any production-ready application, **start with a Flow**.
|
||||
<Card
|
||||
title="Quick Start"
|
||||
icon="bolt"
|
||||
href="en/quickstart"
|
||||
href="/en/quickstart"
|
||||
>
|
||||
Follow our quickstart guide to create your first CrewAI agent and get hands-on experience.
|
||||
</Card>
|
||||
|
||||
167
docs/en/learn/flowstate-chat-history.mdx
Normal file
167
docs/en/learn/flowstate-chat-history.mdx
Normal file
@@ -0,0 +1,167 @@
|
||||
---
|
||||
title: "Flowstate Chat History"
|
||||
description: "Build a stateful chat workflow that keeps context compact, persistent, and production-friendly."
|
||||
icon: "comments"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
This guide shows a practical pattern for managing LLM chat history with Flow state:
|
||||
|
||||
- Keep recent turns in a sliding window
|
||||
- Summarize older turns into a compact running summary
|
||||
- Persist state automatically with `@persist()`
|
||||
- Keep optional long-term recall using Flow memory
|
||||
|
||||
## Why this pattern works
|
||||
|
||||
Naively appending every message to prompts causes token bloat and unstable behavior over long sessions. A better approach is:
|
||||
|
||||
1. Keep only the most recent turns in `state.messages`
|
||||
2. Move older turns into `state.running_summary`
|
||||
3. Build prompts from `running_summary + recent messages`
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. CrewAI installed and configured
|
||||
2. API key configured for your model provider
|
||||
3. Basic familiarity with Flow decorators (`@start`, `@listen`)
|
||||
|
||||
## Step 1: Define typed chat state
|
||||
|
||||
```python Code
|
||||
from typing import Dict, List
|
||||
from pydantic import BaseModel, Field
|
||||
|
||||
|
||||
class ChatSessionState(BaseModel):
|
||||
session_id: str = "demo-session"
|
||||
running_summary: str = ""
|
||||
messages: List[Dict[str, str]] = Field(default_factory=list)
|
||||
max_recent_messages: int = 8
|
||||
last_user_message: str = ""
|
||||
assistant_reply: str = ""
|
||||
turn_count: int = 0
|
||||
```
|
||||
|
||||
## Step 2: Build the Flow
|
||||
|
||||
```python Code
|
||||
from crewai.flow.flow import Flow, start, listen
|
||||
from crewai.flow.persistence import persist
|
||||
from litellm import completion
|
||||
|
||||
|
||||
@persist()
|
||||
class ChatHistoryFlow(Flow[ChatSessionState]):
|
||||
model = "gpt-4o-mini"
|
||||
|
||||
@start()
|
||||
def capture_user_message(self):
|
||||
self.state.last_user_message = self.state.last_user_message.strip()
|
||||
self.state.messages.append(
|
||||
{"role": "user", "content": self.state.last_user_message}
|
||||
)
|
||||
self.state.turn_count += 1
|
||||
return self.state.last_user_message
|
||||
|
||||
@listen(capture_user_message)
|
||||
def compact_old_history(self, _):
|
||||
if len(self.state.messages) <= self.state.max_recent_messages:
|
||||
return "no_compaction"
|
||||
|
||||
overflow = self.state.messages[:-self.state.max_recent_messages]
|
||||
self.state.messages = self.state.messages[-self.state.max_recent_messages :]
|
||||
overflow_text = "\n".join(
|
||||
f"{m['role']}: {m['content']}" for m in overflow
|
||||
)
|
||||
|
||||
summary_prompt = [
|
||||
{
|
||||
"role": "system",
|
||||
"content": "Summarize old chat turns into short bullet points. Preserve facts, constraints, and decisions.",
|
||||
},
|
||||
{
|
||||
"role": "user",
|
||||
"content": (
|
||||
f"Existing summary:\n{self.state.running_summary or '(empty)'}\n\n"
|
||||
f"New old turns:\n{overflow_text}"
|
||||
),
|
||||
},
|
||||
]
|
||||
summary_response = completion(model=self.model, messages=summary_prompt)
|
||||
self.state.running_summary = summary_response["choices"][0]["message"]["content"]
|
||||
return "compacted"
|
||||
|
||||
@listen(compact_old_history)
|
||||
def generate_reply(self, _):
|
||||
system_context = (
|
||||
"You are a helpful assistant.\n"
|
||||
f"Conversation summary so far:\n{self.state.running_summary or '(none)'}"
|
||||
)
|
||||
|
||||
response = completion(
|
||||
model=self.model,
|
||||
messages=[{"role": "system", "content": system_context}, *self.state.messages],
|
||||
)
|
||||
answer = response["choices"][0]["message"]["content"]
|
||||
|
||||
self.state.assistant_reply = answer
|
||||
self.state.messages.append({"role": "assistant", "content": answer})
|
||||
|
||||
# Optional: store key turns in long-term memory for later recall
|
||||
self.remember(
|
||||
f"Session {self.state.session_id} turn {self.state.turn_count}: "
|
||||
f"user={self.state.last_user_message} assistant={answer}",
|
||||
scope=f"/chat/{self.state.session_id}",
|
||||
)
|
||||
return answer
|
||||
```
|
||||
|
||||
## Step 3: Run it
|
||||
|
||||
```python Code
|
||||
flow = ChatHistoryFlow()
|
||||
|
||||
first = flow.kickoff(
|
||||
inputs={
|
||||
"session_id": "customer-42",
|
||||
"last_user_message": "I need help choosing a pricing plan for a 10-person team.",
|
||||
}
|
||||
)
|
||||
print("Assistant:", first)
|
||||
|
||||
second = flow.kickoff(
|
||||
inputs={
|
||||
"last_user_message": "We also need SSO and audit logs. What do you recommend now?",
|
||||
}
|
||||
)
|
||||
print("Assistant:", second)
|
||||
print("Turns:", flow.state.turn_count)
|
||||
print("Recent messages:", len(flow.state.messages))
|
||||
```
|
||||
|
||||
## Expected output (shape)
|
||||
|
||||
```text Output
|
||||
Assistant: ...initial recommendation...
|
||||
Assistant: ...updated recommendation with SSO and audit-log requirements...
|
||||
Turns: 2
|
||||
Recent messages: 4
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- If replies ignore earlier context:
|
||||
increase `max_recent_messages` and ensure `running_summary` is included in the system context.
|
||||
- If prompts become too large:
|
||||
lower `max_recent_messages` and summarize more aggressively.
|
||||
- If sessions collide:
|
||||
provide a stable `session_id` and isolate memory scope with `/chat/{session_id}`.
|
||||
|
||||
## Next steps
|
||||
|
||||
- Add tool calls for account lookup or product catalog retrieval
|
||||
- Route to human review for high-risk decisions
|
||||
- Add structured output to capture recommendations in machine-readable JSON
|
||||
Reference in New Issue
Block a user