From 79f01b45b53d850267659bdda74a45fa296f49ab Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 24 Aug 2026 09:47:07 +0000 Subject: [PATCH] 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 --- .../ar/guides/agents/secure-agent-design.mdx | 26 ++++++++++++------- .../en/guides/agents/secure-agent-design.mdx | 26 ++++++++++++------- .../ko/guides/agents/secure-agent-design.mdx | 26 ++++++++++++------- .../guides/agents/secure-agent-design.mdx | 26 ++++++++++++------- 4 files changed, 68 insertions(+), 36 deletions(-) diff --git a/docs/edge/ar/guides/agents/secure-agent-design.mdx b/docs/edge/ar/guides/agents/secure-agent-design.mdx index bb5c35682..5b22372ff 100644 --- a/docs/edge/ar/guides/agents/secure-agent-design.mdx +++ b/docs/edge/ar/guides/agents/secure-agent-design.mdx @@ -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 قبل أن تستمر. - مراجعة بشرية للإجراءات عالية التأثير. + موافقة ومراجعة بعد التشغيل. ليست عنصر تحكم. ولا تتحقق ممن وافق. حدود التنفيذ والتفصيل وإعدادات الـ Agent. diff --git a/docs/edge/en/guides/agents/secure-agent-design.mdx b/docs/edge/en/guides/agents/secure-agent-design.mdx index b3a5bb191..fea72af26 100644 --- a/docs/edge/en/guides/agents/secure-agent-design.mdx +++ b/docs/edge/en/guides/agents/secure-agent-design.mdx @@ -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. - Human review for high-impact actions. + Approval and post-run review. Not a control. Does not check who approved. 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 e69592136..2dae8eda2 100644 --- a/docs/edge/ko/guides/agents/secure-agent-design.mdx +++ b/docs/edge/ko/guides/agents/secure-agent-design.mdx @@ -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 출력을 검증합니다. - 고영향 동작에 대한 사람 검토. + 승인과 실행 후 검토. 통제가 아닙니다. 누가 승인했는지는 검사하지 않습니다. 실행 제한, verbose, 에이전트 설정. 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 8d285e797..0c19c2cac 100644 --- a/docs/edge/pt-BR/guides/agents/secure-agent-design.mdx +++ b/docs/edge/pt-BR/guides/agents/secure-agent-design.mdx @@ -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. - 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. Limites de execução, verbosidade e configurações do agente.