mirror of
https://github.com/crewAIInc/crewAI.git
synced 2026-09-19 17:46:14 +00:00
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 <theCyberTech@users.noreply.github.com>
This commit is contained in:
Cursor Agent
@@ -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]):
|
||||
<Card title="Human-in-the-Loop" icon="user-check" href="/ar/learn/human-in-the-loop">
|
||||
مراجعة بشرية للإجراءات عالية التأثير.
|
||||
</Card>
|
||||
<Card title="تخصيص الـ Agents" icon="user-pen" href="/ar/learn/customizing-agents">
|
||||
حدود التنفيذ والتفصيل وإعدادات الـ Agent.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@@ -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).
|
||||
<Card title="Human-in-the-Loop" icon="user-check" href="/en/learn/human-in-the-loop">
|
||||
Human review for high-impact actions.
|
||||
</Card>
|
||||
<Card title="Customize Agents" icon="user-pen" href="/en/learn/customizing-agents">
|
||||
Execution limits, verbosity, and agent settings.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@@ -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]):
|
||||
<Card title="Human-in-the-Loop" icon="user-check" href="/ko/learn/human-in-the-loop">
|
||||
고영향 동작에 대한 사람 검토.
|
||||
</Card>
|
||||
<Card title="에이전트 맞춤화" icon="user-pen" href="/ko/learn/customizing-agents">
|
||||
실행 제한, verbose, 에이전트 설정.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@@ -582,6 +582,35 @@ agent = Agent(
|
||||
`respect_context_window` conforme deseja e o CrewAI cuida do resto!
|
||||
</Note>
|
||||
|
||||
## 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)
|
||||
```
|
||||
|
||||
<Note>
|
||||
`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`.
|
||||
</Note>
|
||||
|
||||
## Considerações e Boas Práticas Importantes
|
||||
|
||||
### Segurança e Execução de Código
|
||||
|
||||
@@ -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).
|
||||
<Card title="Human-in-the-Loop" icon="user-check" href="/pt-BR/learn/human-in-the-loop">
|
||||
Revisão humana para ações de alto impacto.
|
||||
</Card>
|
||||
<Card title="Personalize Agentes" icon="user-pen" href="/pt-BR/learn/customizing-agents">
|
||||
Limites de execução, verbosidade e configurações do agente.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
Reference in New Issue
Block a user