This is an example agent which performs deep research using Hatchet and OpenAI. While the agent itself is very simple, it is based on best practices that we have observed at Hatchet while executing billions of tasks and agent executions per month. It is intended to be a forkable starting point for agentic ai projects.
Video demo:
Deep_Research_Demo.mp4
What's the purpose of this repository?
This is a starting point for building an agent in your own product -- it is not meant as a replacement for Deep Research.
What is Hatchet?
Hatchet is an orchestration engine which turns functions into durable tasks that execute in parallel on many machines at once, which helps turn your agents from great demos into fast, reliable production code.
Does this use a framework?
We believe the best framework is no framework. See further reading below for more information.
Caution
Running this example is free on Hatchet (below 1000 tasks/day) but will cost money on OpenAI. As this is an unconstrained agent, please make sure you are testing this against a low usage limit.
- Clone the repo:
git clone https://github.com/hatchet-dev/hatchet-typescript-deep-research.git
- Generate a Hatchet API token on Hatchet Cloud (or run Hatchet with docker-compose), along with an OpenAI API key. Paste the following into a
.envfile in the root of this directory:
OPENAI_API_KEY=<your_api_key_here>
HATCHET_CLIENT_TOKEN=<your_hatchet_token>- Install dependencies:
pnpm install- Run the development server:
pnpm dev- Trigger your first deep research execution, which will ask you for a prompt (or select from the list):
pnpm cliThis project is designed as a starting point to build your own agent. The primary entrypoint for the agent can be found in src/agents/deep-research/deep-research.agent.ts. Tasks (also known as tools) for the agent can be found in the tasks folder.
The agent implements the following control loop:
flowchart TD
Start([Start]) --> Input[/User Query/]
Input --> InitVars[Initialize Variables]
subgraph IterationLoop["Iteration Loop (max 3 iterations)"]
InitVars --> PlanSearch[Plan Search: based on query, existing facts, and missing aspects]
PlanSearch -->|x N| SearchQueries[Execute Search Queries]
SearchQueries --> ProcessSources[Process & Deduplicate Sources]
ProcessSources --> |x M| ConvertToMd[Convert Sources to Markdown]
ConvertToMd --> ExtractFacts[Extract Facts from Sources]
ExtractFacts --> JudgeFacts[Judge if Facts are Sufficient]
JudgeFacts --> Decision{Enough Facts or Max Iterations?}
Decision -->|No| UpdateMissing[Update Missing Aspects]
UpdateMissing --> PlanSearch
end
Decision -->|Yes| GenerateSummary[Generate Final Summary]
GenerateSummary --> JudgeResults[Judge Final Results]
JudgeResults --> ReturnResult[Return Result]
ReturnResult --> End([End])
%% Light grayscale fill with dark text
classDef process fill:#f5f5f5,stroke:#24292e,stroke-width:1px,color:#24292e;
classDef decision fill:#eeeeee,stroke:#24292e,stroke-width:1px,color:#24292e;
classDef io fill:#f0f0f0,stroke:#24292e,stroke-width:1px,color:#24292e;
class PlanSearch,SearchQueries,ProcessSources,ConvertToMd,ExtractFacts,JudgeFacts,GenerateSummary,JudgeResults,UpdateMissing process;
class Decision decision;
class Input,ReturnResult io;
To learn more about Hatchet, visit:
To learn more about what informs our agent design and architecture, see: