docs: add security best practices guide for CrewAI agents

docs/docs.json

@@ -138,7 +138,8 @@
                         "icon": "gear",
                         "pages": [
                           "edge/en/guides/advanced/customizing-prompts",
-                          "edge/en/guides/advanced/fingerprinting"
+                          "edge/en/guides/advanced/fingerprinting",
+                          "edge/en/guides/advanced/security-best-practices"
                         ]
                       },
                       {

docs/edge/en/guides/advanced/security-best-practices.mdx

@@ -0,0 +1,154 @@
+---
+title: Security Best Practices for CrewAI Agents
+description: Practical guidance for configuring CrewAI agents and crews safely in production.
+icon: shield
+---
+
+## Overview
+
+This guide focuses on **CrewAI-native controls** you can use to reduce security risk in production systems.
+
+The goal is simple: keep agent behavior bounded, least-privileged, and reviewable.
+
+## 1) Bound execution to prevent runaway behavior
+
+Use execution limits on agents and crews so failures degrade predictably instead of spiraling.
+
+### Recommended controls
+
+- `max_rpm`: cap request rate to providers
+- `max_iter`: cap iterative reasoning/tool cycles
+- `max_execution_time`: hard timeout for long-running work
+
+```python
+from crewai import Agent
+
+analyst = Agent(
+    role="Security Analyst",
+    goal="Investigate and summarize incidents",
+    backstory="Careful and methodical",
+    max_rpm=30,
+    max_iter=12,
+    max_execution_time=180,
+)
+```
+
+## 2) Apply least privilege to tools
+
+Avoid giving every tool to every agent. Give each agent only the tools required for its task.
+
+### Why this matters
+
+- Reduces blast radius for prompt injection or logic errors
+- Prevents accidental access to unrelated systems
+- Improves traceability of who can do what
+
+```python
+from crewai import Agent
+from crewai.tools import FileReadTool, SerperDevTool
+
+researcher = Agent(
+    role="Researcher",
+    goal="Collect external facts",
+    backstory="Finds reliable sources",
+    tools=[SerperDevTool()],
+)
+
+auditor = Agent(
+    role="Document Auditor",
+    goal="Review internal policy documents",
+    backstory="Checks compliance language",
+    tools=[FileReadTool()],
+)
+```
+
+## 3) Treat delegation as a trust boundary
+
+When `allow_delegation=True`, an agent can route work to other agents. That can be useful, but it is also a security boundary.
+
+### Safe delegation patterns
+
+- Keep delegation disabled by default
+- Enable it only for roles that truly need orchestration
+- Pair delegation with clear task constraints and bounded execution
+
+```python
+from crewai import Agent
+
+coordinator = Agent(
+    role="Coordinator",
+    goal="Route specialized tasks",
+    backstory="Delegates carefully",
+    allow_delegation=True,
+    max_iter=8,
+)
+```
+
+## 4) Constrain outputs with schemas and expectations
+
+Use structured outputs whenever possible to reduce ambiguous or unsafe free-form responses.
+
+### Recommended controls
+
+- `output_pydantic` for schema-validated task output
+- `expected_output` to describe strict acceptance criteria
+
+```python
+from pydantic import BaseModel
+from crewai import Task
+
+class RiskSummary(BaseModel):
+    severity: str
+    findings: list[str]
+    recommendation: str
+
+security_task = Task(
+    description="Review tool configuration for least privilege",
+    expected_output="A structured risk summary with severity, findings, and recommendation.",
+    output_pydantic=RiskSummary,
+)
+```
+
+## 5) Add human oversight for high-stakes actions
+
+For sensitive operations (for example financial actions, production mutations, or customer-impacting changes), add explicit human approval before execution.
+
+### Common oversight checkpoints
+
+- Before running irreversible tools
+- Before external side effects (emails, tickets, writes)
+- Before policy/security exceptions
+
+CrewAI supports human approval at the task layer with `human_input=True`, which is a good fit for sensitive steps that should pause for review before completion.
+
+```python
+from crewai import Task
+
+sensitive_task = Task(
+    description="Execute production database migration",
+    expected_output="Migration result confirmation",
+    human_input=True,
+)
+```
+
+For reviewability after the fact, consider enabling `verbose=True` on agents involved in sensitive flows so execution details are easier to inspect during debugging and incident review.
+
+## Operational checklist
+
+Use this quick checklist before production rollout:
+
+- [ ] Every agent has bounded execution (`max_rpm`, `max_iter`, `max_execution_time`)
+- [ ] Tool access is scoped per role (no broad shared tool list)
+- [ ] Delegation is disabled unless explicitly required
+- [ ] High-impact tasks use `output_pydantic` and precise `expected_output`
+- [ ] Human approval gates exist for sensitive actions
+- [ ] Agent runs are logged or traced for post-incident review
+
+## Related resources
+
+- [Agents](/en/concepts/agents)
+- [Tasks](/en/concepts/tasks)
+- [Flows](/en/concepts/flows)
+- [Human-in-the-loop](/en/learn/human-in-the-loop)
+- [Tool Hooks](/en/learn/tool-hooks)
+- [Tracing and observability](/en/observability/overview)