Research agent

What you'll build

Step-by-step build

1. 1

   Scaffold the app and wire one LLM call

   Create a Next.js app and add a single API route that sends a prompt to Groq and returns the text. Confirm the key works and you get a response before adding any agent logic. This is your baseline; everything else builds on a working model call.

2. 2

   Add the planner

   Prompt the model to turn the topic into 3 to 6 focused sub-questions and return them as a JSON array validated by Zod. Keep the planner separate from the searcher so you can test it alone. A good plan is the difference between a focused report and a rambling one.

3. 3

   Build the search tool

   Wrap a free search API in a function that takes a query and returns titles, snippets, and URLs. A tool is just a function the model is allowed to call with structured arguments. Test it directly with a hardcoded query before letting the model drive it.

4. 4

   Register the tool with the model

   Using the Vercel AI SDK, describe the search tool to the model with a name, a description, and a Zod input schema. Now the model can choose to call it and you run the function on its behalf. Log every tool call so you can see exactly what the agent searched for.

5. 5

   Run the agent loop

   Let the model alternate between calling the search tool and reading results until it decides it has enough. The SDK feeds each tool result back into the conversation automatically. Cap the loop at a maximum number of steps so a confused agent cannot spin forever.

6. 6

   Add the stop condition

   Give the model an explicit instruction to stop searching once each sub-question is answered, then write the report. Combine that soft signal with the hard step cap from the previous step. Knowing when to stop is the skill that separates a real agent from an infinite loop.

7. 7

   Write the cited report

   Prompt the model to synthesize the collected notes into a short report where each claim references the source URL it came from. Reject the answer if it cites a URL that was never fetched. This forces the report to stay grounded in what the agent actually read.

8. 8

   Stream the steps to a UI

   Build a simple page that shows the plan, each search as it happens, and the final report as it streams in. Watching the agent work makes debugging far easier and demos far better. Add a loading state for each step so the UI never looks frozen.

Done when

• ✓Every claim in the final report links to a source the agent actually fetched
• ✓The loop always terminates, either by the stop signal or the step cap
• ✓Asking about an obscure topic yields a short honest report, not padding
• ✓You can read the log and see each sub-question and the search behind it
• ✓Removing the search tool makes the agent say it cannot research, not guess

Ship it

Deploy to Vercel free tier; the streaming API route runs on their edge or serverless functions with no config. Put your Groq and search keys in Vercel environment variables. Write a README that shows a real example topic, the report it produced, and the free-tier limits of each API.

What it proves: Shows you can build an agent loop with real tool calls and keep its output grounded and cited rather than hallucinated.

Paste this into Cursor, Claude, or ChatGPT and build it step by step.

You are my senior AI engineer pair. Help me build "Research agent" step by step. An agent here means an LLM that loops, deciding to call tools until it has enough to answer. Tool-calling means the model asks to run a function and I run it and feed back the result.

Stack: Next.js, Vercel AI SDK 6 for the tool-calling loop and streaming, Groq API for inference, and a free web search API (Tavily or Brave) as the one tool.

Requirements:
1. Take a topic and plan 3 to 6 sub-questions as validated JSON.
2. Expose a web search tool the model can call per sub-question.
3. Run an agent loop with both a stop instruction and a hard step cap.
4. Produce a short report where every claim cites a URL that was actually fetched.
5. Stream the plan, searches, and report to a simple UI.

Work in this order: scaffold and one LLM call, then the planner, then the search tool, then registering it, then the loop and stop condition, then the cited report, then the UI. Give me commands and code for each step and STOP after each so I can test. Do not write the whole app at once.