mirror of
https://github.com/crewAIInc/crewAI.git
synced 2026-09-22 19:06:25 +00:00
docs: treat HITL as approval, not a control
Align Secure Agent Design with the human_input contract: post-run output review, no tool gate, and no check of who approved. Keep pre-execution blocking on tool hooks. Co-authored-by: Rip&Tear <theCyberTech@users.noreply.github.com>
This commit is contained in:
Cursor Agent
@@ -11,7 +11,9 @@ mode: "wide"
|
||||
|
||||
توضّح هذه الصفحة كيفية الحد من هذا الخطر. مرجع ذو صلة: [OWASP Top 10 for LLM Applications](https://owasp.org/www-project-top-10-for-large-language-model-applications/) (حقن المطالبات والوكالة المفرطة).
|
||||
|
||||
يمنحكم CrewAI لبنات بناء: hooks وguardrails وHITL ومخرجات منظمة وحالة Flow. وهو لا يفعّلها كإعداد آمن افتراضي. يجب عليكم تعيين الأدوات وقوائم السماح وفحوصات الموافقة في كود التطبيق.
|
||||
يمنحكم CrewAI لبنات بناء: hooks وguardrails ومخرجات منظمة وحالة Flow. وهو لا يفعّلها كإعداد آمن افتراضي. يجب عليكم تعيين الأدوات وقوائم السماح وفحوصات الموافقة في كود التطبيق.
|
||||
|
||||
Human-in-the-loop (HITL) موافقة، وليس عنصر تحكم. يتوقف ليقبل شخص أو يرفض أو يعلّق. وهو لا يصادق على الموافق، ولا يتحقق من دوره، ولا يثبت أنه مسموح له بالقرار.
|
||||
|
||||
تغطي هذه الصفحة نموذج التهديد وسلوك مسار التنفيذ. لحدود التنفيذ (`max_rpm` و`max_iter` و`max_execution_time`) والتفصيل وإعدادات الـ Agent، راجع [Agents](/ar/concepts/agents) و[تخصيص الـ Agents](/ar/learn/customizing-agents).
|
||||
|
||||
@@ -19,7 +21,7 @@ mode: "wide"
|
||||
| --- | --- |
|
||||
| `HookAborted` في tool hook | يوقف استدعاء تلك الأداة فقط. يستمر الـ Agent. ويتلقى رسالة بأن الأداة حُظرت. |
|
||||
| Task `guardrail` | يرفض أو يعيد محاولة مخرج Task على مسار Task. |
|
||||
| Task `human_input` | يتوقف لإدخال وحدة التحكم على مسار Task. |
|
||||
| Task `human_input` | موافقة: يراجع الإجابة النهائية بعد تشغيل الأدوات على مسار Task. ولا يحظر الأدوات. ولا يتحقق ممن وافق. |
|
||||
| `output_pydantic` / `output_json` | يلائم المخرج مع مخطط. ولا يتحقق من قواعد العمل. |
|
||||
| `Agent.guardrail` | يتحقق من المخرج على `agent.kickoff()` فقط. ولا يعمل أثناء تنفيذ Task في Crew. |
|
||||
|
||||
@@ -102,7 +104,7 @@ researcher = Agent(
|
||||
| أدوات بأقل امتياز | `tools=[...]` على كل Agent |
|
||||
| حظر الاستدعاءات أو تقييدها | [Tool hooks](/ar/learn/tool-hooks) (`PRE_TOOL_CALL` + `HookAborted`) |
|
||||
| فحص استدعاءات النموذج | [LLM hooks](/ar/learn/llm-hooks) |
|
||||
| موافقة بشرية | Tool hooks + [HITL](/ar/learn/human-in-the-loop) |
|
||||
| موافقة بشرية | [HITL](/ar/learn/human-in-the-loop) / `request_human_input` — موافقة فقط. ليست عنصر تحكم. ولا تتحقق ممن وافق. استخدم tool hooks لحظر الاستدعاء. |
|
||||
| فحوصات المخرج | [Task guardrails](/ar/concepts/tasks#task-guardrails) على مسار Task؛ `Agent.guardrail` على `kickoff()` |
|
||||
| شكل منظم | `output_pydantic` / `output_json` أو `response_format=` (الشكل فقط) |
|
||||
|
||||
@@ -226,7 +228,9 @@ Task(
|
||||
|
||||
## 6. بوابات الموافقة
|
||||
|
||||
اطلب تحققًا بشريًا أو من سياسة خارجية قبل الإجراءات غير القابلة للعكس أو المكلفة أو العلنية.
|
||||
HITL موافقة، وليس عنصر تحكم. يطلب من شخص القبول أو الرفض. وهو لا يصادق على ذلك الشخص، ولا يتحقق من دوره، ولا يسجّل أنه كان مخوّلًا. يقبل `input()` الافتراضي في وحدة التحكم من يكون على لوحة المفاتيح.
|
||||
|
||||
اطلب موافقة قبل الإجراءات غير القابلة للعكس أو المكلفة أو العلنية. ضع التوقف في الكود. لا تعتمد على المطالبة وحدها.
|
||||
|
||||
| الخطر | أمثلة | البوابة |
|
||||
| --- | --- | --- |
|
||||
@@ -234,6 +238,10 @@ Task(
|
||||
| متوسط | رسائل إلى مستخدمين حقيقيين، كتابة ملفات، تحديث تذاكر | وافق أو استخدم قائمة سماح |
|
||||
| منخفض | البحث، التلخيص، التصنيف | أتمت مع التسجيل |
|
||||
|
||||
يتوقف Task `human_input=True` **بعد** أن يشغّل الـ Agent أدواته وينتج نتيجة. ويراجع الإجابة النهائية قبل قبول ذلك المخرج. **ولا** يمنع تنفيذ الأدوات. يمكن للـ Agent في تلك الـ Task أن يستدعي أدوات مدمرة قبل أن يرى أي إنسان التشغيل. استخدمه فقط عندما تكفي مراجعة المخرج بعد التشغيل. راجع [الإدخال البشري أثناء التنفيذ](/ar/learn/human-input-on-execution).
|
||||
|
||||
للموافقة **قبل** تشغيل أداة، استخدم tool hook و`HookAborted`:
|
||||
|
||||
```python
|
||||
from crewai.hooks import HookAborted, InterceptionPoint, on
|
||||
|
||||
@@ -247,13 +255,13 @@ def require_email_approval(ctx):
|
||||
raise HookAborted(reason="denied by operator", source="approval-gate")
|
||||
```
|
||||
|
||||
`request_human_input` ما زال موافقة. وهو لا يتحقق ممن كتب `yes`. أضف فحص هوية أو سياسة خاصًا بك إذا احتجت ذلك.
|
||||
|
||||
خيارات أخرى:
|
||||
|
||||
- Task `human_input=True` — مسار تنفيذ Task / Crew فقط. راجع [الإدخال البشري أثناء التنفيذ](/ar/learn/human-input-on-execution).
|
||||
- Task `human_input=True` — مراجعة المخرج بعد التشغيل على مسار Task / Crew فقط.
|
||||
- `ToolCallHookContext.request_human_input` — يعمل على `agent.kickoff()` وتشغيلات Crew. يستخدم افتراضيًا `input()` لوحدة تحكم حاجزًا.
|
||||
- `@human_feedback` / webhooks HITL للمؤسسات — [Human-in-the-Loop](/ar/learn/human-in-the-loop)، [Human Feedback في Flows](/ar/learn/human-feedback-in-flows).
|
||||
|
||||
افرض الموافقة في الكود. لا تعتمد على المطالبة وحدها.
|
||||
- `@human_feedback` / webhooks HITL للمؤسسات — [Human-in-the-Loop](/ar/learn/human-in-the-loop)، [Human Feedback في Flows](/ar/learn/human-feedback-in-flows). الحد نفسه: CrewAI لا يتحقق من الموافق إلا إذا أضفت ذلك خارج هذه الواجهات.
|
||||
|
||||
## 7. تقييد التفويض
|
||||
|
||||
@@ -328,7 +336,7 @@ class SecureOutreachFlow(Flow[PipelineState]):
|
||||
تحقق من مخرجات Task قبل أن تستمر.
|
||||
</Card>
|
||||
<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.
|
||||
|
||||
@@ -11,7 +11,9 @@ CrewAI agents can call tools that take real actions. Untrusted text in the model
|
||||
|
||||
This page shows how to limit that risk. Related reference: [OWASP Top 10 for LLM Applications](https://owasp.org/www-project-top-10-for-large-language-model-applications/) (prompt injection and excessive agency).
|
||||
|
||||
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.
|
||||
CrewAI gives you building blocks: hooks, guardrails, 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.
|
||||
|
||||
Human-in-the-loop (HITL) is approval, not a control. It pauses for a person to accept, reject, or comment. It does not authenticate the approver, check their role, or prove they were allowed to decide.
|
||||
|
||||
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).
|
||||
|
||||
@@ -19,7 +21,7 @@ This page covers threat model and execution-path behavior. For execution limits
|
||||
| --- | --- |
|
||||
| `HookAborted` in a tool hook | Stops that one tool call. The agent continues. It receives a message that the tool was blocked. |
|
||||
| Task `guardrail` | Rejects or retries Task output on the Task path. |
|
||||
| Task `human_input` | Pauses for console input on the Task path. |
|
||||
| Task `human_input` | Approval: reviews the final answer after tools ran on the Task path. It does not block tools. It does not check who approved. |
|
||||
| `output_pydantic` / `output_json` | Fits output to a schema. It does not check business rules. |
|
||||
| `Agent.guardrail` | Checks output on `agent.kickoff()` only. It does not run on Crew Task execution. |
|
||||
|
||||
@@ -102,7 +104,7 @@ Examples:
|
||||
| Least-privilege tools | `tools=[...]` on each agent |
|
||||
| Block or constrain calls | [Tool hooks](/en/learn/tool-hooks) (`PRE_TOOL_CALL` + `HookAborted`) |
|
||||
| Inspect model calls | [LLM hooks](/en/learn/llm-hooks) |
|
||||
| Human approval | Tool hooks + [HITL](/en/learn/human-in-the-loop) |
|
||||
| Human approval | [HITL](/en/learn/human-in-the-loop) / `request_human_input` — approval only. Not a control. Does not check who approved. Use tool hooks to block the call. |
|
||||
| Output checks | [Task guardrails](/en/concepts/tasks#task-guardrails) on the Task path; `Agent.guardrail` on `kickoff()` |
|
||||
| Structured shape | `output_pydantic` / `output_json` or `response_format=` (shape only) |
|
||||
|
||||
@@ -226,7 +228,9 @@ String or `LLMGuardrail` checks work on both the Task path and the kickoff path.
|
||||
|
||||
## 6. Approval gates
|
||||
|
||||
Require a human or an external policy check before irreversible, expensive, or public actions.
|
||||
HITL is approval, not a control. It asks a person to accept or reject. It does not authenticate that person, check their role, or record that they were authorized. Default console `input()` accepts whoever is at the keyboard.
|
||||
|
||||
Require approval before irreversible, expensive, or public actions. Put the pause in code. Do not rely on the prompt alone.
|
||||
|
||||
| Risk | Examples | Gate |
|
||||
| --- | --- | --- |
|
||||
@@ -234,6 +238,10 @@ Require a human or an external policy check before irreversible, expensive, or p
|
||||
| Medium | Emails to real users, file writes, ticket updates | Approve or allowlist |
|
||||
| Low | Search, summarize, classify | Automate with logging |
|
||||
|
||||
Task `human_input=True` pauses **after** the agent has run its tools and produced a result. It reviews the final answer before that output is accepted. It does **not** gate tool execution. An agent on that task can still call destructive tools before any human sees the run. Use it only when post-run output review is enough. See [Human input on execution](/en/learn/human-input-on-execution).
|
||||
|
||||
For approval **before** a tool runs, use a tool hook and `HookAborted`:
|
||||
|
||||
```python
|
||||
from crewai.hooks import HookAborted, InterceptionPoint, on
|
||||
|
||||
@@ -247,13 +255,13 @@ def require_email_approval(ctx):
|
||||
raise HookAborted(reason="denied by operator", source="approval-gate")
|
||||
```
|
||||
|
||||
`request_human_input` is still approval. It does not validate who typed `yes`. Add your own identity or policy check if you need that.
|
||||
|
||||
Other options:
|
||||
|
||||
- Task `human_input=True` — Task execute / Crew path only. See [Human input on execution](/en/learn/human-input-on-execution).
|
||||
- Task `human_input=True` — post-run output review on the Task / Crew path only.
|
||||
- `ToolCallHookContext.request_human_input` — works on `agent.kickoff()` and Crew runs. By default it uses a blocking console `input()`.
|
||||
- `@human_feedback` / Enterprise HITL webhooks — [Human-in-the-Loop](/en/learn/human-in-the-loop), [Human Feedback in Flows](/en/learn/human-feedback-in-flows).
|
||||
|
||||
Enforce approval in code. Do not rely on the prompt alone.
|
||||
- `@human_feedback` / Enterprise HITL webhooks — [Human-in-the-Loop](/en/learn/human-in-the-loop), [Human Feedback in Flows](/en/learn/human-feedback-in-flows). Same limit: CrewAI does not verify the approver unless you add that outside these APIs.
|
||||
|
||||
## 7. Limiting delegation
|
||||
|
||||
@@ -328,7 +336,7 @@ See [Production Architecture](/en/concepts/production-architecture).
|
||||
Validate task outputs before they continue.
|
||||
</Card>
|
||||
<Card title="Human-in-the-Loop" icon="user-check" href="/en/learn/human-in-the-loop">
|
||||
Human review for high-impact actions.
|
||||
Approval and post-run review. Not a control. Does not check who approved.
|
||||
</Card>
|
||||
<Card title="Customize Agents" icon="user-pen" href="/en/learn/customizing-agents">
|
||||
Execution limits, verbosity, and agent settings.
|
||||
|
||||
@@ -11,7 +11,9 @@ CrewAI 에이전트는 실제 동작을 수행하는 도구를 호출할 수 있
|
||||
|
||||
이 페이지는 그 위험을 제한하는 방법을 보여 줍니다. 관련 참고: [OWASP Top 10 for LLM Applications](https://owasp.org/www-project-top-10-for-large-language-model-applications/) (프롬프트 인젝션 및 과도한 agency).
|
||||
|
||||
CrewAI는 hooks, guardrails, HITL, 구조화된 출력, Flow state라는 구성 요소를 제공합니다. 이것들을 안전한 기본값으로 켜지는 않습니다. 도구, allowlist, 승인 검사는 애플리케이션 코드에서 설정해야 합니다.
|
||||
CrewAI는 hooks, guardrails, 구조화된 출력, Flow state라는 구성 요소를 제공합니다. 이것들을 안전한 기본값으로 켜지는 않습니다. 도구, allowlist, 승인 검사는 애플리케이션 코드에서 설정해야 합니다.
|
||||
|
||||
Human-in-the-loop (HITL)는 승인이지 통제가 아닙니다. 사람이 수락, 거부, 의견을 남기도록 일시 중지합니다. 승인자를 인증하지 않고, 역할을 확인하지 않으며, 결정할 권한이 있었음을 증명하지 않습니다.
|
||||
|
||||
이 페이지는 위협 모델과 실행 경로 동작을 다룹니다. 실행 제한(`max_rpm`, `max_iter`, `max_execution_time`), verbose, 에이전트 설정은 [에이전트](/ko/concepts/agents)와 [에이전트 맞춤화](/ko/learn/customizing-agents)를 참고하세요.
|
||||
|
||||
@@ -19,7 +21,7 @@ CrewAI는 hooks, guardrails, HITL, 구조화된 출력, Flow state라는 구성
|
||||
| --- | --- |
|
||||
| tool hook의 `HookAborted` | 해당 도구 호출 하나만 중지합니다. 에이전트는 계속합니다. 도구가 차단되었다는 메시지를 받습니다. |
|
||||
| Task `guardrail` | Task 경로에서 Task 출력을 거부하거나 재시도합니다. |
|
||||
| Task `human_input` | Task 경로에서 콘솔 입력을 위해 일시 중지합니다. |
|
||||
| Task `human_input` | 승인: Task 경로에서 도구가 실행된 뒤 최종 답변을 검토합니다. 도구를 차단하지 않습니다. 누가 승인했는지는 검사하지 않습니다. |
|
||||
| `output_pydantic` / `output_json` | 출력을 스키마에 맞춥니다. 비즈니스 규칙은 검사하지 않습니다. |
|
||||
| `Agent.guardrail` | `agent.kickoff()`에서만 출력을 검사합니다. Crew Task 실행에서는 실행되지 않습니다. |
|
||||
|
||||
@@ -102,7 +104,7 @@ Crew와 Flow 입력에는 [execution boundary hooks](/ko/learn/execution-boundar
|
||||
| 최소 권한 도구 | 각 에이전트의 `tools=[...]` |
|
||||
| 호출 차단 또는 제한 | [Tool hooks](/ko/learn/tool-hooks) (`PRE_TOOL_CALL` + `HookAborted`) |
|
||||
| 모델 호출 검사 | [LLM hooks](/ko/learn/llm-hooks) |
|
||||
| 사람 승인 | Tool hooks + [HITL](/ko/learn/human-in-the-loop) |
|
||||
| 사람 승인 | [HITL](/ko/learn/human-in-the-loop) / `request_human_input` — 승인만. 통제가 아닙니다. 누가 승인했는지는 검사하지 않습니다. 호출을 차단하려면 tool hooks를 사용하세요. |
|
||||
| 출력 검사 | Task 경로의 [Task guardrails](/ko/concepts/tasks#task-guardrails); `kickoff()`의 `Agent.guardrail` |
|
||||
| 구조화된 형태 | `output_pydantic` / `output_json` 또는 `response_format=` (형태만) |
|
||||
|
||||
@@ -226,7 +228,9 @@ Task(
|
||||
|
||||
## 6. 승인 게이트
|
||||
|
||||
되돌릴 수 없거나, 비용이 크거나, 공개되는 동작 전에는 사람 또는 외부 정책 검사를 요구하세요.
|
||||
HITL은 승인이지 통제가 아닙니다. 사람에게 수락 또는 거부를 요청합니다. 그 사람을 인증하지 않고, 역할을 확인하지 않으며, 권한이 있었음을 기록하지 않습니다. 기본 콘솔 `input()`은 키보드 앞에 있는 누구든 받습니다.
|
||||
|
||||
되돌릴 수 없거나, 비용이 크거나, 공개되는 동작 전에는 승인을 요구하세요. 일시 중지는 코드에 두세요. 프롬프트에만 의존하지 마세요.
|
||||
|
||||
| 위험 | 예 | 게이트 |
|
||||
| --- | --- | --- |
|
||||
@@ -234,6 +238,10 @@ Task(
|
||||
| 중간 | 실제 사용자에게 이메일, 파일 쓰기, 티켓 업데이트 | 승인 또는 allowlist |
|
||||
| 낮음 | 검색, 요약, 분류 | 로깅과 함께 자동화 |
|
||||
|
||||
Task `human_input=True`는 에이전트가 도구를 실행하고 결과를 만든 **후**에 일시 중지합니다. 해당 출력이 수락되기 전에 최종 답변을 검토합니다. 도구 실행을 차단하지 **않습니다**. 그 Task의 에이전트는 사람이 실행을 보기 전에 파괴적인 도구를 호출할 수 있습니다. 실행 후 출력 검토로 충분할 때만 사용하세요. [실행 중 인간 입력](/ko/learn/human-input-on-execution)을 참고하세요.
|
||||
|
||||
도구가 실행되기 **전**에 승인하려면 tool hook과 `HookAborted`를 사용하세요.
|
||||
|
||||
```python
|
||||
from crewai.hooks import HookAborted, InterceptionPoint, on
|
||||
|
||||
@@ -247,13 +255,13 @@ def require_email_approval(ctx):
|
||||
raise HookAborted(reason="denied by operator", source="approval-gate")
|
||||
```
|
||||
|
||||
`request_human_input`도 승인입니다. `yes`를 입력한 사람을 검증하지 않습니다. 신원 또는 정책 검사가 필요하면 직접 추가하세요.
|
||||
|
||||
다른 옵션:
|
||||
|
||||
- Task `human_input=True` — Task 실행 / Crew 경로만. [실행 중 인간 입력](/ko/learn/human-input-on-execution)을 참고하세요.
|
||||
- Task `human_input=True` — Task / Crew 경로에서만 실행 후 출력 검토.
|
||||
- `ToolCallHookContext.request_human_input` — `agent.kickoff()`와 Crew 실행에서 동작합니다. 기본적으로 차단형 콘솔 `input()`을 사용합니다.
|
||||
- `@human_feedback` / Enterprise HITL webhooks — [Human-in-the-Loop](/ko/learn/human-in-the-loop), [Flows의 Human Feedback](/ko/learn/human-feedback-in-flows).
|
||||
|
||||
승인은 코드에서 강제하세요. 프롬프트에만 의존하지 마세요.
|
||||
- `@human_feedback` / Enterprise HITL webhooks — [Human-in-the-Loop](/ko/learn/human-in-the-loop), [Flows의 Human Feedback](/ko/learn/human-feedback-in-flows). 같은 한계: 이 API 밖에서 추가하지 않으면 CrewAI는 승인자를 검증하지 않습니다.
|
||||
|
||||
## 7. 위임 제한
|
||||
|
||||
@@ -328,7 +336,7 @@ class SecureOutreachFlow(Flow[PipelineState]):
|
||||
계속하기 전에 Task 출력을 검증합니다.
|
||||
</Card>
|
||||
<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, 에이전트 설정.
|
||||
|
||||
@@ -11,7 +11,9 @@ Agentes CrewAI podem chamar ferramentas que executam ações reais. Texto não c
|
||||
|
||||
Esta página mostra como limitar esse risco. Referência relacionada: [OWASP Top 10 for LLM Applications](https://owasp.org/www-project-top-10-for-large-language-model-applications/) (prompt injection e agency excessiva).
|
||||
|
||||
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.
|
||||
O CrewAI oferece blocos de construção: hooks, guardrails, 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.
|
||||
|
||||
Human-in-the-loop (HITL) é aprovação, não um controle. Ele pausa para uma pessoa aceitar, rejeitar ou comentar. Não autentica o aprovador, não verifica o papel dele e não prova que ele tinha permissão para decidir.
|
||||
|
||||
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).
|
||||
|
||||
@@ -19,7 +21,7 @@ Esta página cobre o modelo de ameaça e o comportamento por caminho de execuç
|
||||
| --- | --- |
|
||||
| `HookAborted` em um tool hook | Interrompe aquela chamada de ferramenta. O agente continua. Ele recebe uma mensagem de que a ferramenta foi bloqueada. |
|
||||
| Task `guardrail` | Rejeita ou retenta a saída da Task no caminho da Task. |
|
||||
| Task `human_input` | Pausa para input no console no caminho da Task. |
|
||||
| Task `human_input` | Aprovação: revisa a resposta final depois que as ferramentas rodaram no caminho da Task. Não bloqueia ferramentas. Não verifica quem aprovou. |
|
||||
| `output_pydantic` / `output_json` | Ajusta a saída a um schema. Não verifica regras de negócio. |
|
||||
| `Agent.guardrail` | Verifica a saída apenas em `agent.kickoff()`. Não roda na execução de Task do Crew. |
|
||||
|
||||
@@ -102,7 +104,7 @@ Exemplos:
|
||||
| Ferramentas com menor privilégio | `tools=[...]` em cada agente |
|
||||
| Bloquear ou restringir chamadas | [Tool hooks](/pt-BR/learn/tool-hooks) (`PRE_TOOL_CALL` + `HookAborted`) |
|
||||
| Inspecionar chamadas do modelo | [LLM hooks](/pt-BR/learn/llm-hooks) |
|
||||
| Aprovação humana | Tool hooks + [HITL](/pt-BR/learn/human-in-the-loop) |
|
||||
| Aprovação humana | [HITL](/pt-BR/learn/human-in-the-loop) / `request_human_input` — só aprovação. Não é um controle. Não verifica quem aprovou. Use tool hooks para bloquear a chamada. |
|
||||
| Checagens de saída | [Task guardrails](/pt-BR/concepts/tasks#task-guardrails) no caminho da Task; `Agent.guardrail` em `kickoff()` |
|
||||
| Forma estruturada | `output_pydantic` / `output_json` ou `response_format=` (apenas a forma) |
|
||||
|
||||
@@ -226,7 +228,9 @@ Checagens de string ou `LLMGuardrail` funcionam no caminho da Task e no caminho
|
||||
|
||||
## 6. Portões de aprovação
|
||||
|
||||
Exija uma pessoa ou uma checagem de política externa antes de ações irreversíveis, caras ou públicas.
|
||||
HITL é aprovação, não um controle. Pede a uma pessoa para aceitar ou rejeitar. Não autentica essa pessoa, não verifica o papel dela e não registra que ela estava autorizada. O `input()` padrão do console aceita quem estiver no teclado.
|
||||
|
||||
Exija aprovação antes de ações irreversíveis, caras ou públicas. Coloque a pausa no código. Não dependa só do prompt.
|
||||
|
||||
| Risco | Exemplos | Portão |
|
||||
| --- | --- | --- |
|
||||
@@ -234,6 +238,10 @@ Exija uma pessoa ou uma checagem de política externa antes de ações irrevers
|
||||
| Médio | E-mails para usuários reais, escrita de arquivos, atualizações de tickets | Aprovar ou allowlist |
|
||||
| Baixo | Busca, resumo, classificação | Automatizar com logging |
|
||||
|
||||
Task `human_input=True` pausa **depois** que o agente executou as ferramentas e produziu um resultado. Ele revisa a resposta final antes que essa saída seja aceita. **Não** bloqueia a execução de ferramentas. Um agente nessa Task ainda pode chamar ferramentas destrutivas antes que qualquer humano veja a execução. Use só quando a revisão da saída após a execução for suficiente. Veja [Input humano na execução](/pt-BR/learn/human-input-on-execution).
|
||||
|
||||
Para aprovação **antes** de uma ferramenta rodar, use um tool hook e `HookAborted`:
|
||||
|
||||
```python
|
||||
from crewai.hooks import HookAborted, InterceptionPoint, on
|
||||
|
||||
@@ -247,13 +255,13 @@ def require_email_approval(ctx):
|
||||
raise HookAborted(reason="denied by operator", source="approval-gate")
|
||||
```
|
||||
|
||||
`request_human_input` ainda é aprovação. Não valida quem digitou `yes`. Adicione sua própria checagem de identidade ou política se precisar.
|
||||
|
||||
Outras opções:
|
||||
|
||||
- Task `human_input=True` — apenas no caminho de execução da Task / Crew. Veja [Input humano na execução](/pt-BR/learn/human-input-on-execution).
|
||||
- Task `human_input=True` — revisão da saída após a execução só no caminho Task / Crew.
|
||||
- `ToolCallHookContext.request_human_input` — funciona em `agent.kickoff()` e em execuções de Crew. Por padrão usa um `input()` de console bloqueante.
|
||||
- `@human_feedback` / webhooks HITL Enterprise — [Human-in-the-Loop](/pt-BR/learn/human-in-the-loop), [Human Feedback em Flows](/pt-BR/learn/human-feedback-in-flows).
|
||||
|
||||
Aplique a aprovação em código. Não dependa só do prompt.
|
||||
- `@human_feedback` / webhooks HITL Enterprise — [Human-in-the-Loop](/pt-BR/learn/human-in-the-loop), [Human Feedback em Flows](/pt-BR/learn/human-feedback-in-flows). O mesmo limite: o CrewAI não verifica o aprovador a menos que você adicione isso fora dessas APIs.
|
||||
|
||||
## 7. Limitando a delegação
|
||||
|
||||
@@ -328,7 +336,7 @@ Veja [Arquitetura de Produção](/pt-BR/concepts/production-architecture).
|
||||
Valide saídas de Task antes que elas continuem.
|
||||
</Card>
|
||||
<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.
|
||||
Aprovação e revisão após a execução. Não é um controle. Não verifica quem aprovou.
|
||||
</Card>
|
||||
<Card title="Personalize Agentes" icon="user-pen" href="/pt-BR/learn/customizing-agents">
|
||||
Limites de execução, verbosidade e configurações do agente.
|
||||
|
||||
Reference in New Issue
Block a user