feature: human input per task (#395)

* feature: human input per task

* Update executor.py

* Update executor.py

* Update executor.py

* Update executor.py

* Update executor.py

* feat: change human input for unit testing
added documentation and unit test

* Create test_agent_human_input.yaml

add yaml for test

---------

Co-authored-by: João Moura <joaomdmoura@gmail.com>

docs/core-concepts/Tasks.md

@@ -23,6 +23,7 @@ Tasks in CrewAI can be designed to require collaboration between agents. For exa
 | **Output Pydantic**  *(optional)*     | Takes a pydantic model and returns the output as a pydantic object. **Agent LLM needs to be using an OpenAI client, could be Ollama for example but using the OpenAI wrapper** |
 | **Output File**  *(optional)*     | Takes a file path and saves the output of the task on it. |
 | **Callback**  *(optional)*  | A function to be executed after the task is completed. |
+| **Human Input** *(optional)*   |   Indicates whether the agent should ask for feedback at the end of the task |
 
 ## Creating a Task
 
@@ -224,4 +225,4 @@ These validations help in maintaining the consistency and reliability of task ex
 
 ## Conclusion
 
-Tasks are the driving force behind the actions of agents in crewAI. By properly defining tasks and their outcomes, you set the stage for your AI agents to work effectively, either independently or as a collaborative unit. Equipping tasks with appropriate tools, understanding the execution process, and following robust validation practices are crucial for maximizing CrewAI's potential, ensuring agents are effectively prepared for their assignments and that tasks are executed as intended.
+Tasks are the driving force behind the actions of agents in crewAI. By properly defining tasks and their outcomes, you set the stage for your AI agents to work effectively, either independently or as a collaborative unit. Equipping tasks with appropriate tools, understanding the execution process, and following robust validation practices are crucial for maximizing CrewAI's potential, ensuring agents are effectively prepared for their assignments and that tasks are executed as intended.

docs/how-to/Human-Input-on-Execution.md

@@ -1,6 +1,6 @@
 ---
 title: Human Input on Execution
-description: Comprehensive guide on integrating CrewAI with human input during execution in complex decision-making processes or when needed help during complex tasks. 
+description: Comprehensive guide on integrating CrewAI with human input during execution in complex decision-making processes or when needed help during complex tasks.
 ---
 
 # Human Input in Agent Execution
@@ -9,7 +9,7 @@ Human input plays a pivotal role in several agent execution scenarios, enabling
 
 ## Using Human Input with CrewAI
 
-Incorporating human input with CrewAI is straightforward, enhancing the agent's ability to make informed decisions. While the documentation previously mentioned using a "LangChain Tool" and a specific "DuckDuckGoSearchRun" tool from `langchain_community.tools`, it's important to clarify that the integration of such tools should align with the actual capabilities and configurations defined within your `Agent` class setup.
+Incorporating human input with CrewAI is straightforward, enhancing the agent's ability to make informed decisions. While the documentation previously mentioned using a "LangChain Tool" and a specific "DuckDuckGoSearchRun" tool from `langchain_community.tools`, it's important to clarify that the integration of such tools should align with the actual capabilities and configurations defined within your `Agent` class setup. Now it is a simple flag in the task itself that needs to be turned on.
 
 ### Example:
 
@@ -23,14 +23,10 @@ import os
 from crewai import Agent, Task, Crew
 from crewai_tools import SerperDevTool
 
-from langchain.agents import load_tools
-
 os.environ["SERPER_API_KEY"] = "Your Key" # serper.dev API key
 os.environ["OPENAI_API_KEY"] = "Your Key"
 
-
-# Loading Human Tools
-human_tools = load_tools(["human"])
+# Loading Tools
 search_tool = SerperDevTool()
 
 # Define your agents with roles, goals, and tools
@@ -44,7 +40,7 @@ researcher = Agent(
   ),
   verbose=True,
   allow_delegation=False,
-  tools=[search_tool]+human_tools # Passing human tools to the agent
+  tools=[search_tool]
 )
 writer = Agent(
   role='Tech Content Strategist',
@@ -67,6 +63,7 @@ task1 = Task(
   ),
   expected_output='A comprehensive full report on the latest AI advancements in 2024, leave nothing out',
   agent=researcher,
+  human_input=True, # setting the flag on for human input in this task
 )
 
 task2 = Task(

src/crewai/agents/executor.py

@@ -18,6 +18,7 @@
 
 class CrewAgentExecutor(AgentExecutor):
     _i18n: I18N = I18N()
+    should_ask_for_human_input: bool = False
     llm: Any = None
     iterations: int = 0
     task: Any = None
@@ -54,6 +55,9 @@ def _call(
             [tool.name for tool in self.tools], excluded_colors=["green", "red"]
         )
         intermediate_steps: List[Tuple[AgentAction, str]] = []
+        # Allowing human input given task setting
+        if self.task.human_input:
+            self.should_ask_for_human_input = True
         # Let's start tracking the number of iterations and time elapsed
         self.iterations = 0
         time_elapsed = 0.0
@@ -169,8 +173,24 @@ def _iter_next_step(
 
         # If the tool chosen is the finishing tool, then we end and return.
         if isinstance(output, AgentFinish):
-            yield output
-            return
+            if self.should_ask_for_human_input:
+                # Making sure we only ask for it once, so disabling for the next thought loop
+                self.should_ask_for_human_input = False
+                human_feedback = self._ask_human_input(output.return_values["output"])
+                action = AgentAction(
+                    tool="Human Input", tool_input=human_feedback, log=output.log
+                )
+                yield AgentStep(
+                    action=action,
+                    observation=self._i18n.slice("human_feedback").format(
+                        human_feedback=human_feedback
+                    ),
+                )
+                return
+
+            else:
+                yield output
+                return
 
         actions: List[AgentAction]
         actions = [output] if isinstance(output, AgentAction) else output
@@ -203,3 +223,9 @@ def _iter_next_step(
                         tools=", ".join([tool.name for tool in self.tools]),
                     )
             yield AgentStep(action=agent_action, observation=observation)
+
+    def _ask_human_input(self, final_answer: dict) -> str:
+        """Get human input."""
+        return input(
+            self._i18n.slice("getting_input").format(final_answer=final_answer)
+        )

src/crewai/task.py

@@ -70,6 +70,10 @@ class Config:
         frozen=True,
         description="Unique identifier for the object, not set by user.",
     )
+    human_input: Optional[bool] = Field(
+        description="Whether the task should have a human review the final answer of the agent",
+        default=False,
+    )
 
     _original_description: str | None = None
     _original_expected_output: str | None = None

src/crewai/translations/en.json

@@ -15,7 +15,9 @@
     "final_answer_format": "If you don't need to use any more tools, you must give your best complete final answer, make sure it satisfy the expect criteria, use the EXACT format below:\n\nThought: I now can give a great answer\nFinal Answer: my best complete final answer to the task.\n\n",
     "format_without_tools": "\nSorry, I didn't use the right format. I MUST either use a tool (among the available ones), OR give my best final answer.\nI just remembered the expected format I must follow:\n\nQuestion: the input question you must answer\nThought: you should always think about what to do\nAction: the action to take, should be one of [{tool_names}]\nAction Input: the input to the action\nObservation: the result of the action\n... (this Thought/Action/Action Input/Observation can repeat N times)\nThought: I now can give a great answer\nFinal Answer: my best complete final answer to the task\nYour final answer must be the great and the most complete as possible, it must be outcome described\n\n",
     "task_with_context": "{task}\n\nThis is the context you're working with:\n{context}",
-    "expected_output": "\nThis is the expect criteria for your final answer: {expected_output} \n you MUST return the actual complete content as the final answer, not a summary."
+    "expected_output": "\nThis is the expect criteria for your final answer: {expected_output} \n you MUST return the actual complete content as the final answer, not a summary.",
+    "human_feedback": "You got human feedback on your work, re-avaluate it and give a new Final Answer when ready.\n {human_feedback}",
+    "getting_input": "This is the agent final answer: {final_answer}\nPlease provide a feedback: "
   },
   "errors": {
     "unexpected_format": "\nSorry, I didn't use the expected format, I MUST either use a tool (use one at time) OR give my best final answer.\n",

tests/agent_test.py

@@ -681,6 +681,31 @@ def test_agent_definition_based_on_dict():
     assert agent.verbose == True
     assert agent.tools == []
 
+# test for human input
+@pytest.mark.vcr(filter_headers=["authorization"])
+def test_agent_human_input():
+    from unittest.mock import patch
+
+    config = {
+        "role": "test role",
+        "goal": "test goal",
+        "backstory": "test backstory",
+    }
+
+    agent = Agent(config=config)
+
+    task = Task(
+        agent=agent,
+        description="Say the word: Hi",
+        expected_output="The word: Hi",
+        human_input=True,
+    )
+
+    with patch.object(CrewAgentExecutor, "_ask_human_input") as mock_human_input:
+        mock_human_input.return_value = "Hello"
+        output = agent.execute_task(task)
+        mock_human_input.assert_called_once()
+        assert output == "Hello"
 
 def test_interpolate_inputs():
     agent = Agent(
@@ -698,3 +723,4 @@ def test_interpolate_inputs():
     assert agent.role == "Sales specialist"
     assert agent.goal == "Figure stuff out"
     assert agent.backstory == "I am the master of nothing"
+