From ff7fd108ff4fa616779cb7437b2955b3f6103fba Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 24 Aug 2026 09:39:46 +0000 Subject: [PATCH] docs: tighten Secure Agent Design scope and fill examples Keep the guide focused on threat model and execution-path behavior, point knobs at Customize Agents, warn that backstory is a soft control, replace the Flow stub with a state handoff, and add the missing pt-BR kickoff note. Co-authored-by: Rip&Tear --- .../ar/guides/agents/secure-agent-design.mdx | 20 ++++++++++--- .../en/guides/agents/secure-agent-design.mdx | 20 ++++++++++--- .../ko/guides/agents/secure-agent-design.mdx | 20 ++++++++++--- docs/edge/pt-BR/concepts/agents.mdx | 29 +++++++++++++++++++ .../guides/agents/secure-agent-design.mdx | 20 ++++++++++--- 5 files changed, 93 insertions(+), 16 deletions(-) diff --git a/docs/edge/ar/guides/agents/secure-agent-design.mdx b/docs/edge/ar/guides/agents/secure-agent-design.mdx index 23211dabc..bb5c35682 100644 --- a/docs/edge/ar/guides/agents/secure-agent-design.mdx +++ b/docs/edge/ar/guides/agents/secure-agent-design.mdx @@ -13,6 +13,8 @@ mode: "wide" يمنحكم CrewAI لبنات بناء: hooks وguardrails وHITL ومخرجات منظمة وحالة Flow. وهو لا يفعّلها كإعداد آمن افتراضي. يجب عليكم تعيين الأدوات وقوائم السماح وفحوصات الموافقة في كود التطبيق. +تغطي هذه الصفحة نموذج التهديد وسلوك مسار التنفيذ. لحدود التنفيذ (`max_rpm` و`max_iter` و`max_execution_time`) والتفصيل وإعدادات الـ Agent، راجع [Agents](/ar/concepts/agents) و[تخصيص الـ Agents](/ar/learn/customizing-agents). + | لبنة البناء | ما تفعله عند إضافتها | | --- | --- | | `HookAborted` في tool hook | يوقف استدعاء تلك الأداة فقط. يستمر الـ Agent. ويتلقى رسالة بأن الأداة حُظرت. | @@ -79,6 +81,8 @@ researcher = Agent( ) ``` +نص `backstory` عنصر تحكم ضعيف. وهو لا يمنع النموذج من اتباع النص غير الموثوق. استخدم tool hooks وقوائم السماح أدناه لفرض السياسة. + لمدخلات Crew وFlow، استخدم [execution boundary hooks](/ar/learn/execution-boundary-hooks) (`INPUT`). هذه الـ hooks لا تعمل على `agent.kickoff()` المستقل. لـ MCP، راجع [أمان MCP](/ar/mcp/security). ## 2. حقن المطالبات @@ -289,13 +293,18 @@ class PipelineState(BaseModel): class SecureOutreachFlow(Flow[PipelineState]): @start() def research(self): - # Fetch tools only; write structured notes into state - ... + result = researcher.kickoff( + f"Extract factual notes about {self.state.topic}." + ) + self.state.notes = [result.raw] @listen(research) def send(self): - # No fetch tools; send or write tools sit behind hooks or HITL - ... + approved = "\n".join(self.state.notes) + result = sender.kickoff( + f"Send outreach using only these notes:\n{approved}" + ) + self.state.email_status = result.raw ``` راجع [بنية الإنتاج](/ar/concepts/production-architecture). @@ -321,4 +330,7 @@ class SecureOutreachFlow(Flow[PipelineState]): مراجعة بشرية للإجراءات عالية التأثير. + + حدود التنفيذ والتفصيل وإعدادات الـ Agent. + diff --git a/docs/edge/en/guides/agents/secure-agent-design.mdx b/docs/edge/en/guides/agents/secure-agent-design.mdx index 2c76548d9..b3a5bb191 100644 --- a/docs/edge/en/guides/agents/secure-agent-design.mdx +++ b/docs/edge/en/guides/agents/secure-agent-design.mdx @@ -13,6 +13,8 @@ This page shows how to limit that risk. Related reference: [OWASP Top 10 for LLM CrewAI gives you building blocks: hooks, guardrails, human-in-the-loop (HITL), structured outputs, and Flow state. It does not turn these on as a secure default. You must set tools, allowlists, and approval checks in your application code. +This page covers threat model and execution-path behavior. For execution limits (`max_rpm`, `max_iter`, `max_execution_time`), verbosity, and agent settings, see [Agents](/en/concepts/agents) and [Customize Agents](/en/learn/customizing-agents). + | Building block | What it does when you add it | | --- | --- | | `HookAborted` in a tool hook | Stops that one tool call. The agent continues. It receives a message that the tool was blocked. | @@ -79,6 +81,8 @@ researcher = Agent( ) ``` +The `backstory` text is a soft control. It does not stop the model from following untrusted text. Use tool hooks and allowlists below to enforce policy. + For Crew and Flow inputs, use [execution boundary hooks](/en/learn/execution-boundary-hooks) (`INPUT`). Those hooks do not run on standalone `agent.kickoff()`. For MCP, see [MCP Security](/en/mcp/security). ## 2. Prompt injection @@ -289,13 +293,18 @@ class PipelineState(BaseModel): class SecureOutreachFlow(Flow[PipelineState]): @start() def research(self): - # Fetch tools only; write structured notes into state - ... + result = researcher.kickoff( + f"Extract factual notes about {self.state.topic}." + ) + self.state.notes = [result.raw] @listen(research) def send(self): - # No fetch tools; send or write tools sit behind hooks or HITL - ... + approved = "\n".join(self.state.notes) + result = sender.kickoff( + f"Send outreach using only these notes:\n{approved}" + ) + self.state.email_status = result.raw ``` See [Production Architecture](/en/concepts/production-architecture). @@ -321,4 +330,7 @@ See [Production Architecture](/en/concepts/production-architecture). Human review for high-impact actions. + + Execution limits, verbosity, and agent settings. + diff --git a/docs/edge/ko/guides/agents/secure-agent-design.mdx b/docs/edge/ko/guides/agents/secure-agent-design.mdx index b3f284b30..e69592136 100644 --- a/docs/edge/ko/guides/agents/secure-agent-design.mdx +++ b/docs/edge/ko/guides/agents/secure-agent-design.mdx @@ -13,6 +13,8 @@ CrewAI 에이전트는 실제 동작을 수행하는 도구를 호출할 수 있 CrewAI는 hooks, guardrails, HITL, 구조화된 출력, Flow state라는 구성 요소를 제공합니다. 이것들을 안전한 기본값으로 켜지는 않습니다. 도구, allowlist, 승인 검사는 애플리케이션 코드에서 설정해야 합니다. +이 페이지는 위협 모델과 실행 경로 동작을 다룹니다. 실행 제한(`max_rpm`, `max_iter`, `max_execution_time`), verbose, 에이전트 설정은 [에이전트](/ko/concepts/agents)와 [에이전트 맞춤화](/ko/learn/customizing-agents)를 참고하세요. + | 구성 요소 | 추가했을 때 하는 일 | | --- | --- | | tool hook의 `HookAborted` | 해당 도구 호출 하나만 중지합니다. 에이전트는 계속합니다. 도구가 차단되었다는 메시지를 받습니다. | @@ -79,6 +81,8 @@ researcher = Agent( ) ``` +`backstory` 텍스트는 약한 통제입니다. 모델이 신뢰할 수 없는 텍스트를 따르는 것을 막지 않습니다. 정책은 아래 tool hooks와 allowlist로 강제하세요. + Crew와 Flow 입력에는 [execution boundary hooks](/ko/learn/execution-boundary-hooks) (`INPUT`)를 사용하세요. 이 hooks는 단독 `agent.kickoff()`에서는 실행되지 않습니다. MCP는 [MCP 보안](/ko/mcp/security)을 참고하세요. ## 2. 프롬프트 인젝션 @@ -289,13 +293,18 @@ class PipelineState(BaseModel): class SecureOutreachFlow(Flow[PipelineState]): @start() def research(self): - # Fetch tools only; write structured notes into state - ... + result = researcher.kickoff( + f"Extract factual notes about {self.state.topic}." + ) + self.state.notes = [result.raw] @listen(research) def send(self): - # No fetch tools; send or write tools sit behind hooks or HITL - ... + approved = "\n".join(self.state.notes) + result = sender.kickoff( + f"Send outreach using only these notes:\n{approved}" + ) + self.state.email_status = result.raw ``` [프로덕션 아키텍처](/ko/concepts/production-architecture)를 참고하세요. @@ -321,4 +330,7 @@ class SecureOutreachFlow(Flow[PipelineState]): 고영향 동작에 대한 사람 검토. + + 실행 제한, verbose, 에이전트 설정. + diff --git a/docs/edge/pt-BR/concepts/agents.mdx b/docs/edge/pt-BR/concepts/agents.mdx index 7c9f1ce5f..fb2bad3f2 100644 --- a/docs/edge/pt-BR/concepts/agents.mdx +++ b/docs/edge/pt-BR/concepts/agents.mdx @@ -582,6 +582,35 @@ agent = Agent( `respect_context_window` conforme deseja e o CrewAI cuida do resto! +## Interação direta com o agente via `kickoff()` {#direct-agent-interaction-with-kickoff} + +Agentes podem ser usados diretamente, sem passar por uma Task ou um fluxo de Crew, com o método `kickoff()`. Isso oferece uma forma mais simples de interagir com um agente quando você não precisa da orquestração completa do crew. + +```python Code +from crewai import Agent +from crewai_tools import SerperDevTool + +# Criar um agente +researcher = Agent( + role="AI Technology Researcher", + goal="Research the latest AI developments", + tools=[SerperDevTool()], + verbose=True +) + +# Usar kickoff() para interagir diretamente com o agente +result = researcher.kickoff("What are the latest developments in language models?") + +# Acessar a resposta bruta +print(result.raw) +``` + + + `kickoff()` executa um `AgentExecutor`. Ele não cria uma Task nem um Crew. + O agente mantém role, goal, backstory e tools. O método retorna + `LiteAgentOutput`. + + ## Considerações e Boas Práticas Importantes ### Segurança e Execução de Código diff --git a/docs/edge/pt-BR/guides/agents/secure-agent-design.mdx b/docs/edge/pt-BR/guides/agents/secure-agent-design.mdx index 38787a40c..8d285e797 100644 --- a/docs/edge/pt-BR/guides/agents/secure-agent-design.mdx +++ b/docs/edge/pt-BR/guides/agents/secure-agent-design.mdx @@ -13,6 +13,8 @@ Esta página mostra como limitar esse risco. Referência relacionada: [OWASP Top O CrewAI oferece blocos de construção: hooks, guardrails, HITL, saídas estruturadas e estado de Flow. Ele não liga esses recursos como um padrão seguro. Você deve definir ferramentas, allowlists e checagens de aprovação no código da aplicação. +Esta página cobre o modelo de ameaça e o comportamento por caminho de execução. Para limites de execução (`max_rpm`, `max_iter`, `max_execution_time`), verbosidade e configurações do agente, veja [Agentes](/pt-BR/concepts/agents) e [Personalize Agentes](/pt-BR/learn/customizing-agents). + | Bloco de construção | O que faz quando você o adiciona | | --- | --- | | `HookAborted` em um tool hook | Interrompe aquela chamada de ferramenta. O agente continua. Ele recebe uma mensagem de que a ferramenta foi bloqueada. | @@ -79,6 +81,8 @@ researcher = Agent( ) ``` +O texto de `backstory` é um controle fraco. Ele não impede o modelo de seguir texto não confiável. Use tool hooks e allowlists abaixo para aplicar a política. + Para entradas de Crew e Flow, use [execution boundary hooks](/pt-BR/learn/execution-boundary-hooks) (`INPUT`). Esses hooks não rodam em `agent.kickoff()` isolado. Para MCP, veja [Segurança MCP](/pt-BR/mcp/security). ## 2. Prompt injection @@ -289,13 +293,18 @@ class PipelineState(BaseModel): class SecureOutreachFlow(Flow[PipelineState]): @start() def research(self): - # Fetch tools only; write structured notes into state - ... + result = researcher.kickoff( + f"Extract factual notes about {self.state.topic}." + ) + self.state.notes = [result.raw] @listen(research) def send(self): - # No fetch tools; send or write tools sit behind hooks or HITL - ... + approved = "\n".join(self.state.notes) + result = sender.kickoff( + f"Send outreach using only these notes:\n{approved}" + ) + self.state.email_status = result.raw ``` Veja [Arquitetura de Produção](/pt-BR/concepts/production-architecture). @@ -321,4 +330,7 @@ Veja [Arquitetura de Produção](/pt-BR/concepts/production-architecture). Revisão humana para ações de alto impacto. + + Limites de execução, verbosidade e configurações do agente. +