> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crewship.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Your First CrewAI Crew
> Build and deploy a complete CrewAI crew from scratch
## What We'll Build
A research crew that:
1. Researches a topic using web search
2. Analyzes and synthesizes findings
3. Produces a written report as an artifact
## Prerequisites
* Python 3.11+
* CrewAI installed (`pip install crewai`)
* Crewship CLI installed and authenticated
Want to skip the setup? Clone the [crewai-quickstart](https://github.com/Crewship/crewai-quickstart) repo and run `crewship deploy` to get a working crew deployed in minutes.
## Step 1: Create the Project
```bash theme={null}
# Create a new CrewAI project
crewai create crew research_crew
cd research_crew
```
This creates:
```
research_crew/
├── src/
│ └── research_crew/
│ ├── __init__.py
│ ├── crew.py
│ ├── main.py
│ └── config/
│ ├── agents.yaml
│ └── tasks.yaml
├── pyproject.toml
└── README.md
```
## Step 2: Define Your Agents
Edit `src/research_crew/config/agents.yaml`:
```yaml agents.yaml theme={null}
researcher:
role: Senior Research Analyst
goal: >
Uncover cutting-edge developments and insights about {topic}
backstory: >
You're a seasoned research analyst with a keen eye for emerging trends.
You excel at finding and synthesizing information from diverse sources.
tools:
- SerperDevTool
writer:
role: Technical Content Writer
goal: >
Create engaging, well-structured content about {topic}
backstory: >
You're an experienced technical writer who transforms complex research
into clear, compelling narratives. You write for a technical audience.
```
## Step 3: Define Your Tasks
Edit `src/research_crew/config/tasks.yaml`:
```yaml tasks.yaml theme={null}
research_task:
description: >
Research the topic: {topic}
Find the latest developments, key players, challenges, and future trends.
Focus on credible sources and recent information.
expected_output: >
A comprehensive research brief with key findings, sources, and insights.
agent: researcher
writing_task:
description: >
Write a detailed report based on the research about {topic}.
Structure:
1. Executive Summary
2. Key Findings
3. Analysis
4. Future Outlook
5. Sources
expected_output: >
A well-structured markdown report of 800-1200 words.
agent: writer
output_file: artifacts/report.md
```
Files written to `artifacts/` are collected as run artifacts, accessible via the API and Console.
## Step 4: Configure the Crew
Edit `src/research_crew/crew.py`:
```python crew.py theme={null}
from crewai import Agent, Crew, Process, Task
from crewai.project import CrewBase, agent, crew, task
from crewai_tools import SerperDevTool
@CrewBase
class ResearchCrew:
"""Research crew that produces written reports"""
agents_config = "config/agents.yaml"
tasks_config = "config/tasks.yaml"
@agent
def researcher(self) -> Agent:
return Agent(
config=self.agents_config["researcher"],
tools=[SerperDevTool()],
verbose=True,
)
@agent
def writer(self) -> Agent:
return Agent(
config=self.agents_config["writer"],
verbose=True,
)
@task
def research_task(self) -> Task:
return Task(config=self.tasks_config["research_task"])
@task
def writing_task(self) -> Task:
return Task(config=self.tasks_config["writing_task"])
@crew
def crew(self) -> Crew:
return Crew(
agents=self.agents,
tasks=self.tasks,
process=Process.sequential,
verbose=True,
)
```
## Step 5: Create the Entry Point
Edit `src/research_crew/main.py`:
```python main.py theme={null}
from research_crew.crew import ResearchCrew
def kickoff(inputs: dict) -> str:
"""Entry point for Crewship deployment"""
crew = ResearchCrew()
result = crew.crew().kickoff(inputs=inputs)
return str(result)
# For local testing
if __name__ == "__main__":
result = kickoff({"topic": "AI agents in 2024"})
print(result)
```
## Step 6: Add Dependencies
Ensure `pyproject.toml` includes required packages:
```toml pyproject.toml theme={null}
[project]
name = "research_crew"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
"crewai>=0.80.0",
"crewai-tools>=0.14.0",
]
```
## Step 7: Add Crewship Configuration
Create `crewship.toml` in the project root:
```toml crewship.toml theme={null}
name = "research-crew"
framework = "crewai"
[build]
entrypoint = "research_crew.main:kickoff"
python = "3.11"
[runtime]
timeout = 600
memory = 512
[metadata]
description = "A crew that researches topics and writes reports"
tags = ["research", "writing"]
```
## Step 8: Set Environment Variables
```bash theme={null}
# OpenAI for the LLM
crewship env set OPENAI_API_KEY=sk-proj-...
# Serper for web search
crewship env set SERPER_API_KEY=...
```
## Step 9: Deploy
```bash theme={null}
crewship deploy
```
```
📦 Packaging crew...
☁️ Uploading build context...
🔨 Building image...
✅ Deployed successfully!
Deployment: dep_abc123xyz
Project: research-crew
```
## Step 10: Run Your Crew
```bash theme={null}
crewship invoke --input '{"topic": "quantum computing in 2024"}' --stream
```
Watch the execution:
```
▶ Run started: run_xyz789
├─ [10:30:01] Researcher agent starting task...
├─ [10:30:05] Tool: SerperDevTool("quantum computing breakthroughs 2024")
├─ [10:30:12] Tool: SerperDevTool("quantum computing companies 2024")
├─ [10:30:25] Researcher agent completed task
├─ [10:30:26] Writer agent starting task...
├─ [10:30:58] Writer agent completed task
├─ [10:30:59] Artifact: report.md (3.2 KB)
✅ Run completed in 58.4s
```
## Step 11: Get the Artifact
```bash theme={null}
# List artifacts
crewship runs artifacts run_xyz789
# Download the report
crewship runs download run_xyz789 report.md
```
## Next Steps
Add real-time event handling
Work with run outputs
Build an agent with LangGraph (Python)
Build an agent with LangGraph.js