docs: add Secure Agent Design guide

[theCyberTech]

Adds a Secure Agent Design guide under Guides → Agents. The guide covers trusted vs untrusted input, prompt injection, tool abuse, output checks, approval gates, delegation limits, and agent isolation.

This page is the design and threat-model guide. Execution limits (max_rpm, max_iter, max_execution_time), verbosity, and agent settings stay on Agents and Customize Agents, so an Advanced config page can own those knobs without overlapping this guide.

HITL is approval, not a control. That warning lives in the overview and in section 6 only. Task human_input=True reviews the final answer after tools ran; it does not gate tool execution. Pre-execution blocking stays on tool hooks (HookAborted). This matches the human_input contract called out in #7096.

The isolation Flow example now stores validated OutreachNotes (response_format + result.pydantic) and passes only claims and sources to the sender. It does not dump result.raw.

The prose is simplified technical English: short sentences, defined terms, and no jargon such as “fail open” or “ACL”. The same APIs and execution-path limits remain.

Accuracy notes (matched to code):

• agent.kickoff() uses AgentExecutor / LiteAgentOutput. It does not create a Task or a Crew.
• Agent.guardrail runs on kickoff only. Task guardrails and human_input run on the Task path.
• Execution boundary hooks run on Crew and Flow only.
• @CrewBase @on hooks are added to the global hook list when the crew is created.
• HookAborted blocks that tool call. The run continues.
• If a tool hook raises any exception other than HookAborted, CrewAI ignores the error and the tool still runs.
• On the Task path, memory=False on an agent does not turn off crew memory.
• allow_delegation defaults to False. A2A trust_remote_completion_status defaults to False.

Also in this update:

• The first backstory example is labeled as a soft control.
• pt-BR concepts/agents.mdx now has the direct kickoff() section and the AgentExecutor / LiteAgentOutput note.

Locales: edge en, pt-BR, ko, and ar pages plus nav entries. Frozen docs/v*/ is unchanged.

Locale links to EN-only A2A and E2B pages keep the /en/... prefix so mint broken-links passes. The Arabic kickoff note now matches the English AgentExecutor behavior.

  

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
crewai	🟢 Ready	View Preview	Aug 4, 2026, 6:54 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Added a comprehensive Secure Agent Design guide. It covers trust boundaries, prompt injection, tool abuse, validation, approvals, delegation, and isolation. Related architecture, agent, MCP, and navigation pages now link to the guide.

Changes

Secure Agent Design documentation

Layer / File(s)	Summary
Security scope and trust boundaries docs/edge/en/guides/agents/secure-agent-design.mdx, docs/edge/en/concepts/agents.mdx	Defines security scope, threat areas, trust boundaries, input categories, secret handling, least privilege, input inspection, and the direct AgentExecutor implementation and LiteAgentOutput return value for kickoff().
Injection and tool-abuse controls docs/edge/en/guides/agents/secure-agent-design.mdx	Documents prompt injection, indirect injection, constrained tools, hooks, guardrails, structured handoffs, and tool-call allowlists.
Validation, approval, delegation, and isolation docs/edge/en/guides/agents/secure-agent-design.mdx	Adds guidance and examples for output validation, approval gates, delegation limits, and isolated research and action flows.
Guide navigation and cross-references docs/docs.json, docs/edge/en/concepts/production-architecture.mdx, docs/edge/en/guides/agents/crafting-effective-agents.mdx, docs/edge/en/mcp/security.mdx, docs/edge/en/guides/agents/secure-agent-design.mdx	Adds the guide to the Agents index and links it from related documentation pages.

Suggested reviewers: lorenzejay

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly and concisely identifies the main change: adding the Secure Agent Design guide.
Description check	✅ Passed	The description directly explains the new guide, its security topics, documentation scope, and related behavior changes.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch cursor/secure-agent-design-612d

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Copilot]

Pull request overview

Adds a new Edge documentation guide, Secure Agent Design, and wires it into navigation and related pages to serve as a production-focused security checklist for building tool-using agents in CrewAI.

Changes:

• Introduces a new Secure Agent Design guide covering trust boundaries, prompt injection, tool abuse controls, output validation, approval gates, delegation limits, and isolation patterns.
• Adds cross-links from existing production/security documentation to the new guide.
• Registers the new guide in docs/docs.json under Guides → Agents.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
docs/edge/en/mcp/security.mdx	Adds a “broader production checklist” link to Secure Agent Design.
docs/edge/en/guides/agents/secure-agent-design.mdx	New production security checklist guide with patterns and code examples.
docs/edge/en/guides/agents/crafting-effective-agents.mdx	Adds a tip linking to Secure Agent Design for production readers.
docs/edge/en/concepts/production-architecture.mdx	Adds a Security section and summary bullet linking to Secure Agent Design.
docs/docs.json	Adds the new guide to the Guides → Agents navigation group.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated no new comments.

Suppressed comments (1)

docs/edge/en/guides/agents/secure-agent-design.mdx:268

• The constrain_writes hook example is doing a very naive path check (only ".." and POSIX absolute paths via startswith("/")). Since FileWriterTool also takes a directory argument (and runs on non-POSIX systems), this example can be misleading for production security guidance. Consider validating the full resolved path using crewai_tools.security.safe_path.validate_file_path, which also handles symlinks and platform-specific path semantics, and abort with the actual validation error.

    filename = ctx.tool_input.get("filename", "")
    if ".." in filename or filename.startswith("/"):
        raise HookAborted(
            reason="invalid file path",
            source="file-policy",

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated no new comments.

Suppressed comments (1)

docs/edge/en/guides/agents/secure-agent-design.mdx:109

• This new edge-only guide uses internal links with the /en/... prefix (e.g. Tool hooks/LLM hooks/HITL/Task guardrails). In the edge docs, internal links should use /edge/en/... (as in other pages like docs/edge/en/learn/tool-hooks.mdx) and the PR description says this was done to keep mintlify broken-links passing. Please update these (and the other /en/... links elsewhere in this page) to /edge/en/....

| Hard blocks on dangerous calls | [Tool hooks](/en/learn/tool-hooks) (`PRE_TOOL_CALL` + `HookAborted`) |
| Inspect model traffic | [LLM hooks](/en/learn/llm-hooks) |
| Human approval for irreversible actions | Tool hooks + [HITL](/en/learn/human-in-the-loop) |
| Output checks before side effects | [Task guardrails](/en/concepts/tasks#task-guardrails) |

[coderabbitai]

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/edge/en/concepts/agents.mdx`:
- Around line 641-644: Sync the `kickoff()` documentation update from
`docs/edge/en/concepts/agents.mdx` into the corresponding Arabic, Korean, and
Brazilian Portuguese MDX files, following the mappings and translation
requirements in `DOCS_TRANSLATIONS.md`; preserve the same AgentExecutor behavior
and LiteAgentOutput details in each translation.
- Around line 641-644: Synchronize the direct kickoff() section across the
localized agent concept docs: add the complete English-equivalent section to the
Arabic and Brazilian Portuguese files, and update the Korean note to use the
AgentExecutor symbol. Keep the content and LiteAgentOutput return behavior
consistent across all locales.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 4417a52c-1d44-47a6-b658-88f0f968bd01

📥 Commits

Reviewing files that changed from the base of the PR and between 112683b and da28681.

📒 Files selected for processing (2)

• docs/edge/en/concepts/agents.mdx
• docs/edge/en/guides/agents/secure-agent-design.mdx

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/edge/en/guides/agents/secure-agent-design.mdx