Skip to content

Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.

docs: add docs about Agent.kickoff usage (#3121)

Lucas Gomidef071966951c4
diff --git a/docs/en/concepts/agents.mdx b/docs/en/concepts/agents.mdx
index b8250f9f9..08691a7b7 100644
--- a/docs/en/concepts/agents.mdx
+++ b/docs/en/concepts/agents.mdx
@@ -526,6 +526,103 @@ agent = Agent(
The context window management feature works automatically in the background. You don't need to call any special functions - just set `respect_context_window` to your preferred behavior and CrewAI handles the rest!
</Note>
+## Direct Agent Interaction with `kickoff()`
+
+Agents can be used directly without going through a task or crew workflow using the `kickoff()` method. This provides a simpler way to interact with an agent when you don't need the full crew orchestration capabilities.
+
+### How `kickoff()` Works
+
+The `kickoff()` method allows you to send messages directly to an agent and get a response, similar to how you would interact with an LLM but with all the agent's capabilities (tools, reasoning, etc.).
+
+```python Code
+from crewai import Agent
+from crewai_tools import SerperDevTool
+
+# Create an agent
+researcher = Agent(
+ role="AI Technology Researcher",
+ goal="Research the latest AI developments",
+ tools=[SerperDevTool()],
+ verbose=True
+)
+
+# Use kickoff() to interact directly with the agent
+result = researcher.kickoff("What are the latest developments in language models?")
+
+# Access the raw response
+print(result.raw)
+```
+
+### Parameters and Return Values
+
+| Parameter | Type | Description |
+| :---------------- | :---------------------------------- | :------------------------------------------------------------------------ |
+| `messages` | `Union[str, List[Dict[str, str]]]` | Either a string query or a list of message dictionaries with role/content |
+| `response_format` | `Optional[Type[Any]]` | Optional Pydantic model for structured output |
+
+The method returns a `LiteAgentOutput` object with the following properties:
+
+- `raw`: String containing the raw output text
+- `pydantic`: Parsed Pydantic model (if a `response_format` was provided)
+- `agent_role`: Role of the agent that produced the output
+- `usage_metrics`: Token usage metrics for the execution
+
+### Structured Output
+
+You can get structured output by providing a Pydantic model as the `response_format`:
+
+```python Code
+from pydantic import BaseModel
+from typing import List
+
+class ResearchFindings(BaseModel):
+ main_points: List[str]
+ key_technologies: List[str]
+ future_predictions: str
+
+# Get structured output
+result = researcher.kickoff(
+ "Summarize the latest developments in AI for 2025",
+ response_format=ResearchFindings
+)
+
+# Access structured data
+print(result.pydantic.main_points)
+print(result.pydantic.future_predictions)
+```
+
+### Multiple Messages
+
+You can also provide a conversation history as a list of message dictionaries:
+
+```python Code
+messages = [
+ {"role": "user", "content": "I need information about large language models"},
+ {"role": "assistant", "content": "I'd be happy to help with that! What specifically would you like to know?"},
+ {"role": "user", "content": "What are the latest developments in 2025?"}
+]
+
+result = researcher.kickoff(messages)
+```
+
+### Async Support
+
+An asynchronous version is available via `kickoff_async()` with the same parameters:
+
+```python Code
+import asyncio
+
+async def main():
+ result = await researcher.kickoff_async("What are the latest developments in AI?")
+ print(result.raw)
+
+asyncio.run(main())
+```
+
+<Note>
+The `kickoff()` method uses a `LiteAgent` internally, which provides a simpler execution flow while preserving all of the agent's configuration (role, goal, backstory, tools, etc.).
+</Note>
+
## Important Considerations and Best Practices
### Security and Code Execution