DEV Community: Prosper Otemuyiwa

Building Multi-Agent Research Systems using Vercel AI SDK

Prosper Otemuyiwa — Fri, 13 Mar 2026 13:26:08 +0000

There are many ways to build apps and systems. In today’s AI-native world, the possibilities are endless.

Now imagine you’re tasked with building a multi-agent research system, with one key requirement: don’t over-engineer it.

KISS — Keep It Simple, Stupid.

This is the scenario given to you:

"A friend asked me to pull together everything on Eli Lilly's Q4 results, any ongoing GLP-1 trials they've filed recently, and how the financial press was covering it. Build a multi-agent research system that handles that so you can go accomplish 10 other things while the system gets you the result."

Now, let’s break this down:

Pull together everything on Eli Lilly’s Q4 results
Identify any GLP-1 trials they’ve filed recently
See how the financial press has been covering it

When broken down like this, it’s simply three queries across three completely different domains: SEC filings, clinical trials, and live news.

Three different tools, three different contexts and then stitching it all together manually at the end. It’s similar to the "15-tab" problem.

And it gets worse when you’re building an AI app. You often end up maintaining a research pipeline that’s just a collection of disconnected scripts, held together by copy-paste.

The Architecture

We have three different contexts, so three domains. We'll use the Vercel AI SDK to handle all three domains in parallel.

One query, three specialist agents running simultaneously, and a single synthesized response. With the @valyu/ai-sdk package, plugging in domain-specific data sources takes just one import—no manual tool definitions required.

This is the architecture: the Orchestrator–Worker pattern.

One orchestrator agent understands the query, dispatches the right specialists in parallel, and synthesizes the results. Each specialist has its own tool suite and domain expertise

The tools come from @valyu/ai-sdk, a package that provides ready-made Vercel AI SDK tools backed by Valyu's search API. No manual tool() definitions, no Zod schemas for parameters, no custom execute functions.

Import the tool, drop it into your tools object, done.

Why Parallel Dispatch Matters

Sequential agents are the wrong default for research workloads. Each specialist takes 4-6 seconds.

Three in sequence is 15+ seconds. Three specialists running simultaneously gets you results in the time it takes the slowest one to finish.

Data Flow: From Query to Report

For a query like "What's Eli Lilly's financial position and do their GLP-1 trials support the revenue projections?":

Setup

Install Nextjs and then add the following packages...

pnpm add ai @ai-sdk/anthropic @valyu/ai-sdk @ai-sdk/react zod valyu-js

Create .env.local:

ANTHROPIC_API_KEY=your_key_here
VALYU_API_KEY=your_key_here

Grab your Anthropic and Valyu API keys.

Both keys are read from environment automatically. @valyu/ai-sdk picks up VALYU_API_KEY without any explicit configuration.

Project structure:

research-nexus/
├── src/
│   ├── agents/
│   │   ├── financial-analyst.ts   # Financial analyst
│   │   ├── scientist.ts  # Scientist
│   │   ├── journalist.ts          # Journalist
│   │   └── orchestrator.ts        # Query router + synthesizer
│   └── app/
│       └── api/
│           └── chat/
│               └── route.ts       # Next.js API route
└── package.json

No lib/ or tools/ directories. The tools come pre-built.

The Specialist Agents

Each specialist is a ToolLoopAgent with domain-specific tools from @valyu/ai-sdk. The agent loop lets the model chain multiple tool calls before returning. Searching SEC filings, then cross-referencing earnings, then adding macro context, all within a single agent invocation.

Financial Analyst

import { ToolLoopAgent } from "ai";
import { anthropic } from "@ai-sdk/anthropic";
import { secSearch, financeSearch, economicsSearch } from "@valyu/ai-sdk";

export const financialAnalystAgent = new ToolLoopAgent({
  model: anthropic("claude-haiku-4-5-20251001"),
  instructions: `You are a senior financial analyst specializing in SEC filings, market data, and economic research.

Your capabilities:
- Search and analyze SEC filings (10-K, 10-Q, 8-K, proxy statements)
- Look up financial data including stock prices, earnings, income statements
- Research economic indicators and macro data

When responding:
- Always cite the specific filing type and date
- Present financial figures clearly with proper formatting
- Highlight key risks, trends, and material changes
- Compare metrics across periods when relevant
- Be precise about numbers — never approximate when exact data is available`,
  tools: {
    secSearch: secSearch({ maxNumResults: 3, responseLength: "short" }),
    financeSearch: financeSearch({ maxNumResults: 3, responseLength: "short" }),
    economicsSearch: economicsSearch({ maxNumResults: 3, responseLength: "short" }),
  },
});

financial-analyst.ts

Scientist

import { ToolLoopAgent } from "ai";
import { anthropic } from "@ai-sdk/anthropic";
import { bioSearch, paperSearch } from "@valyu/ai-sdk";

export const medicalResearcherAgent = new ToolLoopAgent({
  model: anthropic("claude-haiku-4-5-20251001"),
  instructions: `You are a medical and life sciences research specialist with expertise in clinical trials, drug discovery, and biomedical literature.

Your capabilities:
- Search clinical trial databases for trial status, results, and endpoints
- Look up FDA drug labels, approvals, and safety information
- Research biomedical literature from PubMed, bioRxiv, and medRxiv
- Analyze academic papers on drugs, therapies, and medical devices

When responding:
- Always cite trial IDs (NCT numbers), DOIs, or publication references
- Clearly distinguish between preliminary and peer-reviewed findings
- Note the phase of clinical trials and their primary endpoints
- Flag any safety concerns or adverse events mentioned in the data
- Use proper medical terminology but explain it when needed`,
  tools: {
    bioSearch: bioSearch({ maxNumResults: 3, responseLength: "short" }),
    paperSearch: paperSearch({ maxNumResults: 3, responseLength: "short" }),
  },
});

scientist.ts

Journalist

import { ToolLoopAgent } from "ai";
import { anthropic } from "@ai-sdk/anthropic";
import { webSearch } from "@valyu/ai-sdk";

export const journalistAgent = new ToolLoopAgent({
  model: anthropic("claude-haiku-4-5-20251001"),
  instructions: `You are an investigative journalist and news analyst with access to real-time web sources.

Your capabilities:
- Search the web for breaking news and current events
- Find and cross-reference multiple news sources on a topic
- Track developing stories and provide timeline context
- Research background on people, organizations, and events

When responding:
- Always attribute information to specific sources
- Present multiple perspectives when covering controversial topics
- Distinguish between confirmed facts and unverified reports
- Provide publication dates so readers know how current the information is
- Summarize key points clearly, then provide supporting details`,
  tools: {
    webSearch: webSearch({ maxNumResults: 5, responseLength: "short" }),
  },
});

journalist.ts

Three agents, three imports from @valyu/ai-sdk, zero custom tool definitions.

The Orchestrator

The orchestrator handles query classification, parallel dispatch, and synthesis.

import { ToolLoopAgent, tool, stepCountIs } from "ai";
import { anthropic } from "@ai-sdk/anthropic";
import { z } from "zod";
import { financialAnalystAgent } from "./financial-analyst";
import { scientistAgent } from "./scientist";
import { journalistAgent } from "./journalist";

const financialAnalystTool = tool({
  description:
    "Delegate to the Financial Analyst agent for SEC filings, stock data, earnings reports, economic indicators, and financial analysis.",
  inputSchema: z.object({
    task: z.string().describe("The financial research task to complete"),
  }),
  execute: async ({ task }, { abortSignal }) => {
    const result = await financialAnalystAgent.generate({
      prompt: task,
      abortSignal,
    });
    return result.text;
  },
});

const scientistTool = tool({
  description:
    "Delegate to the Scientist agent for clinical trials, drug information, FDA data, biomedical papers, and life sciences research.",
  inputSchema: z.object({
    task: z.string().describe("The medical/life sciences research task to complete"),
  }),
  execute: async ({ task }, { abortSignal }) => {
    const result = await scientistAgent.generate({
      prompt: task,
      abortSignal,
    });
    return result.text;
  },
});

const journalistTool = tool({
  description:
    "Delegate to the Journalist agent for real-time news, current events, breaking stories, and web-based research on any topic.",
  inputSchema: z.object({
    task: z.string().describe("The news/research task to complete"),
  }),
  execute: async ({ task }, { abortSignal }) => {
    const result = await journalistAgent.generate({
      prompt: task,
      abortSignal,
    });
    return result.text;
  },
});

export const orchestratorAgent = new ToolLoopAgent({
  model: anthropic("claude-haiku-4-5-20251001"),
  instructions: `You are a research orchestrator that routes queries to specialized agents.

You have three specialist agents available:
1. **Financial Analyst** — SEC filings, stock data, earnings, financial statements, economic data
2. **Scientist** — Clinical trials, drug discovery, FDA data, biomedical papers
3. **Journalist** — Real-time news, current events, web research

Your job:
- Analyze the user's query and delegate to the right specialist(s)
- For questions that span multiple domains, call multiple agents
- Synthesize results from multiple agents into a coherent response
- If a query doesn't fit any specialist, answer it yourself
- Always be clear about which sources informed your response`,
  tools: {
    financialAnalyst: financialAnalystTool,
    scientist: scientistTool,
    journalist: journalistTool,
  },
  stopWhen: stepCountIs(10),
});

The orchestrator agent acts as a smart router. It receives the user's query, analyzes what domains it touches, and delegates work to the right specialist(s).

It doesn't do the research itself. Instead, it calls one or more sub-agents as tools:

Financial Analyst for SEC/market data,
Scientist for clinical trials and biomedical literature,
Journalist for real-time news.

For cross-domain questions like "How does Eli Lilly's GLP-1 pipeline affect their stock outlook?", it calls multiple specialists in sequence.

Sub-Agents as Tools. Each specialist is a ToolLoopAgent wrapped in a tool() call, which makes it callable by the orchestrator just like any other function.

When invoked, the sub-agent runs its own independent loop, calling Valyu search tools (like secSearch or bioSearch), reading the results, and synthesizing a response.

The sub-agent's final text is returned to the orchestrator as the tool's output.

Loop Control. The stopWhen: stepCountIs(10) on the orchestrator caps it at 10 loop iterations to prevent runaway execution. The sub-agents use the default limit of 20 steps. Within those bounds, each agent is free to make multiple tool calls. For example, the Financial Analyst might search SEC filings first, then cross-reference with earnings data, all within a single invocation before returning its findings.

The API Route

// app/api/chat/route.ts
import { createAgentUIStreamResponse } from "ai";
import { orchestratorAgent } from "@/agents/orchestrator";

export async function POST(request: Request) {
  const { messages } = await request.json();

  return createAgentUIStreamResponse({
    agent: orchestratorAgent,
    uiMessages: messages,
  });
}

For the sake of keeping this post short, here’s the repo: multi-agent-research-sys.

You’ll find all the UI pages there. Clone the project and run it locally to explore the full setup.

Running it

pnpm dev

Output:

User entered query

Result shows up

What `@valyu/ai-sdk` Provides

The package ships ten tools that cover the major research verticals:

Tool	Data Sources
`secSearch()`	SEC 10-K, 10-Q, 8-K filings, EDGAR full-text
`financeSearch()`	Stocks, earnings, balance sheets, insider trades, dividends
`economicsSearch()`	FRED, BLS, World Bank, US government spending
`bioSearch()`	ClinicalTrials.gov, DrugBank, ChEMBL, FDA labels, Open Targets
`paperSearch()`	PubMed, arXiv, bioRxiv, medRxiv, academic publishers
`webSearch()`	Real-time web, news, general content
`patentSearch()`	USPTO, global patent databases
`companyResearch()`	Comprehensive company intelligence
`datasources()`	List available data sources
`datasourcesCategories()`	List available categories

Each tool accepts optional configuration: maxNumResults, relevanceThreshold, includedSources for source-level filtering. All read VALYU_API_KEY from the environment by default.

The difference from web only search matters most for the financial and biomedical agents.

A web search for "Eli Lilly 10-K 2024 risk factors" returns SEO articles about the filing. secSearch() returns the actual filing text.
A web search for "tirzepatide Phase 3 results" returns health news coverage. bioSearch() returns the ClinicalTrials.gov entries and DrugBank compound data.
That's primary source access vs secondary commentary. A meaningful difference for research quality.

Extending the System

Adding a fourth specialist (patents, legal, government) requires:

One agent file importing the relevant @valyu/ai-sdk tools
Adding the new agent to the orchestrator

Ten specialists in parallel takes the same wall-clock time as three.

The full code is on GitHub. Clone, run and explore!

Get a Valyu API key at platform.valyu.ai. $10 free credit, no credit card required.

Perplexity Sonar Alternatives for Developers (2026)

Prosper Otemuyiwa — Tue, 10 Mar 2026 12:13:15 +0000

Quick Answer: The best alternatives to Perplexity Sonar for developers are Valyu (for specialised data access + web search + benchmark-leading accuracy), Linkup (for simple web search with predictable pricing), and Tavily (for LangChain/LlamaIndex-integrated RAG).

For Sonar Deep Research specifically, Valyu's DeepResearch API is the only alternative that matches multi-step research with citations while also accessing full-text SEC filings, PubMed, and academic sources that Sonar cannot reach.

I've been building search-grounded AI apps long enough to have a mental list of the API switches that felt obvious in hindsight. Switching off Perplexity Sonar is near the top.

The Sonar API is a capable product. I'm not here to trash it. But if you've been running a production app on Sonar and you've hit the reliability ceiling, the throttling wall, or the "this thing only knows about public web pages" limit, you're not alone, and there are real alternatives now.

This article covers what Perplexity Sonar actually is (the full product family, not just the consumer chatbot), the documented reasons developers switch, and the concrete alternatives for each use case, including a dedicated section on Sonar Deep Research specifically.

What Perplexity Sonar Actually Is

First: Sonar is Perplexity's API product, not the consumer app.

"Perplexity" and "Sonar" are distinct things. Searching for Perplexity alternatives usually returns lists of consumer chatbots (ChatGPT, Claude, etc.). That's the wrong category if you're building as a developer.

The Sonar API family has five models:

Model	Primary Use	Pricing
sonar	Lightweight Q&A, high-volume	$5/1,000 requests
sonar-pro	Deeper content understanding	$8/1,000 requests + tokens
sonar-reasoning-pro	Enhanced multi-step reasoning	$2/M input, $8/M output
sonar-deep-research	Exhaustive multi-step research reports	$2/M input, $8/M output + $5/1,000 searches + $3/M reasoning tokens

sonar-deep-research runs autonomous multi-step research, searches the web multiple times, reasons over what it finds, produces a comprehensive report. Available via Perplexity API and OpenRouter.

The pricing for Deep Research compounds fast. A request that triggers 30 searches costs $0.15 in search fees alone, before tokens.

Why Developers Are Switching

These are documented complaints from /r/perplexity_ai, /r/AI_Agents, and developer comparisons, not personal opinions.

Reliability. One developer documented 20+ daily API outages with the Perplexity status page showing green the entire time. For a production app, that's not workable. The common workaround is building fallback logic, which defeats the point of paying for a managed API.

Intentional throttling. Linkup documented this in their own comparison: Sonar's API accuracy appears deliberately capped to avoid creating a competitive consumer product. Perplexity's primary business is a consumer chatbot. The API is secondary. The engineering priorities show.

The architecture problem. Sonar uses a /chat/completions endpoint, the same pattern as LLM chat APIs. Every API call forces a full text generation. If you only want source URLs for a RAG pipeline, you still pay for a generated answer. For developers who want to control the generation step themselves (use Claude or GPT-4 for generation, use search just for retrieval), this creates a wasteful and expensive architecture.

Linkup measured this...The unpredictability in output token length (ranging from 4 to 340,000 tokens) makes cost-per-query essentially impossible to forecast.

Web-only. This is the hard ceiling. Sonar searches the public web. That's it. No SEC filings, no PubMed, no academic journals, no ChEMBL compound databases, no FRED economic data. If you're building financial analysis tools, biomedical research assistants, or anything that requires authoritative data that lives behind institutional barriers, Sonar hits a wall.

The $5 Pro plan trap. Many developers sign up for Perplexity Pro at $20/month expecting meaningful API access. The Pro plan includes $5/month in API credits. That's roughly 1,000 standard queries at low search depth. A heavy testing session can burn through it in hours.

Alternatives for Standard Sonar Use Cases

Valyu DeepSearch API

The most differentiated option in this category, specifically because it goes beyond web search.

Valyu's DeepSearch API gives you a single endpoint that searches the public web AND 36+ specialised data sources; SEC 10-K, 10-Q, 13F, 13D, 13G filings with full-text search, PubMed and bioRxiv research papers, ChEMBL bioactive compounds, academic journals, FRED and BLS economic data, clinical trials, patent databases.

For developers building anything that needs financial data, biomedical research, academic content, or economic indicators, this is the alternative that actually solves the problem. Sonar doesn't provide reliable data in many of these areas.

On raw web search accuracy, Valyu benchmarks at 79% on FreshQA (600 time-sensitive queries) versus Sonar's architecture which relies on Perplexity's indexed web.

On finance-specific questions, Valyu scores 73% vs Google's 55%.

from valyu import Valyu

client = Valyu(api_key="your-api-key")

# Search web + SEC filings + economic data in one call
response = client.search(
    query="What risk factors did Apple disclose in their most recent 10-K?",
    search_type="all", # web + proprietary
    max_num_results=10
)

print(response)

The MCP server integration means it drops into Claude Desktop, Cursor, and other MCP-compatible tools with zero additional code. Native Vercel AI SDK and LangChain integrations exist.

Platform: platform.valyu.ai | Docs: docs.valyu.ai | Free $10 credit on signup.

Best for: Developers who need specialised data (financial, biomedical, academic, economic) or who want benchmark-leading accuracy on time-sensitive and domain-specific queries.

Linkup

Linkup's pitch is architectural clarity. They expose a dedicated /search endpoint with an outputType parameter, you specify whether you want search_results (clean JSON of sources), answer (generated text), or structured (custom JSON schema). This is fundamentally different from Sonar's chat completion approach.

Pricing is transparent and flat: standard search at €5/1,000 queries, deep search at €50/1,000 queries. No token variability. On SimpleQA benchmarks, Linkup hit 91% vs Sonar's 77.3%.

The one limitation: Linkup is web-only. No specialised data access.

Best for: Developers who want predictable pricing and architectural control over the search/generation split.

Tavily

They are one of the most commonly used search APIs in the LangChain/LlamaIndex ecosystem. Tavily's biggest advantage is installation friction: if you're building a LangChain agent, Tavily is a one-liner. The free tier (1,000 credits/month) is generous enough for development.

Performance is solid. Pricing: $0.008/credit pay-as-you-go, Monthly plans start around $30/month for ~4,000 credits.

Best for: RAG pipelines built on LangChain or LlamaIndex where developer experience and quick integration matter more than maximum accuracy.

Alternatives for Sonar Deep Research Specifically

sonar-deep-research occupies a specific niche: multi-step autonomous research that produces comprehensive reports, not just answers. The use case is different from standard search. You're asking it to do what a human researcher would do over an hour, not just answer a question.

The key question is what you actually need from a deep research API:

Multi-step search execution (runs multiple queries, synthesizes results)
Citations and source references in the output
Access to authoritative data sources, not just indexed web pages
Structured output or webhook support for long-running tasks

On criteria 1, 2, and 3, Valyu's DeepResearch API is the only alternative that matches sonar-deep-research functionally while expanding what it can do.

# Valyu DeepResearch - multi-step autonomous research
# with access to SEC filings, PubMed, academic journals

from valyu import Valyu

client = Valyu(api_key="YOUR_API_KEY")

# Create an async DeepResearch task
task = client.deepresearch.create(
    query="Analyze the financial health of Tesla based on recent SEC filings and analyst sentiment",
    mode="standard",  # also supports: "fast", "heavy", "max"
    output_formats=["markdown"],
    search={
        "search_type": "proprietary",
        "included_sources": ["finance", "academic"]
    }
)

if task.success:
    print(f"Task created: {task.deepresearch_id}")

    # Wait for completion with progress updates
    result = client.deepresearch.wait(
        task.deepresearch_id,
        on_progress=lambda s: print(f"Status: {s.status}")
    )

    if result.status == "completed":
        print(result.output) # markdown report
        print(result.sources)  # cited sources with URLs
        print(result.cost) # fixed task cost

The difference that matters for serious use cases: when Sonar Deep Research researches "clinical trial outcomes for GLP-1 receptor agonists," it's searching whatever's publicly indexed on the web. When Valyu DeepResearch does the same query, it's searching PubMed, ClinicalTrials.gov, FDA drug labels, ChEMBL, and Open Target where the actual source databases where this research lives.

For financial research: Valyu reads the actual 10-K filings, earnings transcripts, and insider trading data. Sonar reads articles about those filings.

Pricing comparison for deep research:

Product	Per Request Cost	Data Sources	Output
Sonar Deep Research	$2/M input + $8/M output + $5/1,000 searches + $3/M reasoning tokens	Public web only	Markdown report
Valyu DeepResearch (fast)	$0.10	Web + 36+ specialised sources	Markdown, PDF, JSON
Valyu DeepResearch (standard)	~$1-3	Web + 36+ specialised sources	Markdown, PDF, JSON
Valyu DeepResearch (max)	$15.00	Web + 36+ specialised sources	Markdown, PDF, JSON, Excel

Valyu also supports webhooks (for async long-running tasks), file analysis, and follow-up instructions, features the Sonar Deep Research endpoint doesn't offer.

Head-to-Head Comparison Table

	Perplexity Sonar	Valyu DeepSearch	Linkup	Tavily
Web search	Yes	Yes	Yes	Yes
Proprietary data	No	36+ sources	No	No
FreshQA accuracy	Not published	79%	Not published	Not published
SimpleQA accuracy	77–86%	94%	91%	Not published
Dedicated search endpoint	No (/chat only)	Yes	Yes	Yes
MCP integration	No	Yes	No	No
LangChain integration	Limited	Yes	Yes	Yes (native)
Webhooks	No	Yes (DeepResearch)	No	No
Predictable pricing	No (token-variable)	Yes	Yes	Yes
Deep research mode	Yes (sonar-deep-research)	Yes (DeepResearch API)	Yes (deep search)	No
Entry price (web search)	$5/1,000 requests	Free $10 credit	€5/1,000 queries	Free 1k credits/mo

Which Alternative for Which Use Case

Building a RAG pipeline on LangChain/LlamaIndex?
Start with Tavily. It's the path of least resistance and performs well. If you hit accuracy issues or need data beyond the public web, move to Valyu.

Building anything that touches financial data?
Valyu. SEC filings, earnings data, stock prices, FRED economic data, balance sheets, insider trading, all in one API call. No other search API comes close for this use case.

Building biomedical or clinical research tools?
Valyu. PubMed, bioRxiv, ClinicalTrials.gov, ChEMBL, DrugBank, Open Targets, FDA drug labels. The Bio app (310 GitHub stars) is a live demo of what's possible.

Need multi-step autonomous research (replacing sonar-deep-research)?
Valyu DeepResearch API. It's the only deep research API that combines multi-step synthesis with access to authoritative specialised databases, plus structured output formats and webhook support.

Pure web search with transparent pricing, no specialised data needed?
Linkup for pricing predictability.

A Note on What Sonar Does Well

Sonar has strong developer documentation, an OpenAI-compatible API format that makes migration easy, and solid performance for general web Q&A tasks. The sonar-reasoning-pro model is genuinely useful for chain-of-thought web-grounded reasoning.

The limitations documented here are real, but they're architectural constraints that come from being a secondary product of a consumer AI company, most likely not signs of bad engineering. If your use case is pure web Q&A at scale and you're happy with the public web as your data universe, Sonar is a viable choice.

The alternatives above exist for when those constraints become blockers.

FAQ

What is the best alternative to Perplexity Sonar API?
Valyu DeepSearch for developers who need specialised data access (finance, biomedical, academic) or benchmark-leading accuracy. Linkup for predictable pricing and architectural control. Tavily for the fastest LangChain/LlamaIndex integration.

What is the best alternative to Perplexity Sonar Deep Research?
Valyu's DeepResearch API is the only alternative that matches sonar-deep-research on multi-step research synthesis while also accessing SEC filings, PubMed, academic journals, and clinical trial data that Sonar cannot reach.

Is Perplexity Sonar web-only?
Yes. All Sonar models (Sonar, Sonar Pro, Sonar Reasoning, Sonar Reasoning Pro, Sonar Deep Research) search only the public web and Perplexity's index. They have no access to SEC filings, academic databases, clinical trials, or other specialised data sources.

Why is Sonar API unreliable?
Perplexity's primary product is a consumer chatbot. The API is a secondary product. Developer forums document 20+ daily outages with no reflection on the official status page. The API capacity and reliability engineering reflects these priorities.

Does Perplexity Sonar have an MCP integration?
Yes. Sonar offers a Model Context Protocol server. Valyu also does. It can be added to Claude Desktop, Cursor, and other MCP-compatible environments with one command: npx skills add valyuAI/skills.

How does sonar-deep-research pricing work?
Sonar Deep Research charges $2/million input tokens, $8/million output tokens, $5 per 1,000 searches (a single request might trigger 30 searches = $0.15 in search fees alone), and $3/million reasoning tokens. The total cost per request is hard to predict and can range significantly based on query complexity.

What is AI Search?

Prosper Otemuyiwa — Wed, 04 Mar 2026 12:10:07 +0000

A developer's guide to understanding AI-native search, how it works, what separates the good from the bad, and what to actually check before picking a provider.

Quick answer: AI search is the ability for an AI system to query external information sources at runtime and retrieve actual content. Not just links, not summaries of summaries, but real data. Without it, an LLM is limited to whatever it saw during training. With it, an LLM can answer questions about earnings calls filed yesterday, drug interactions from the latest clinical trial, or stock prices from three hours ago.
AI search is to an LLM what the internet is to a knowledge worker. It's not optional infrastructure.

Why AI Agents Need Search
AI-Native Search vs Traditional Keyword Search
The Five Things That Need to Be First-Class
- Breadth: Web + Proprietary Sources
- Depth: Content, Not Links
- Freshness: Real-Time, Not Stale Caches
- AI-Native Query Understanding
- LLM Integration: First-Class, Not Bolted On
The Evaluation Checklist
The Good, and the Bad
Benchmark Reality Check
FAQ

Why AI Agents Need Search

Think about what makes a human researcher effective. It is not just memory, it is the ability to go look things up.

A doctor does not rely purely on what they memorized in medical school. They check UpToDate, PubMed, current prescribing guidelines.

A financial analyst does not rely on their training data. They pull the latest 10-K, check earnings transcripts, cross-reference FRED data, check stocks daily.

LLMs face the same constraint. GPT-4o was trained on data with a cutoff. Same with Claude and Gemini. Every model's knowledge stops somewhere. This creates three categories of failure:

Staleness: Asking about anything that changed after the training cutoff returns either a wrong answer or a hedge ("I don't have information beyond...").
Hallucination at the edges: When a model is uncertain, it sometimes fills the gap with plausible-sounding fiction. Real-time retrieval with citations is the structural fix for this.
Coverage gaps: Training data is biased toward publicly crawlable content. SEC filings, paywalled research papers, proprietary financial data, clinical trial databases, most of the professional information infrastructure does not end up in training data at useful fidelity.

Search solves all three. Not by making the model smarter in the abstract, but by giving it access to ground truth at query time.

The pattern that works: LLM receives a question, determines it needs external data, calls a search tool, retrieves real content, reasons over that content, returns a grounded answer with citations. This is the architecture that drives production AI applications in finance, healthcare, legal, transportation and research today.

AI-Native Search vs Traditional Keyword Search

This distinction matters more than most developers realize when they first start building.

Traditional search: The kind behind every enterprise search box built in the past decade and more. It operates on keyword matching. You construct a query like cancer AND (immunotherapy OR checkpoint inhibitor) NOT pediatric and get documents that contain those terms. This works for humans who have time to iterate on queries, scan results, and synthesize across ten browser tabs.

If you have spent any time doing serious research on Google, you know the tricks that have accumulated over the years: site:gov filetype:pdf to find government PDFs, intitle:"annual report" "2024" to find exact-title matches, "exact phrase" -exclusion to filter noise, after:2024-01-01 to constrain by date, or related:competitor.com to find similar sites. Power users have entire mental libraries of these operators. I became an expert at these tricks. Some queries end up looking like:

"PFAS contamination" site:epa.gov OR site:atsdr.cdc.gov filetype:pdf after:2023-01-01 -"press release"

This is not a quirk. It is part of the fundamental design. Google was built for humans who can iteratively refine, scan results, and make judgment calls about relevance. The operator syntax is the escape hatch that power users reach for when natural language search fails them.

AI agents do not work like that. They work like this:

"Get me the stock price of Tesla over the last 30 days"

"What did Pfizer's CFO say about margins in their most recent earnings call?"

"Which clinical trials are currently recruiting for NASH treatment in the US?"

"Get me the rulings and judgements about insider trading that happened in the past 20 days"

These are natural language questions. They imply intent. They require the search layer to understand that "last 30 days" means a dynamic date range, that "earnings call" means looking at SEC filings or earnings transcripts, that "currently recruiting" means filtering on trial status.

An LLM generating a Google query has to translate intent into operator syntax before it can search and then translate SERP results back into content before it can reason. Every translation step introduces error.

An LLM that generates NASH clinical trials recruiting site:clinicaltrials.gov might get results, or it might not, depending on how clinicaltrials.gov structures its content for Google's crawler. The search layer is working against the LLM, not with it.

An AI-native search system handles this natively. You pass natural language, the kind of query an LLM would generate, and the search layer handles the translation to underlying sources, retrieves actual content (not a list of URLs), and returns that content in a format the LLM can reason over directly.

The shift from keyword search to AI-native search is roughly similar to the shift from SQL to natural language database queries. The interface changes, the underlying capability requirements change, and the failure modes change completely.

The Five Things That Need to Be First-Class

When evaluating an AI search provider, five things matter enough that weakness in any one of them might be a dealbreaker for serious use cases.

1. Breadth: Web + Proprietary Sources

Most AI search APIs search the web. That is the table stakes. What separates research-grade search from ordinary search is proprietary source coverage.

The information that actually matters in professional contexts is mostly not just sitting on the open web:

Financial research: SEC filings (10-Ks, 10-Qs, 8-Ks), earnings transcripts, balance sheets, insider trading disclosures - these are on EDGAR but require structured access to be useful for AI
Biomedical research: PubMed, bioRxiv, medRxiv, clinical trial registries, ChEMBL's 2.5 million bioactive compounds, DrugBank, FDA drug labels
Academic research: Full-text multimodal search over ArXiv, PubMed, BioRxiv, MedRxiv, and more. The actual papers, not just the abstracts
Economic data: FRED (Federal Reserve Economic Data), BLS statistics, World Bank indicators
Legal and regulatory: Patent databases, SEC enforcement actions, legislation

But public databases are only part of the picture. The other category of proprietary data is internal, and it is often where the highest-value information lives.

A mid-size law firm's decades of case notes, client briefs, and research memos.
A pharmaceutical company's internal compound testing database that has never been published.
A logistics company's shipment history and carrier performance data. An enterprise sales team's CRM notes and deal history. None of this is on the open web. None of it is in any public database.

But all of it is the kind of context that makes AI responses actually useful for the people inside those organizations.

The right AI search architecture can be plugged into these internal sources too: vector databases, document stores, internal wikis, SQL databases, proprietary APIs.

The more sources a search layer can reach, the more complete its picture of the world. An AI assistant that can simultaneously search PubMed, a biotech company's internal research database, and the latest FDA filings delivers fundamentally different answers than one that is web-only.

This is the compounding advantage of breadth: each additional source does not just add coverage, it adds the ability to cross-reference. "Find mentions of compound X across our internal trial data, published literature, and competitor patent filings" requires all three sources to be reachable in one query. Web-only search makes that impossible by design.

When evaluating breadth, ask specific questions:

Which proprietary sources are integrated, and what is the specific dataset (not just "financial data" but "SEC 10-K filings with full text including MD&A sections")?
Are academic papers full-text or abstract-only?
How many data sources are covered, and can you filter by source type in a single API call?
Does the provider support connecting to custom internal sources, and through what mechanism?

Web-only providers and most of the market is web-only will fail any use case that requires professional-grade data, internal knowledge, or cross-source synthesis.

2. Depth: Content, Not Links

This is the difference between a search API and a web search API wrapper.

A web search wrapper returns a list of URLs with snippets. The LLM then has to decide which links are worth following, potentially trigger additional API calls to retrieve content, and synthesize across multiple round trips. This is slow, expensive, and introduces noise.

AI-native search returns content directly. When you query for "Moderna's RNA platform approach in their 2024 10-K," you should get the actual text from that document, the specific section about their RNA platform, not just a URL to EDGAR where you could theoretically find that document.

Depth also means content quality. The raw HTML of most financial documents is a mess. PDFs are worse. A good search provider handles extraction, normalization, and structuring as part of the retrieval pipeline. You get clean, LLM-ready text, not a soup of HTML tags and formatting artifacts.

Depth indicators to check:

Does the API return full document content or snippets?
What is the content extraction quality on complex document types (PDFs, tables, structured financial data)?
What is the maximum content length per result?
Is there a content extraction endpoint that works separately from search?

3. Freshness: Real-Time, Not Stale Caches

This is where the difference between providers becomes visible in production.

Heavy crawl caching was a reasonable approach for search engines built for human consumption. If a document was crawled three weeks ago, that is probably fine for general-purpose search. For AI agents operating in time-sensitive contexts, it is a critical failure mode.

A recruiter using an AI research tool should not discover that the candidate's current employer is wrong because the AI's search layer cached their LinkedIn profile three months ago. A financial analyst querying recent news should not get results from last month because the search provider's crawl queue is backed up.

The worst pattern is a search provider that advertises "live search" but performs live crawls only as a fallback when the cached version is stale by their internal definition. The result is non-deterministic freshness: sometimes you get today's data, sometimes you get data from three weeks ago, and you cannot tell which you are getting without manual verification.

Real freshness requirements:

News and market data: Minutes, not hours
SEC filings: EDGAR indexes within 5-10 minutes of filing; your search should reflect this
Clinical trial registries: Updates happen continuously. Staleness of more than 24 hours affects research validity
Web content: Varies by use case, but the provider should give you visibility into crawl timestamps

When evaluating a provider's freshness claims, ask for documentation of their crawl frequency and caching policy. Ask whether their "live crawl" option is reliable or an unreliable fallback. Run the same query twice on the same day with different time stamps in the query, and check whether results change.

4. AI-Native Query Understanding

The query interface is the developer experience.

Legacy search APIs require you to construct the query in a format the search engine understands: keyword boolean syntax, specific field names, structured filters. You have to translate the user's intent into the search system's dialect before you can use it.

AI-native search inverts this. You pass natural language, and the search layer handles the translation to underlying sources. This matters across every vertical:

Finance: "What did Tesla's management say about gross margin pressure in the last two earnings calls?" should route to earnings transcripts and SEC filings, not a news summary blog.

Biomedical: "Recent studies on CRISPR off-target effects in vivo" should pull from PubMed and bioRxiv, ranked by recency and citation weight.

Legal: "UK court precedents on contractor misclassification in the gig economy since 2020" should pull from case law databases with correct jurisdictional filtering, not general web results that might cite the wrong legal system or be two years out of date.

Shipping and logistics: "Current Suez Canal transit delays for container ships" should route to live maritime tracking data, port authority feeds, and recent news, not a Wikipedia article about the 2023 blockage.

Prediction markets: "Current odds on the next Federal Reserve rate decision across Polymarket and Kalshi" should pull from those specific markets with live contract prices, not a news article from last week speculating about what the Fed might do.

Each of these queries contains implicit routing logic: which sources are relevant, what time frame applies, what the user actually means by vague terms like "recent" or "current." AI-native search handles this inference layer so the LLM does not have to.

Semantic understanding also matters for result ranking. A keyword search for "risk factors" returns documents containing the phrase "risk factors."

A semantically-aware search returns documents that discuss risk even if the exact phrase does not appear because the model understands that "material uncertainty," "contingent liabilities," and "regulatory exposure" are semantically proximate to the concept of risk.

Test this concretely: Give a provider three natural language queries you would realistically generate from an LLM tool call. Evaluate whether the results are actually what those queries mean, not just documents that contain the keywords.

5. LLM Integration: First-Class, Not Bolted On

How the search API integrates into your AI stack determines the actual developer experience.

First-class integration means:

Tool/function calling format: The API should work as a native tool in OpenAI, Anthropic, and other LLM tool-use patterns. You define the tool once and the LLM decides when to call it and what to pass.
Framework support: LangChain, LlamaIndex, Vercel AI SDK, CrewAI - Your search provider should be a first-class citizen in whichever orchestration layer you use. Not a custom wrapper you have to maintain.
MCP support: Model Context Protocol is now the standard for LLM-to-tool communication. A provider without MCP support adds friction for Claude and Cursor users.
Streaming: For real-time interfaces, the ability to stream results as they arrive matters for perceived performance.
Structured outputs: The LLM often needs search results in a specific schema. Can the search provider return structured JSON directly, or do you have to parse raw text in your application layer?

Bolted-on integration looks like this in practice:

A REST API that returns a single blob of text with no schema, so you have to write custom parsing logic in your application to extract titles, URLs, content, and timestamps separately.
No official SDK or not enough SDKs. You are writing raw HTTP requests or maintaining your own wrapper library that breaks every time the provider changes their response format.
Documentation that shows Python examples only, nothing for TypeScript or Go, and the Python examples use requests instead of an official client.
MCP support that is "in beta" with no ETA, forcing you to write a custom MCP server adapter.
No streaming support, so your UI freezes for 3-5 seconds on every search call while waiting for the full response.
LangChain integration that exists as a third-party community package maintained by one person, not the search provider.
No tool-use JSON schema provided, meaning you have to write your own OpenAI function definition and hope it matches what the API actually accepts.
Rate limit errors that return HTTP 200 with an error field in the body instead of HTTP 429, breaking standard retry logic.
Pagination that requires stateful session tokens the LLM cannot manage across tool calls.

The cumulative effect of bolted-on integration is that you spend engineering time maintaining glue code rather than building your product. This is the quiet cost that does not show up in a pricing comparison but adds up to weeks of engineering time at scale.

The Evaluation Checklist

Use this when running a structured evaluation of AI search providers:

Data Coverage

[ ] Web search included (table stakes)
[ ] Which proprietary sources are included, listed specifically, not categorically
[ ] Full-text access to academic papers (not just abstracts)
[ ] Financial data: SEC filings, earnings, market data
[ ] Biomedical: PubMed, clinical trials, compound databases
[ ] Can you filter by source type in a single API call?
[ ] Does the provider support connecting to internal/custom data sources?

Content Quality

[ ] Returns full document content, not just URLs or snippets
[ ] Clean extraction from PDFs and structured documents
[ ] Table and structured data handling
[ ] Configurable result length

Freshness

[ ] Documented crawl frequency per source type
[ ] Time-to-index for SEC filings (should be under 30 minutes)
[ ] News freshness (should be under 5 minutes for major events)
[ ] No silent caching that makes freshness non-deterministic

Query Interface

[ ] Natural language queries work without manual keyword construction
[ ] Semantic ranking, not just keyword matching
[ ] Handles multi-part queries correctly

Integration

[ ] Official SDK for your language
[ ] LangChain / LlamaIndex integration
[ ] Vercel AI SDK tool integration
[ ] MCP server support
[ ] Streaming support

Reliability and Pricing

[ ] SLA with documented uptime
[ ] Pricing is per-result, not per-request (so you pay for what you get)
[ ] Rate limits are documented and sufficient for your use case
[ ] Transparent pricing for proprietary vs web content

The Good, and the Bad

The Good

Unified search across heterogeneous sources. The right architecture gives you a single API call that can query the web, SEC filings, PubMed, and FRED economic data simultaneously. Your LLM does not need to know which source to use for which question. The search layer figures that out. This is transformative for building research agents: instead of wiring together five different data source integrations, you have one.

Grounded answers that cite sources. When search results are the context for LLM reasoning, the LLM can cite its sources. This changes the trust model completely. A financial analyst can see not just the answer but the specific 10-K paragraph that supports it. A doctor can see which PubMed study the recommendation came from. Grounded answers are auditable; pure LLM answers are not.

Real-time awareness. An LLM with search access is always current. It does not need to be retrained to know about yesterday's earnings call or last week's FDA ruling. This decouples knowledge currency from model versioning, which is a significant architectural win.

Reduced hallucination on factual claims. Hallucinations happen most often when the model is uncertain. It generates confident rubbish. Real-time retrieval gives the model ground truth to reason over rather than forcing it to infer from training data. Benchmark data consistently shows that retrieval-augmented generation outperforms pure LLM generation on factual tasks: 79% accuracy on FreshQA for top-tier AI search vs 39% for Google's standard search.

The Bad

Latency. Search adds round-trip time to every query that requires it. A tool call to retrieve content and return it to the LLM typically adds 1-5 seconds depending on source and query complexity. For real-time interfaces, this is noticeable. Deep research workflows that chain multiple search calls can take 30+ seconds. You need to architect around this with streaming, async patterns, and user feedback mechanisms.

Cost accumulation. At scale, search costs add up quickly. Pricing models vary significantly across providers: some charge per request, some per result, some per character of content returned. A single complex research query that touches multiple sources can cost more than you expect if you have not modeled your usage carefully. Price per 1,000 web searches ranges from $1.50 to $15+ depending on the provider and mode.

Result noise. No search system has perfect precision. At high recall settings, you get relevant results but also irrelevant ones. The LLM then has to distinguish signal from noise in its context window and a bloated context with irrelevant content can actually degrade answer quality. Good search configurations tune precision and recall for the specific use case.

Over-reliance on search. Building an AI system that calls search for every query is not always the right architecture. Some queries are better answered from a fine-tuned model or a curated knowledge base. The skill is knowing when to retrieve and when to rely on the model's parametric knowledge. Indiscriminate search adds latency and cost without improving quality for questions the model already knows well.

Benchmark Reality Check

Here is how top AI search providers perform on standardized benchmarks as of early 2026:

Benchmark	Valyu	Parallel	Exa	Google
FreshQA (600 time-sensitive queries)	79%	52%	24%	39%
SimpleQA (4,326 factual questions)	94%	93%	91%	38%
Finance (120 finance questions)	73%	67%	63%	55%
Economics (100 economics questions)	73%	52%	45%	43%
MedAgent (562 complex medical queries)	48%	42%	44%	45%

A few things worth noting here:

The FreshQA gap between Exa (24%) and top-performing providers (79%) is not a minor implementation difference. It is a fundamental architectural difference in how freshness is handled. Exa's neural search model is built on a large cached index, which delivers excellent semantic relevance on older content but fails on time-sensitive queries. This is a known tradeoff they have publicly acknowledged.

The SimpleQA results show that most providers cluster between 91-94% on factual retrieval tasks. The floor drops significantly for Google (38%) because standard Google search is optimizing for human page-browsing behavior, not LLM-ready content delivery.

Finance and economics benchmarks show the clearest differentiation, because these domains require proprietary source access that web-only providers do not have. A provider that scores 55% on finance questions versus 73% is not just slower, it is genuinely missing data that lives in structured financial databases rather than on the open web.

FAQ

What is the difference between AI search and RAG?

RAG (Retrieval-Augmented Generation) is the broader pattern: retrieve relevant content, add it to the LLM's context, generate an answer. AI search is one implementation of the retrieval component. You can do RAG with a vector database of your own documents, with a search API, or with both. AI search APIs are the external retrieval component, they give your LLM access to content beyond whatever you have locally indexed.

Can AI search replace fine-tuning?

For knowledge tasks, often yes. Fine-tuning embeds knowledge into model weights, which makes it fast to retrieve but expensive to update. Search retrieves knowledge at query time, which is slower but always current. For a financial assistant that needs to know about last week's earnings call, search is the right tool. For a coding assistant that needs to know your internal coding conventions, fine-tuning or RAG on your codebase is better. Most production systems use both.

Why not just use Google Search via the API?

Google's Search API returns links and snippets optimized for human web browsing. It does not return full content. It does not cover proprietary databases. It scores 39% on FreshQA despite being the most-crawled index on earth, because its content format and coverage gaps make it poorly suited to LLM context injection. Google is excellent at finding web pages that humans then read. It is not designed for the LLM use case of retrieving ground-truth content for reasoning.

What does AI-native search actually mean?

It means the search system is designed from the ground up for the query patterns and consumption patterns of AI systems (AI agents, apps, etc) not human users.

Key differences: Natural language queries without keyword syntax, content returned directly rather than URLs to browse, results formatted for LLM context windows, source diversity beyond the open web, and integration patterns (tool calling, MCP, SDK) that fit AI agent architectures.

How do I handle freshness requirements in production?

First, check timestamp metadata on every search result and log it. This gives you visibility into actual freshness rather than relying on provider claims.
Second, separate your use cases by freshness requirement: some queries can tolerate cached results (what is the history of X?), others cannot (what is the current price of X?).

What is the right number of search results to pass to an LLM?

For most use cases: 3-5 results for single-shot Q&A, 10-15 for research tasks that need broad coverage, 1-2 for fact lookup where precision matters more than recall. The tradeoff is context window cost (more results = more tokens = more cost and potentially degraded coherence) vs recall (fewer results = risk of missing the relevant content). Test empirically on your domain rather than using defaults.

Should I build my own search infrastructure or use an API?

For domain-specific corpora you own (internal documents, proprietary databases), build or buy a specialized solution.
For external information access: Web, SEC filings, academic papers, market data, building your own infrastructure means managing crawl infrastructure, database partnerships, content licensing, and extraction pipelines. This is a multi-year engineering effort. Use an API unless search is literally your core product.

What questions should I ask a search provider before signing a contract?

What is your exact crawl frequency for [specific source category relevant to my use case]?
Do you have direct database integrations with [specific databases] or do you scrape the web versions?
What is the maximum content length I can retrieve per result?
What is your SLA and what are the remedies if you miss it?
How are proprietary source costs priced? Per retrieval, per query, or per subscription?

Deep Research API for AI Agents: The Complete Guide (2026)

Prosper Otemuyiwa — Mon, 02 Mar 2026 18:24:14 +0000

I spent three days testing every deep research API I could find. OpenAI's. Perplexity's. Exa's. Parallel's. Gemini's.

They all have the same blind spot: they only search the web.

If your AI agent needs to cross-reference a drug trial with a bioRxiv preprint, or analyze a company's 10-K risk factors alongside FRED economic data, or map a patent landscape against recent academic research, web-only search might not get you there. The data you need most likely isn't indexable by Google or crawlable by search bots.

This guide covers what a deep research API actually is, how the major options compare, and how to build AI agents that can reach proprietary data sources: SEC filings, PubMed, clinical trials, patents in a single API call.

Note: All examples are shown in both Python and TypeScript. Non-developers stay tuned, there's also something for you! 😉

What Is a Deep Research API?

A deep research API is a programmatic interface that performs multi-step, autonomous research on behalf of an AI agent. Unlike a standard search API that returns a list of results, a deep research API:

Plans a research strategy from a query
Executes multiple searches across sources
Reads, synthesizes, and cross-references retrieved content
Returns a structured report with citations

The term entered mainstream usage after OpenAI launched their "deep research" feature in February 2025. Since then, every major AI company has shipped a version. For developers building AI agents, the question isn't whether to use one, it's which one reaches the data you actually need.

Key factors when evaluating a deep research API:

Data source coverage (web-only vs. proprietary databases)
Output formats (markdown, PDF, structured JSON)
The ability to handle deliverables
Async handling (how long tasks run, webhook support)
Pricing model (per task vs. per retrieval)
Benchmark accuracy on domain-specific queries

The Deep Research API Landscape in 2026

Here's what's actually ranking when you search "deep research API" and what each tool can and can't reach:

API	Data Sources	Output Formats	Best For	Pricing
OpenAI Deep Research	Web (Bing)	Text	General research, broad questions	o3: ~$10-30/call ($10/M in, $40/M out); o4-mini: ~$1-3/call ($2/M in, $8/M out)
Perplexity Deep Research	Web	Text	Quick cited answers	Free tier + Pro $20/mo
Parallel.ai	Web	Markdown, JSON	Developer agentic workflows	Per task, usage-based
Gemini Deep Research	Web + Google Search	Text, structured	Google ecosystem integration	Gemini Advanced $20/mo
Valyu DeepResearch	Web + 36+ proprietary (SEC, PubMed, patents, clinical trials, financial data)	Markdown, PDF, structured JSON	AI agents needing authoritative/paywalled data	$0.10-$15.00 per task

On pricing transparency

OpenAI's deep research costs are token-based and can spike quickly. One independent analysis ran 10 test queries and spent $100 on o3-deep-research, $9.18 on o4-mini-deep-research. Both are usage-variable, a research task that cites 50 sources will cost substantially more than one that cites 5.

Valyu's pricing is flat per task regardless of how many internal searches and retrievals the agent performs. For production workloads where cost predictability matters, that's a meaningful difference.

The critical column: Data Sources

Four of the five options above are web-only. That means:

No SEC 10-K/10-Q filings (EDGAR isn't fully indexable by web crawlers)
No paywalled academic papers (Elsevier, Springer, Wiley)
No real-time financial data (stock prices, earnings, balance sheets)
No clinical trial data (ClinicalTrials.gov full text)
No patent claims (USPTO full text)

If your use case lives entirely in open web content, the OpenAI or Perplexity options are fine. If it doesn't, you need an API with proprietary source access.

When Web Search Is Not Enough

Three use cases where web-only deep research fails:

1. Financial research agents

You ask: "What are the key risk factors disclosed by Nvidia in their latest 10-K, and how do they compare to AMD's?"

A web-only API returns news articles about these filings, not the filings themselves. The actual MD&A sections, risk disclosures, and financial statements are in EDGAR. Some might return details about the filings, but simply surface details.

2. Biomedical research agents

You ask: "What bioactive compounds in ChEMBL target the KRAS G12C mutation, and how do they relate to current clinical trials?"

ChEMBL has 2.5 million bioactive molecule records. ClinicalTrials.gov is partially indexed but the structured data (phase, endpoints, eligibility criteria) isn't extractable via web search.

3. Patent landscape analysis

You ask: "Which companies hold patents in transformer-based neural architecture search filed after 2022?"

USPTO full-text patent search isn't something a lot of Search APIs return well. Some return some data but let you know that it might not be complete or recent.

Deep Research API for Researchers & Non-Developers

Valyu has a "Deep Research" UI mode simply for non-developers, researchers and folks from all walks of life to have access to the full power of the Deep Research API simply by prompting what you need.

DeepResearch dashboard for the non-coders

You can see the Deliverables feature there as well. Deliverables allow you to extract structured data or create formatted documents (CSV, Excel, PowerPoint, Word, PDF) from the research alongside the report.

Building with Valyu's Deep Research API (for Developers)

Valyu's DeepResearch is an async API. You submit a task, it runs in the background, you poll for completion or use webhooks. This is the right architecture for research that takes 30 seconds to 15 minutes depending on complexity.

Installation

Python

pip install valyu
export VALYU_API_KEY=your_key_here

TypeScript

pnpm add @valyu/valyu-js
export VALYU_API_KEY=your_key_here

Quick Start

Python

from valyu import Valyu

valyu = Valyu()

# Create a research task
task = valyu.deepresearch.create(
    query="What are the key risk factors disclosed by Nvidia in their 2024 10-K?",
    mode="standard",
    search={
        "search_type": "proprietary",
        "included_sources": ["finance"]  # SEC filings, earnings, market data
    }
)

print(f"Task ID: {task.deepresearch_id}")
print(f"Status: {task.status}")  # 'running' or 'queued'

TypeScript

import { Valyu } from "@valyu/valyu-js";

const valyu = new Valyu(process.env.VALYU_API_KEY!);

// Create a research task
const task = await valyu.deepresearch.create({
  query: "What are the key risk factors disclosed by Nvidia in their 2024 10-K?",
  mode: "standard",
  search: {
    search_type: "proprietary",
    included_sources: ["finance"]  // SEC filings, earnings, market data
  }
});

console.log(`Task ID: ${task.deepresearch_id}`);
console.log(`Status: ${task.status}`);  // 'running' or 'queued'

Waiting for Results

Python

# Wait for completion with progress tracking
def on_progress(status):
    if status.progress:
        print(f"Step {status.progress.current_step}/{status.progress.total_steps}")

result = valyu.deepresearch.wait(
    task.deepresearch_id,
    poll_interval=5,
    max_wait_time=1800,
    on_progress=on_progress
)

if result.status == "completed":
    print(result.output)      # Full markdown report
    print(f"Cost: ${result.cost}")

    for source in result.sources:
        print(f"- {source.title}: {source.url}")

TypeScript

const result = await valyu.deepresearch.wait(task.deepresearch_id, {
  pollInterval: 5000,
  maxWaitTime: 1800000,
  onProgress: (status) => {
    if (status.progress) {
      console.log(`Step ${status.progress.currentStep}/${status.progress.totalSteps}`);
    }
  }
});

if (result.status === "completed") {
  console.log(result.output);      // Full markdown report
  console.log(`Cost: $${result.cost}`);

  result.sources.forEach(source => {
    console.log(`- ${source.title}: ${source.url}`);
  });
}

Research Modes

Valyu has four modes, optimized for different depth/cost tradeoffs:

Mode	Price	Max Steps	Best For
`fast`	$0.10	10	Quick lookups, batch processing
`standard`	$0.50	15	Balanced research
`heavy`	$2.50	15	Complex topics, fact verification
`max`	$15.00	25	Exhaustive multi-source analysis

For most agentic workflows, standard mode hits the right tradeoff. Use fast for high-volume batch tasks. Use heavy or max when you need the agent to cross-verify claims across sources.

Proprietary Source Selection

The search parameter controls which data sources the agent searches.

Python

# Academic + biomedical research
task = valyu.deepresearch.create(
    query="Recent advances in CRISPR base editing for sickle cell disease",
    mode="heavy",
    search={
        "search_type": "proprietary",
        "included_sources": ["academic"]  # PubMed, arXiv, bioRxiv, medRxiv, clinical trials
    }
)

# Financial + economic analysis
task = valyu.deepresearch.create(
    query="How do current FRED interest rate indicators compare to 2008 pre-crisis levels?",
    mode="standard",
    search={
        "search_type": "proprietary",
        "included_sources": ["finance"]  # SEC filings, FRED, BLS, stocks, earnings
    }
)

# Patent landscape
task = valyu.deepresearch.create(
    query="Which companies have filed transformer architecture patents since 2022?",
    mode="heavy",
    search={
        "search_type": "proprietary",
        "included_sources": ["patents"]  # USPTO patent database
    }
)

# Cross-domain: web + proprietary combined
task = valyu.deepresearch.create(
    query="Analyze competitor drug pipeline for NASH treatment",
    mode="max",
    search={
        "search_type": "all",
        "included_sources": ["academic", "finance"]
    }
)

TypeScript

// Academic + biomedical research
const academicTask = await valyu.deepresearch.create({
  query: "Recent advances in CRISPR base editing for sickle cell disease",
  mode: "heavy",
  search: {
    search_type: "proprietary",
    included_sources: ["academic"]  // PubMed, arXiv, bioRxiv, medRxiv, clinical trials
  }
});

// Financial + economic analysis
const financeTask = await valyu.deepresearch.create({
  query: "How do current FRED interest rate indicators compare to 2008 pre-crisis levels?",
  mode: "standard",
  search: {
    search_type: "proprietary",
    included_sources: ["finance"]  // SEC filings, FRED, BLS, stocks, earnings
  }
});

// Patent landscape
const patentTask = await valyu.deepresearch.create({
  query: "Which companies have filed transformer architecture patents since 2022?",
  mode: "heavy",
  search: {
    search_type: "proprietary",
    included_sources: ["patents"]  // USPTO patent database
  }
});

// Cross-domain: web + proprietary combined
const crossTask = await valyu.deepresearch.create({
  query: "Analyze competitor drug pipeline for NASH treatment",
  mode: "max",
  search: {
    search_type: "all",
    included_sources: ["academic", "finance"]
  }
});

Available proprietary source categories: academic, finance, patent, legal, transportation, politics.

Structured JSON Output

Instead of markdown, you can define a schema for structured output, useful when your agent needs to pipe results into a database or downstream process.

Python

competitor_schema = {
    "type": "object",
    "properties": {
        "companies": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "ticker": {"type": "string"},
                    "key_risk_factors": {
                        "type": "array",
                        "items": {"type": "string"}
                    },
                    "revenue_guidance": {"type": "string"}
                },
                "required": ["name", "key_risk_factors"]
            }
        },
        "summary": {"type": "string"}
    },
    "required": ["companies", "summary"]
}

task = valyu.deepresearch.create(
    query="Extract risk factors and revenue guidance from Q4 2024 10-Ks for major cloud providers",
    mode="heavy",
    output_formats=[competitor_schema],
    search={
        "search_type": "proprietary",
        "included_sources": ["finance"]
    }
)

TypeScript

const competitorSchema = {
  type: "object",
  properties: {
    companies: {
      type: "array",
      items: {
        type: "object",
        properties: {
          name: { type: "string" },
          ticker: { type: "string" },
          key_risk_factors: {
            type: "array",
            items: { type: "string" }
          },
          revenue_guidance: { type: "string" }
        },
        required: ["name", "key_risk_factors"]
      }
    },
    summary: { type: "string" }
  },
  required: ["companies", "summary"]
} as const;

const task = await valyu.deepresearch.create({
  query: "Extract risk factors and revenue guidance from Q4 2024 10-Ks for major cloud providers",
  mode: "heavy",
  output_formats: [competitorSchema],
  search: {
    search_type: "proprietary",
    included_sources: ["finance"]
  }
});

The API returns JSON that conforms to your schema, ready to deserialize directly.

Webhooks for Production

Don't poll in production. Use webhooks.

Python

import hmac
import hashlib
from flask import Flask, request, jsonify

app = Flask(__name__)
WEBHOOK_SECRET = "your-stored-secret"  # returned on task creation, store it

@app.route("/webhooks/deepresearch", methods=["POST"])
def handle_research_complete():
    signature = request.headers.get("X-Webhook-Signature")
    timestamp = request.headers.get("X-Webhook-Timestamp")
    payload = request.get_data(as_text=True)

    signed = f"{timestamp}.{payload}"
    expected = "sha256=" + hmac.new(
        WEBHOOK_SECRET.encode(),
        signed.encode(),
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(expected, signature):
        return jsonify({"error": "Invalid signature"}), 401

    data = request.json
    if data["status"] == "completed":
        process_research_result(data["deepresearch_id"], data["output"])

    return jsonify({"received": True}), 200


# Task creation with webhook
task = valyu.deepresearch.create(
    query="Comprehensive competitive analysis: SEC filings + market data",
    mode="max",
    webhook_url="https://your-app.com/webhooks/deepresearch"
)
# CRITICAL: store task.webhook_secret immediately - only returned once
store_secret(task.deepresearch_id, task.webhook_secret)

TypeScript

import crypto from "crypto";
import express, { Request, Response } from "express";

const app = express();
app.use(express.raw({ type: "application/json" }));

const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET!;

app.post("/webhooks/deepresearch", (req: Request, res: Response) => {
  const signature = req.headers["x-webhook-signature"] as string;
  const timestamp = req.headers["x-webhook-timestamp"] as string;
  const payload = req.body.toString();

  const signed = `${timestamp}.${payload}`;
  const expected = "sha256=" + crypto
    .createHmac("sha256", WEBHOOK_SECRET)
    .update(signed)
    .digest("hex");

  if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))) {
    return res.status(401).json({ error: "Invalid signature" });
  }

  const data = JSON.parse(payload);
  if (data.status === "completed") {
    processResearchResult(data.deepresearch_id, data.output);
  }

  res.json({ received: true });
});


// Task creation with webhook
const task = await valyu.deepresearch.create({
  query: "Comprehensive competitive analysis: SEC filings + market data",
  mode: "max",
  webhook_url: "https://your-app.com/webhooks/deepresearch"
});
// CRITICAL: store task.webhookSecret immediately - only returned once
await storeSecret(task.deepresearch_id, task.webhook_secret);

Date Filtering

For time-sensitive research tasks, you can pin the search window.

Python

task = valyu.deepresearch.create(
    query="Clinical trial results for GLP-1 receptor agonists in NASH",
    mode="standard",
    search={
        "search_type": "proprietary",
        "included_sources": ["academic"],
        "start_date": "2023-01-01",
        "end_date": "2025-12-31"
    }
)

TypeScript

const task = await valyu.deepresearch.create({
  query: "Clinical trial results for GLP-1 receptor agonists in NASH",
  mode: "standard",
  search: {
    search_type: "proprietary",
    included_sources: ["academic"],
    start_date: "2023-01-01",
    end_date: "2025-12-31"
  }
});

This prevents the agent from pulling in outdated studies. This is very important for medical or financial research where recency matters.

Attach Documents for Analysis & Inclusion

Feed existing documents of all types into the research task. This is useful for combining internal documents with external research.

Python

import base64

with open("internal_q4_report.pdf", "rb") as f:
    pdf_b64 = base64.b64encode(f.read()).decode()

task = valyu.deepresearch.create(
    query="Compare the Q4 projections in this internal report against actual SEC filing data for our competitors",
    mode="heavy",
    files=[{
        "data": f"data:application/pdf;base64,{pdf_b64}",
        "filename": "q4_report.pdf",
        "mediaType": "application/pdf",
        "context": "Internal Q4 2024 financial projections"
    }],
    search={
        "search_type": "proprietary",
        "included_sources": ["finance"]
    }
)

TypeScript

import fs from "fs";

const pdfBuffer = fs.readFileSync("internal_q4_report.pdf");
const pdfB64 = pdfBuffer.toString("base64");

const task = await valyu.deepresearch.create({
  query: "Compare the Q4 projections in this internal report against actual SEC filing data for our competitors",
  mode: "heavy",
  files: [{
    data: `data:application/pdf;base64,${pdfB64}`,
    filename: "q4_report.pdf",
    mediaType: "application/pdf",
    context: "Internal Q4 2024 financial projections"
  }],
  search: {
    search_type: "proprietary",
    included_sources: ["finance"]
  }
});

Deep Research API in Production

"Talk is cheap, show me the code, and show it to me in production" - Odogwu Machalla

Consult Ralph is an AI-powered Deep Research app for consultants. It's in production, currently used by hundreds of consultants daily. The app is heavily powered by Valyu DeepResearch API.

// Detect dark theme var iframe = document.getElementById('tweet-2020959881935962295-719'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=2020959881935962295&theme=dark" }

It's also open-source. You can fork, clone, star it and check out the code for good references on how to use the Valyu Deep Research API in your codebase.

Benchmarks

Valyu's DeepResearch scores 53.1 on DeepResearch-Bench. The best published score for any commercial deep research API.

On domain-specific benchmarks where proprietary data access matters:

Benchmark	Valyu	Parallel	Exa	Google
Finance (120 questions)	73%	67%	63%	55%
Economics (100 questions)	73%	52%	45%	43%
MedAgent (562 medical queries)	48%	42%	44%	45%
FreshQA (600 time-sensitive)	79%	52%	24%	39%

The finance and economics gaps are almost entirely explained by proprietary data access. Valyu queries FRED, BLS, and SEC directly. Web-only APIs rely on articles that reference this data, which is noisier and often outdated.

Frequently Asked Questions

What is a deep research API?

A deep research API is a programmatic interface that performs multi-step autonomous research. It accepts a query, plans a research strategy, searches multiple sources, synthesizes results, and returns a structured report with citations. Unlike a standard search API, deep research APIs run asynchronously - tasks can take seconds to minutes depending on depth.

How does Valyu's DeepResearch API differ from OpenAI's?

OpenAI's deep research (o3-deep-research, o4-mini-deep-research) only searches the web via Bing. Valyu's DeepResearch searches both the web and 36+ proprietary data sources including SEC filings, PubMed, arXiv, clinical trials, USPTO patents, FRED economic data, and ChEMBL bioactive compounds. For AI agents that need authoritative domain data rather than general web content, this is the meaningful difference.

What does the Valyu DeepResearch API cost?

Four modes: fast ($0.10/task), standard ($0.50/task), heavy ($2.50/task), max ($15.00/task). Pricing is per task regardless of the number of searches or retrievals the agent performs internally. Signup gets $10 in free credits, no card required.

Does Valyu's deep research API support webhooks?

Yes. Pass a webhook_url on task creation. The API returns a webhook_secret for signature verification. Webhooks fire on task completion or failure with the full output payload. Retries use exponential backoff (up to 5 attempts) on server errors.

Can I get structured JSON output from a deep research API?

Valyu supports custom JSON Schema for structured output. Pass a schema object in output_formats. The API returns output that conforms to your schema, ready to deserialize directly into your application's data structures.

How long does a deep research task take?

Fast mode typically completes in under 60 seconds. Standard mode takes 2-5 minutes. Heavy and max modes can take up to 15-30 minutes for complex multi-source analysis. Use the wait() method with progress callbacks for synchronous use cases, or webhooks for production event-driven workflows.

Can I attach documents to a deep research task?

Yes. Pass files as base64-encoded data with a media type. The API supports PDFs, images (PNG, JPEG, WebP), and other documents. Useful for combining internal documents with external research - for example, analyzing your internal financial projections against publicly filed SEC data.

Is there a TypeScript / JavaScript SDK?

Yes. pnpm add @valyu/valyu-js. The API surface is identical to the Python SDK - all examples in this guide are shown in both languages.

Summary

If you're building AI agents that only research general web content, OpenAI or Perplexity deep research are solid choices, including Valyu. If your agents need to touch SEC filings, academic papers behind paywalls, clinical trial databases, USPTO patents, or real financial data, you need an API with proprietary source access.

Valyu's DeepResearch API:

Four modes from $0.10 (fast) to $15.00 (max)
36+ proprietary data sources across finance, biomedical, academic, patent, and legal domains
Markdown, PDF, and structured JSON output
Webhook and polling support
53.1 on DeepResearch-Bench (best published commercial score)

Docs at docs.valyu.ai/guides/deepresearch.

$10 free credits on signup at platform.valyu.ai.

Why your AI agent keeps hallucinating financial data (and how to fix it)

Prosper Otemuyiwa — Fri, 27 Feb 2026 12:02:18 +0000

You asked your financial agent for NVIDIA's current P/E ratio. It answered: 40.2.

The actual number was 45.65.

You asked it to summarize the key risks from a company's latest 10-K. It cited concerns that were quietly removed two annual reports ago.

You asked for Apple's most recent quarterly revenue. Off by $3 billion.

This is not a hallucination problem in the sense you might think. The LLM isn't randomly generating numbers. It's retrieving the most statistically likely answer from its training data, and doing it confidently. The problem is that financial data has a shelf life measured in hours, sometimes minutes and LLM training data has a shelf life measured in years or months.

This is a data access problem, not an intelligence problem. And it has a clean fix.

Why the training cutoff ruins financial agents

GPT-5.2's training data cuts off is August 31, 2025. Claude 4.6 Sonnet's is August 2025.

Stock prices move by the second. Earnings drop quarterly. The Fed makes a rate decision and markets reprice overnight. A company files an 8-K about a material event and that changes everything. LLMs have none of this.

What makes it worse is that the model doesn't know it's wrong. When you ask for Microsoft's current P/E ratio, it has an answer. That answer was accurate at some point during training. It delivers it with the same confidence as if it just pulled the number off a live exchange. No hedging, no "as of my knowledge cutoff" qualifier, unless you've explicitly prompted for it, and even then it often still gives you a number.

The result: An agent that sounds authoritative while being factually wrong on every time-sensitive financial data point.

For general Q&A this is acceptable. For anything financial, it's a liability.

The two approaches that don't actually work

Approach 1: Prompt the model harder

const result = await generateText({
  model: openai('gpt-5.2'),
  prompt: `You are a financial expert. Always provide accurate,
  up-to-date financial data. Today's date is ${new Date().toISOString()}.
  What is Apple's current stock price?`,
});

This does nothing useful. Telling the model today's date doesn't give it access to today's data. It still answers from training data. Worse, the explicit date sometimes triggers more confident wrong answers because the model pattern-matches "I know this domain" and generates a plausible-sounding number.

Approach 2: RAG with financial documents

Some teams build a RAG pipeline: scrape financial reports, chunk them, embed them, retrieve on query. This is better than nothing but it creates a new set of problems:

You're now responsible for keeping the document store current
Scraped financial documents lose structure (tables, footnotes, cross-references)
Your retrieval quality determines your answer quality
SEC filings alone average 40,000 words. Chunking strategies matter enormously
You're essentially rebuilding a financial data API, badly

The root problem isn’t your retrieval strategy. It’s that you’re trying to solve a live data problem with a static data architecture.

Let’s be honest. It’s 2026. Why are you still building and maintaining your own RAG pipeline from scratch?

Vector DB tuning. Chunking debates. Re-indexing jobs. Infra bills creeping up every month. Edge cases multiplying. It gets expensive fast. And the maintenance burden compounds even faster.

The actual fix: live data as tools

The correct mental model is this: An LLM should reason over financial data, not store it.

The LLM is good at understanding context, synthesizing information, drawing conclusions, and communicating clearly. It's bad at being a database. Stop asking it to be one.

The fix is to give your agent tools that query live financial data at inference time. When the agent needs a stock price, it calls a tool and gets the current price. When it needs SEC filings, it searches them in real time. The LLM never touches a stale number.

Here's what this looks like with the Vercel AI SDK and TypeScript:

Basic setup

pnpm add @valyu/ai-sdk ai @ai-sdk/openai

import { generateText, stepCountIs } from "ai";
import { financeSearch } from "@valyu/ai-sdk";
import { openai } from "@ai-sdk/openai";

const { text } = await generateText({
  model: openai('gpt-5.2'),
  prompt: 'What is the current P/E ratio for NVIDIA and how does it compare to AMD?',
  tools: {
    financeSearch: financeSearch(),
  },
  stopWhen: stepCountIs(5),
});

console.log(text);

When the agent runs this, it doesn't guess. It calls financeSearch with a query, gets back current market data, and reasons over it. The number it tells you is the number that was retrieved from a live source at the moment you asked.

Building a financial research agent

Here's a more complete example, a streaming financial agent you can drop into a Next.js API route:

// app/api/finance/route.ts
import { openai } from '@ai-sdk/openai';
import { financeSearch } from '@valyu/ai-sdk';
import { streamText } from 'ai';

export async function POST(req: Request) {
  const { messages } = await req.json();

  const result = streamText({
    model: openai('gpt-5.2'),
    messages,
    system: `You are a financial analyst with access to real-time market data and SEC filings. When asked about any financial metric, stock price, earnings figure, or company filing, always use your search tool to retrieve current data. Never rely on prior knowledge for financial figures. Cite your sources.`,
    tools: {
      searchFinance: financeSearch(),
    },
  });

  return result.toDataStreamResponse();
}

The critical part is the system prompt instruction: "Always use your search tool to retrieve current data. Never rely on prior knowledge for financial figures."

This forces the agent to go live on every financial query instead of falling back to training data.

Going deeper: SEC filings and Earnings data

Stock prices are the obvious case. But the same problem applies to everything structural: balance sheets, income statements, risk factors, insider transactions, earnings guidance.

Here's how to search SEC filings specifically:

import { Valyu } from "valyu-js";

const valyu = new Valyu();

// Search for specific disclosure language across recent 10-K filings
const response = await valyu.search(
  "material risk factors related to AI compute supply chain 2024",
  {
    searchType: "proprietary",
    includedSources: ["valyu/valyu-sec-filings"],
    maxNumResults: 10,
    responseLength: "large",
  }
);

response.results.forEach((result) => {
  console.log(`Filing: ${result.title}`);
  console.log(`Source: ${result.url}`);
  console.log(`Excerpt: ${result.content.slice(0, 400)}`);
});

This returns actual filing content. Not summaries, not news articles about filings, the actual text from 10-Ks.

Natural language queries work. You don't need ticker symbols or accession numbers.

For combining market data with fundamentals in one agent:

import { generateText, stepCountIs } from "ai";
import { financeSearch } from "@valyu/ai-sdk";
import { openai } from "@ai-sdk/openai";

const { text } = await generateText({
  model: openai('gpt-5.2'),
  prompt: `Analyze Microsoft's financial position: current valuation
  multiples, most recent quarterly earnings vs expectations, and any
  material risk disclosures from their latest 10-K.`,
  tools: {
    finance: financeSearch(),
  },
  stopWhen: stepCountIs(10),
});

The agent will make multiple tool calls. One for market data, one for earnings, one for SEC filings and synthesize the results into a coherent analysis. All from live sources.

Combining multiple financial data sources

The most useful financial agents cross-reference data types. An earnings miss is more meaningful when you can see it alongside the stock reaction, the analyst revision history, and what management said in the 8-K. Here's a multi-source pattern:

import { Valyu } from "valyu-js";

const valyu = new Valyu();

async function analyzeCompany(ticker: string) {
  // Parallel queries across data types
  const [marketData, fundamentals, filings] = await Promise.all([
    valyu.search(`${ticker} stock price market cap volume`, {
      searchType: "proprietary",
      includedSources: ["valyu/valyu-stocks"],
      maxNumResults: 3,
    }),
    valyu.search(`${ticker} earnings revenue EPS most recent quarter`, {
      searchType: "proprietary",
      includedSources: [
        "valyu/valyu-earnings-US",
        "valyu/valyu-income-statement-US",
      ],
      maxNumResults: 5,
    }),
    valyu.search(`${ticker} 10-K risk factors material disclosures`, {
      searchType: "proprietary",
      includedSources: ["valyu/valyu-sec-filings"],
      maxNumResults: 5,
      responseLength: "large",
    }),
  ]);

  return {
    market: marketData.results,
    fundamentals: fundamentals.results,
    filings: filings.results,
  };
}

This is the pattern that makes financial agents actually useful. You're not asking the LLM to recall financial data, you're giving it three live data streams to reason over.

Handling the response in a streaming UI

If you want this in a chat interface, the Vercel AI SDK handles the streaming side cleanly:

// app/page.tsx
'use client';

import { useChat } from 'ai/react';

export default function FinanceAgent() {
  const { messages, input, handleInputChange, handleSubmit, isLoading } = useChat({
    api: '/api/finance',
  });

  return (
    <div className="flex flex-col h-screen max-w-3xl mx-auto p-4">
      <div className="flex-1 overflow-y-auto space-y-4 mb-4">
        {messages.map((message) => (
          <div
            key={message.id}
            className={`flex ${
              message.role === 'user' ? 'justify-end' : 'justify-start'
            }`}
          >
            <div
              className={`rounded-lg px-4 py-2 max-w-2xl ${
                message.role === 'user'
                  ? 'bg-blue-500 text-white'
                  : 'bg-gray-100 text-gray-900'
              }`}
            >
              {message.content}
            </div>
          </div>
        ))}
        {isLoading && (
          <div className="text-gray-400 text-sm">Searching live data...</div>
        )}
      </div>

      <form onSubmit={handleSubmit} className="flex gap-2">
        <input
          value={input}
          onChange={handleInputChange}
          placeholder="Ask about any company or market..."
          className="flex-1 px-4 py-2 border rounded-lg"
          disabled={isLoading}
        />
        <button
          type="submit"
          disabled={isLoading}
          className="px-6 py-2 bg-blue-500 text-white rounded-lg disabled:bg-gray-300"
        >
          {isLoading ? 'Searching...' : 'Ask'}
        </button>
      </form>
    </div>
  );
}

What changes once you do this

The quantitative difference is real. On a benchmark of 120 finance-specific questions, agents using live proprietary data access score 73% accuracy. Agents using GPT with no tool access score significantly lower, and every miss is a confident, plausible-sounding wrong answer.

A more practical scenario: When a user asks your agent about a company's debt-to-equity ratio, they're probably making a decision. The cost of a confidently wrong answer is not a user complaint, it's a user making a bad decision because your tool told them something false with authority.

The architecture shift here is small. You're adding a tool definition and changing a system prompt instruction. The result is an agent that reasons accurately over live financial data instead of pattern-matching from stale training.

FAQ

Q: Does this work with Claude and other models, not just OpenAI?

Yes. The Vercel AI SDK supports any model through their provider system. Swap openai('gpt-5.2') for anthropic('claude-sonnet-4-6') and the tool calling works identically. Financial data tools are model-agnostic.

Q: What financial data sources does this actually cover?

The financeSearch tool routes across stocks (200K+), crypto (200+ coins), forex (180+ pairs), ETFs (25K+), plus company fundamentals, earnings, balance sheets, income statements, cash flows, dividends, insider transactions. And SEC filings (3M+ documents: 10-K, 10-Q, 8-K, Form 4s). All queryable via natural language.

Q: What about FRED economic data and macro indicators?

You can include valyu/valyu-fred and valyu/valyu-bls as sources in the search. Same pattern. Just pass them in includedSources and query in natural language. Useful for macro context alongside company-level data.

Q: How do I avoid the agent making too many tool calls and running up costs?

stopWhen: stepCountIs(N) from the Vercel AI SDK controls the maximum number of tool call steps. For simple queries, stepCountIs(3) is usually enough. For deep research queries, stepCountIs(10) gives more room. You can also set maxPrice on the search tool itself to cap per-result retrieval costs.

Q: Should I still use RAG for financial data?

RAG makes sense for private documents you own. Internal research reports, your own financial models, proprietary analysis. For public financial data (market prices, SEC filings, earnings) that changes continuously, live API access is more appropriate. Don't use static RAG for data that has a freshness requirement.

Q: Does this work for real-time stock prices or just historical data?

Both. Market data has a 1-5 minute delay on real-time prices. Historical data is available going back years. For most analytical use cases, the 1-5 minute delay is irrelevant. If you're building a trading system that requires millisecond precision, you need a dedicated market data feed. For financial research agents, this is more than sufficient.

The code in this article is runnable as-is with a VALYU_API_KEY and OPENAI_API_KEY in your environment.

Full working examples are in the Valyu cookbook on GitHub.

Here's a real-world Finance AI agent - https://finance.valyu.ai. The repo is open-source

If you're building something with this, drop it in the comments. I'm curious what use cases people are working on.

How I Built a Live Stock Market AI Agent in ~40 Lines of TypeScript

Prosper Otemuyiwa — Tue, 24 Feb 2026 11:48:37 +0000

I got tired of jumping between Yahoo Finance, a broker dashboard, and a Google News tab every time I wanted a quick read on a stock. What I actually wanted: type a question, get a grounded answer that pulls live prices, recent earnings, and current news in one shot.

Turns out you can wire this up in an afternoon with Vercel AI SDK and Valyu's financeSearch + webSearch tools. Here's how.

What we're building

A Node.js CLI agent you run like this:

npx tsx agent.ts "What's happening with NVDA? Give me price, recent earnings, and any news I should know about."

It streams back a real answer, not a hallucinated one, pulled from live financial data and current web sources.

Setup

You need two things:

A Valyu API key - free $10 credit when you sign up at platform.valyu.ai
An Anthropic API key (or swap in OpenAI/any other AI SDK provider)

pnpm add ai @ai-sdk/anthropic @valyu/ai-sdk

Create a .env file:

VALYU_API_KEY=your-valyu-key
ANTHROPIC_API_KEY=your-anthropic-key

The agent

// agent.ts
import { streamText, stepCountIs } from "ai";
import { anthropic } from "@ai-sdk/anthropic";
import { financeSearch, webSearch } from "@valyu/ai-sdk";

const query = process.argv[2] ?? "What's the current price and outlook for AAPL?";

const result = streamText({
  model: anthropic("claude-3-5-sonnet-20241022"),
  messages: [
    {
      role: "system",
      content: `You are a stock market analyst with access to live financial data and web search.
- Use financeSearch for stock prices, earnings, dividends, balance sheets, and insider transactions
- Use webSearch for recent news, analyst sentiment, and market context
- Always cite sources
- Be specific: include actual numbers, dates, and figures from your search results`,
    },
    {
      role: "user",
      content: query,
    },
  ],
  tools: {
    financeSearch: financeSearch(),
    webSearch: webSearch(),
  },
  stopWhen: stepCountIs(5),
});

for await (const chunk of result.textStream) {
  process.stdout.write(chunk);
}

console.log("\n");

That's the whole thing. The agent loop is handled by stepCountIs(5), the model keeps calling tools until it has enough data to answer, up to 5 steps.

How it works

When you run it, the agent:

Receives your question
Decides which tools to call (financeSearch, webSearch, or both)
Gets results back. Real prices, actual earnings figures, live news
Synthesizes an answer with citations
Streams it back token by token

The financeSearch tool pulls from stock prices, earnings reports, income statements, balance sheets, dividend history, and insider transaction data. webSearch covers current news, analyst coverage, and anything else on the open web.

For a query like "What's happening with NVDA?" you'd typically see it call financeSearch for price and recent earnings, then webSearch for news about data center demand or any recent analyst upgrades, then combine them into a coherent analysis.

Extending it

A few directions from here:

Add more tools for deeper research:

import { secSearch, economicsSearch } from "@valyu/ai-sdk";

tools: {
  financeSearch: financeSearch(),
  webSearch: webSearch(),
  sec: secSearch(),          // 10-K, 10-Q, 8-K filings
  economics: economicsSearch(), // FRED, BLS macro data
},

Compare multiple tickers:

content: "Compare MSFT and GOOGL on trailing P/E, revenue growth, and recent earnings beats"

The agent will run parallel searches and give you a side-by-side.

Control costs with config options:

financeSearch({
  maxNumResults: 5,        // fewer results = lower cost
  relevanceThreshold: 0.8, // only high-quality matches
})

What the data actually covers

financeSearch isn't just price tickers. It pulls from:

Historical and real-time stock, crypto, and forex prices
Earnings per share, revenue, and guidance
Balance sheets, income statements, cash flow
Insider buy/sell transactions (Form 4 data)
Dividend history

So queries like "How have TSLA insiders been trading over the last 6 months?" or "What's Apple's free cash flow trend since 2021?" work out of the box.

Running it

npx tsx agent.ts "Is AMD a buy right now? Give me current price, latest earnings, and analyst sentiment."

Sample output (abridged):

AMD is currently trading at $X.XX, down X% today...

Recent Earnings (Q4 2024):
- Revenue: $X.XB (beat estimates by X%)
- EPS: $X.XX vs $X.XX expected
- Data center segment grew XX% YoY...

Analyst Sentiment:
According to recent coverage from [source], consensus is...

The numbers are real. The sources are cited. No hallucination.

The Underlying API

Under the hood, @valyu/ai-sdk is a thin wrapper around Valyu's DeepSearch API. If you want to build a custom tool, one that only searches specific financial sources, you can drop down to the raw tool() from the AI SDK:

import { tool } from "ai";
import { z } from "zod";

const cryptoSearch = tool({
  description: "Search cryptocurrency price and market data",
  inputSchema: z.object({
    query: z.string(),
  }),
  execute: async ({ query }) => {
    const response = await fetch("https://api.valyu.ai/v1/search", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-api-key": process.env.VALYU_API_KEY,
      },
      body: JSON.stringify({
        query,
        search_type: "proprietary",
        included_sources: ["valyu/valyu-crypto"],
        max_num_results: 5,
      }),
    });
    return response.json();
  },
});

Full list of available sources and parameters at docs.valyu.ai.

Code

Full example is a single file, agent.ts , above is all you need. If you build something on top of this, the main things to think about are:

System prompt quality matters a lot for financial queries. Be explicit about what each tool is for
stepCountIs(5) is usually enough for single-stock analysis; bump to 8-10 for comparative research
Stream the output for better UX - streamText over generateText

The Valyu finance data covers benchmarks like 73% accuracy on 120 finance questions vs 55% for Google search, which matters when you're asking specific questions about earnings or insider activity where precision is the point.

A Code-First Approach to Managing Notification Workflows

Prosper Otemuyiwa — Thu, 09 May 2024 13:50:37 +0000

Building rich, smooth, and customizable multi-channel notification experiences that are delivered the right way is difficult. Scaling them across teams and organizations makes it even harder.

At Novu, we empower developers with best-in-class notification tools and infrastructure to make managing notifications a walk-in-the-park when developing apps or any form of digital system.

Why a code-first notification workflow approach?

These are the current challenges developers face in managing notification workflows:

ClickOps, not GitOps. Currently, developers are limited to building notification workflows solely through the user interface (UI) and API. While these methods serve their purpose adequately, they come with some drawbacks. Not only are they time-consuming, but they also disrupt the development flow.
External Frameworks. It’s inherently difficult and sometimes impossible to integrate notification workflows with external content frameworks. There are tons of tools out there that simplify notification content creation.
Debugging. Debugging notification content issues in a UI or via API can be time-consuming.
Limited Customization. Immense limitation of notification steps customization and lack of control. Developers yearn for the ability to control the before and after of certain actions and events in their apps. The if this, then that approach is not readily available in a UI-first notification workflow.
Huge barrier for non-technical users. Developers rarely work in silos. They work together with marketing, product, sales and other departments to build, manage and sell software. Currently, non-technical users depend on them for the slightest modifications and changes to the notification experience. It’s time-consuming and not scalable!

The power of code-first notification workflows

The code-first notification workflow approach empowers you as a developer to build advanced workflows with code while giving your non-technical teammates full control over content and behaviour.

Everyone wants to be great at something - a great friend, a great partner, a great footballer, a great chef, a great colleague. Novu’s advanced code-first workflow (currently known as Novu Echo) makes you a great developer and teammate by arming you with incredible power to do the following:

Integration of content frameworks and templating libraries such as React Email, MJML, Vuemail, and Maizzle into your workflow. As long as it’s an npm package or library, you can integrate it with your notification workflow.
Run custom code between notification steps (email, SMS, in-app, push).- For example, before sending an email, get data from an external service or DB.
- Pass custom data from any component to channel providers within the code.
- Pass customized and well-designed content data into the In-App notification step.



import { Echo } from "@novu/echo";
import { renderReactEmail } from "./emails/react-email";

const commentWorkflow = client.workflow('comment-on-post', async function({ step, subscriber, payload }) => {
    const inAppResponse = await step.inApp('in-app-step', async (inputs) => {
        return {
            body: renderReactComponent(inputs)
        }
    }, {
        inputs: {
                // ...JSON Schema or ZOD/Ajv/Class Validators definition
        }
    });

    // Novu Worker Engine will manage the state and durability of each step in isolation
    const { events } = await step.digest('diges-events', async () => {
        return {
            amount: 1,
            unit: 'day'
        };
    });

    await step.email('comment-reminder', async () => {
        // Echo runs as part of your application, so you have access to your database or resources
        const post = await db.findPost(payload.post_id);

        return {
            subject: 'E-mail Subject',
            body: renderReactEmail(inputs, events)
        }
  }, {
        // Step-level inputs defined in code and controlled in the novu Cloud UI by a Non Technical Team member
        inputSchema: {
            // ...JSON Schema
        },
        providers: {
            sendgrid: async (inputs) => {
                return {
                    ipPoolName: 'custom-pool'
                }
            }
        },
        skip: () => {
            // Write custom skip logic
            return inAppResponse.seen;
        }
    });
}, { 
    // Define your workflow trigger payload using json schema and custom validation;
    payloadSchema: {
        // ...JSON Schema
    }
});


// Trigger workflows like you usually do
commentWorkflow.trigger({
    to: { subscriberId: '12345' },
    payload: { ...Custom Trigger Data }
});

An example of the code-first notification workflow

Build reusable workflow components. For instance, your codebase can now have rich and complete email, In-App and push notification components all in the same place.
Integrate with existing legacy design and notification systems.
Version-controlled notification workflows managed in Git.
Debug and replay notification workflows in your code editors.
Define workflow inputs and variables using JSON schema (supports zod, ajv, class validators, and so many more)



...
const inAppResponse = await step.inApp('in-app-step', async (inputs) => {
        return {
            body: renderReactComponent(inputs)
        }
    }, {
        inputSchema: {
            type: "object",
      properties: {
        prompt: {
          title: "System Message",
          type: "string",
          default: "This is the default message",
          description: "The system message to be sent.",
        },
        showCount: {
          title: "Show Digest Count",
          type: "boolean",
          default: false,
          description: "Whether to show the count of the messages.",
        },
        showSummary: {
          title: "Show Digest Summary",
          type: "boolean",
          default: true,
          description: "Whether to show the summary of the messages.",
        },
      },
        }
    });

input using JSON schema

Deploy changes from your local development environment to the Novu Cloud in your CI platform.

GitOps notification as code

Below is a glimpse of an engineer crafting the notification workflow and content locally using the Novu Dev Studio. Any changes made locally are synced to the Cloud via the click of a button by the engineer.

The UI components (step inputs) on the right are built from code by the engineer. The result of the code shown earlier.
The email content is designed using React email.
The JSON tab displays editable JSON code for making changes The Novu Dev Studio

No-code control to non-technical users

One major pain point that Novu Echo addresses is the inability for non-technical users to modify parts of the notification workflow as they see fit.

Now, engineers can develop complex notification workflows from code, which exposes a customized UI interface (as shown above) with step inputs that product, marketing, and any non-technical user can safely use to modify the notification experience without breaking the system.

Power has changed hands—from constraint to limitless potential

The code-first notification workflow approach enhances the process of sending and managing notifications. It has put boundless and great power in the hands of engineers, enabling them to bring to life any type of notification systems and engines they imagine.

With this approach, engineers can build notification systems that offer unparalleled flexibility and customization, benefiting their customers, teammates, and companies alike.

No longer limited by UI notification steps and rigidity.
No longer limited by notification content editors and systems. The more, the merrier!
Now an IFTTT (If-This-Then-That) pro engineer!

Delve into building right away with this approach by using our code-first notification workflow guide..

How to build dev.to Community Digest with Novu

Prosper Otemuyiwa — Mon, 29 Apr 2024 18:20:30 +0000

dev.to is a widely recognized and highly esteemed community dedicated to developers from all around the globe. It serves as a platform for thousands of developers to learn, share, and publish their experiences with leveraging technology in their work.

One other thing that piqued my curiosity is the dev.to community Digest I frequently get in my inbox. The email digest helps me stay informed about some of the top articles I am interested in.

Dev.to Email Community Digest

In the first part of this article, I covered how to develop a system similar to dev.to's In-App Notification system in less than 30 minutes. Now, I'll show you how to build an automated email community digest similar to this using Novu.

Add a Digest & Email Node to Existing Workflow on Novu

All notifications are sent via a workflow. A workflow acts as a container for the logic and blueprint associated with any type of notification in your app.

All the channels (Email, SMS, In-App, Push) are tied together under a single entity in a workflow.

In the previous article, we already created a workflow. Now, let's add a Digest node to it:

Open the existing Devto Notifications Workflow.
Click on the + icon under the In-App node and select Digest.

- Click on the Digest node. A modal will open where you can set how long events need to be digested before the next action. In this case, the next action will be sending an email to subscribers.

Set 1 minute for the digest. Feel free to experiment with this. You can set any custom minute or hour needed.
The digest node allows you to set a specific time interval for when notifications should be sent.
We need to access all the digested event payloads in order to show the subscriber all or parts of the events included in this digest. For example: “Prosper and 2 others liked your photo.”
In our case, we need all post titles and links that have been published by anyone in the past minute to be sent in one email to subscribers.

- Click on the + icon again to add the Email channel.

Click on the Email channel node to add content. Don't forget to click the Update button when you're finished.
- Add the content below to it. This is a digest template:

<p> Hey Dev.to Subscriber, <p>
<p>Here are some recent community posts just for you </p>

{{#each step.events}}
<a href="{{article_url}}" style="font-weight:bold;">
  <h3>{{article_title}}</h3>
</a>
<br/>
{{/each}}

As part of the digested template, you will have access to a few properties:

step.events: An array of all the events aggregated under this digest.
step.total_count: The number of total events in this digest.
step.digest: A boolean flag to indicate if we are in digest mode right now.

In the code above, we are looping through the step.events to grab all the events that have happened in the action before sending an email.

The action here is on In-App push notifications. Novu collects all the In-App push notifications that occur within a one-minute digest time. It then uses the specified payload (in this case, article_url and article_title) to determine the content to display in the email sent to subscribers. It's quite impressive!

Publish to dev.to via the API with POSTMAN or Insomnia

Fire up either POSTMAN or Insomnia again and publish as many articles as possible within the space of a minute.

Firstly, the In-App notifications will appear as intended. No surprises here. We already went through this in the previous part of this series.

Wait for a minute. You should receive an email after a minute with all of the articles published within that timeframe.

The email just arrived in my inbox. Just like on dev.to!

The body of the email contains a digest of all the content published within a minute.

That's all. Now, we have a dev.to email community digest.

Note: Feel free to style the email content to look as pretty as dev.to’s community digest.

More on Using Digest

There are numerous scenarios where using a notification digest in your app can be beneficial.

For instance, if you're developing a social media app like Instagram, TikTok, or a LinkedIn-like app that requires frequent user interaction notifications, it's wise to digest these notifications. To avoid overwhelming users and risking app uninstalls or notification disabling, manage your notification volume effectively.
Similarly, if you're building the next GitHub or a web app requiring constant email notifications, take care with your notification strategy. Using an email digest can be a practical solution!

For more information, refer to this comprehensive guide on the different types of digests available and learn how you can configure them in your app with Novu.

Conclusion

We have successfully incorporated an email community digest into our app without making any changes to the existing codebase. We only made a few changes in our Novu dashboard.

I prayed for days like these a decade ago. They're here and they powerfully demonstrate how we can leverage excellent tools to move quickly, iterate, focus on business logic and build a million-dollar business 😁

I’ll leave you with these two guides that show in detail how to:

Don’t hesitate to ask any questions or request support. You can find me on Discord and Twitter. Please feel free to reach out.

How to build dev.to In-App Notification System in 20 minutes

Prosper Otemuyiwa — Tue, 23 Apr 2024 11:14:26 +0000

dev.to is a very popular community for developers. It’s a platform for thousands of developers to collaborate, learn, publish and explore new ways of making programming languages and technology work for them.

I’m an avid reader of dev.to and publish a lot of articles on the platform. My favorite thing to do is to check my notifications to see who posted a new article, commented or liked any of my posts.

I'll guide you on how to swiftly build an In-App Notification system for your next app using Novu and the dev.to API. While it might not exactly resemble the image mentioned above, it'll have many similarities.

If you want to explore the code right away, you can view the completed code on GitHub.

Grab your dev.to API Key

You can get your dev.to API key from your settings page.

Set Up a Next.js App

To create a Next.js app, open your terminal, cd into the directory you’d like to create the app in, and run the following command:

npx create-next-app@latest devto

Go through the prompts, select your preference, install and run the app in your browser with:

npm run dev

Set Up & Integrate Novu

Run the following command to install the Novu node SDK:

npm install @novu/node

Run the following command to install the Novu Notification Center package:

npm install @novu/notification-center

The Novu Notification Center package provides a React component library that adds a notification center to your React app. The package is also available for non-React apps.

Before we can start sending and receiving notifications, we need to set up a few things:

Create a workflow for sending notifications,
Create a subscriber - recipient of notifications.

Create a Novu Workflow

A workflow is a blueprint for notifications. It includes the following:

Workflow name and Identifier
Channels: - Email, SMS, Chat, In-App and Push

Create a workflow by following the steps below:

Click Workflow on the left sidebar of your Novu dashboard.
Click the Add a Workflow button on the top left. You can select a Blank workflow or use one of the existing templates.
The name of the new workflow is currently “Untitled”. Rename it to Devto Notifications.
Select In-App as the channel you want to add.

5. Click on the recently added “In-App” channel and add the following text to it. Once you’re done, click “Update” to save your configuration.

The code below is what is in the image above. You can copy & paste it into the Novu editor.

<p><strong>{{ name }}</strong> made a new post.</p>
<br />
<article style="padding:10px;border-radius:5px;border-color: white;border-block: solid;">
  <a href="{{ article_url }}" style="font-weight:bold;">
    <h3>{{ article_title }}</h3>
  </a>
</article>

Enable the “Add an Avatar” button to allow the notifications coming in show a default avatar.

Create a Subscriber to receive Notifications

A subscriber is the recipient of a notification. Essentially, your app users are subscribers. As a logged-in user on dev.to, you are a subscriber.

To send notifications to a user on your app, you’ll need to register that user as a subscriber on Novu. If you click “Subscriber” on the left sidebar of the Novu dashboard, you’ll see the subscriber list. As a first time Novu user, it will be an empty list.

Open your terminal and run the following script to create a subscriber:

curl --location '<https://api.novu.co/v1/subscribers>' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: ApiKey <NOVU_API_KEY>' \
  --data-raw '{
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]",
    "phone": "+1234567890"
    }'

Note: Grab your NOVU API Key from the settings section of your Novu dashboard.

Refresh the Subscribers page on your Novu dashboard. You should see the recently added subscriber now! You can also add a subscriber to Novu by running this API endpoint.

Note: The best option to add a subscriber is via code in your backend. With Node.js code, you can run the following code to create a subscriber:

import { Novu } from "@novu/node";

// Insert your Novu API Key here
const novu = new Novu("<NOVU_API_KEY>");

// Create a subscriber on Novu
await novu.subscribers.identify("132", {
  email: "[email protected]",
  firstName: "John",
  lastName: "Doe",
  phone: "+13603963366",
});

For the sake of this article, we’ll make do with adding a subscriber via the terminal to speed the process up.

Set up Novu Notification Center in the App

Head over to scr/pages/index.js. We’ll modify this page to include the Novu Notification Center.

Import the Notification Center components from the Novu notification center package like so:

...
import {
  NovuProvider,
  PopoverNotificationCenter,
  NotificationBell,
} from "@novu/notification-center";

Display the Notification Center by adding the imported components like so:

...
return (
    <main
      className={`flex min-h-screen flex-col items-center justify-between p-24 ${inter.className}`}
    >
      <div className="z-10 max-w-5xl w-full items-center justify-between font-mono text-sm lg:flex">
        <p className="fixed left-0 top-0 flex w-full justify-center border-b border-gray-300 bg-gradient-to-b from-zinc-200 pb-6 pt-8 backdrop-blur-2xl dark:border-neutral-800 dark:bg-zinc-800/30 dark:from-inherit lg:static lg:w-auto lg:rounded-xl lg:border lg:bg-gray-200 lg:p-4 lg:dark:bg-zinc-800/30">
           Dev.to In-App Notifications
        </p>
        <div className="fixed bottom-0 left-0 flex h-48 w-full items-end justify-center bg-gradient-to-t from-white via-white dark:from-black dark:via-black lg:static lg:h-auto lg:w-auto lg:bg-none">
          <NovuProvider
            subscriberId={process.env.NEXT_PUBLIC_SUBSCRIBER_ID}
            applicationIdentifier={process.env.NEXT_PUBLIC_NOVU_APP_ID}
          >
            <PopoverNotificationCenter>
              {({ unseenCount }) => (
                <NotificationBell unseenCount={unseenCount} />
              )}
            </PopoverNotificationCenter>
          </NovuProvider>
        </div>
      </div>

      ...
      <div className="grid grid-cols-2">

Check your app, you should immediately see a notification bell.

Click the notification bell. The Notification Center will immediately pop up like so:

Add the following to your .env values:

NEXT_PUBLIC_SUBSCRIBER_ID=
NEXT_PUBLIC_NOVU_APP_ID=
NEXT_PUBLIC_NOVU_API_KEY=

Grab your Novu API Key and APP ID from the Settings section of your Novu dashboard.

Get the Identifier of the subscriber we created earlier and add it to the .env values.

In a real world app, the ID of the logged-in user should be passed to the subscriberID property of the NovuProvider component.

Note: We’re using it as an env variable because we’re not incorporating an authentication system in this tutorial. Ideally, once the user registers, the user ID should immediately be created as a subscriber and the ID be passed to the component.

Reload your app and the notification center should be squeaky clean like so:

Build the API to Publish dev.to Articles & Trigger In-App Notifications

Create a publish-devto-article.js file in the src/pages/api directory.

Add the code below to it to import the Novu SDK and specify the workflow trigger ID:

import { Novu } from "@novu/node";

const novu = new Novu(process.env.NEXT_PUBLIC_NOVU_API_KEY);

export const workflowTriggerID = "devto-notifications";

Note: The @novu/node Novu SDK can be used only in server-side.

The workflowTriggerID value is obtained from the workflow dashboard. Earlier, when we set up a workflow titled Devto Notifications, Novu created a slug from this title to serve as the trigger ID.

You can see it here:

Now add the following functions to the code in the publish-devto-article.js file:

...
export default async function handler(req, res) {
  const { article } = req.body;

  const response = await fetch("<https://dev.to/api/articles>", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "API-Key": process.env.NEXT_PUBLIC_DEVTO_API_KEY,
    },
    body: JSON.stringify({ article: article }),
  });

  /**
   * Get response of the published article from Dev.to
   */
  const dataFromDevto = await response.json();

  /**
   * Extra the essential details needed from the Dev.to response
   */
  const { title, url, published_timestamp, user } = dataFromDevto;

  /**
   * Send notification that a new article has been published
   */
  sendInAppNotification(user, title, url);

  return res.json({ message: dataFromDevto  });
}

/**
 * SEND IN-APP NOTIFICATION VIA NOVU
 * @param {*} userDetails
 * @param {*} articleTitle
 * @param {*} articleURL
 * @returns json
 */
async function sendInAppNotification(userDetails, articleTitle, articleURL) {
  await novu.trigger(workflowTriggerID, {
    to: {
      subscriberId: process.env.NEXT_PUBLIC_SUBSCRIBER_ID,
    },
    payload: {
      name: userDetails.name,
      article_url: articleURL,
      article_title: articleTitle,
      profile_image: userDetails.profile_image_90,
    },
  });

  return res.json({ finish: true });
}

The sendInAppNotification function block of code above triggers the notification via the Novu SDK:

Accepts the workflow trigger ID to determine which workflow to trigger.
Accepts the subscriber ID value to identify the notification recipient.
Accepts a payload object that represents the parameters to inject into the workflow variables.

The handler function block above makes a POST request to Dev.to to publish an article and then calls the sendInAppNotification to fire an In-App notification indicating that someone just published an article.

Note: The request body is passed from POSTMAN or Insomnia. Next, we will test our API with any of these API software tools.

Test the API with POSTMAN or Insomnia - Publish to Dev.to

Fire up either POSTMAN or Insomnia and make a request to the API we created and post a JSON request to publish an article on Dev.to.

Our API url: http://localhost:3000/api/publish-devto-article

I personally use & prefer Insomnia because it has a snappy and lovely UI. As you can see below, we passed some parameters (pulled from dev.to API docs) to enable us publish an article.

Next, check your app. You should see an instant notification about the new published article on Dev.to.

Click on the new post title. It should take you directly to the article on Dev.to!

You can try publishing as many as possible.

The Notification Center provides a lot of functions built-in. A user can mark all notifications as read, mark one notification as read, and delete a notification.

The Notification Center ships with a lot of props and options to customize the whole experience. Header, footer, colors can be customized to conform with your app.

Center the Notification Center, Just like Dev.to’s

You might be wondering, Dev.to’s Notification Center isn't a popover; it's centered on the page. How do I achieve that?

Simply replace the PopoverNotificationCenter component with the NotificationCenter component from the Novu package.

It should look something like this:

<NovuProvider
    subscriberId={process.env.NEXT_PUBLIC_SUBSCRIBER_ID}
    applicationIdentifier={process.env.NEXT_PUBLIC_NOVU_APP_ID}
>
  <NotificationCenter />
</NovuProvider>

However, Next.js uses Server side rendering so you might come across this issue on your page because the <NotificationCenter /> component makes use of the window object.

Let’s fix this issue by wrapping the component in a way that disables ssr and lazy loads it.

Create a components/notifications folder in the src/ directory. Go ahead and add these two files with the code below to them respectively:

index.js

export { default } from "./notifications";

notifications.js

import { NotificationCenter } from "@novu/notification-center";
import dynamic from "next/dynamic";
import React, { useCallback } from "react";

const Notifications = () => {
  const onNotificationClick = useCallback((notification) => {
    if (notification?.cta?.data?.url) {
      window.location.href = notification.cta.data.url;
    }
  }, []);

  return (
    <div>
      <NotificationCenter
        colorScheme="dark"
        onNotificationClick={onNotificationClick}
      />
    </div>
  );
};

export default dynamic(() => Promise.resolve(Notifications), {
  ssr: false,
});

The code above does the following:

It imports the original <NotificationCenter /> component from Novu.
It uses Next’s dynamic functionality that allows us to dynamically load a component on the client side, and to use the ssr option to disable server-rendering.
It defines a notificationClick handler for the onNotificationClick prop of the NotificationCenter component (The function that is called when the notification item is clicked).
The colorScheme is one of the props you can pass to the NotificationCenter component. It takes in either “light” or “dark” values to enable you set the UI mode.

Finally, head back to the pages/index.js file, import our newly created component and use it in the NovuProvider parent component like so:

...
import Notification from "../components/notifications";

...
...
...
<div className="fixed bottom-0 left-0 flex h-48 w-full items-end justify-center bg-gradient-to-t from-white via-white dark:from-black dark:via-black lg:static lg:h-auto lg:w-auto lg:bg-none">
    <NovuProvider
      subscriberId={process.env.NEXT_PUBLIC_SUBSCRIBER_ID}
      applicationIdentifier={process.env.NEXT_PUBLIC_NOVU_APP_ID}
    >
      <Notification />
    </NovuProvider>
</div>
...
...
...

Lastly, let's adjust the components' position to place the Notification Center in the middle of the page.

pages/index.js

import Image from "next/image";
import { Inter } from "next/font/google";
import {
  NovuProvider,
  PopoverNotificationCenter,
  NotificationBell,
} from "@novu/notification-center";

import Notification from "../components/notifications";

const inter = Inter({ subsets: ["latin"] });

export default function Home() {
  return (
    <main
      className={`flex min-h-screen flex-col items-center justify-between p-24 ${inter.className}`}
    >
      <div className="z-10 max-w-5xl w-full items-center justify-between font-mono text-sm lg:flex">
        <p className="fixed left-0 top-0 flex w-full justify-center border-b border-gray-300 bg-gradient-to-b from-zinc-200 pb-6 pt-8 backdrop-blur-2xl dark:border-neutral-800 dark:bg-zinc-800/30 dark:from-inherit lg:static lg:w-auto lg:rounded-xl lg:border lg:bg-gray-200 lg:p-4 lg:dark:bg-zinc-800/30">
          Dev.to In-App Notifications
        </p>
      </div>

      <div className="relative flex place-items-center before:absolute before:h-[300px] before:w-full sm:before:w-[480px] before:-translate-x-1/2 before:rounded-full before:bg-gradient-radial before:from-white before:to-transparent before:blur-2xl before:content-[''] after:absolute after:-z-20 after:h-[180px] after:w-full sm:after:w-[240px] after:translate-x-1/3 after:bg-gradient-conic after:from-sky-200 after:via-blue-200 after:blur-2xl after:content-[''] before:dark:bg-gradient-to-br before:dark:from-transparent before:dark:to-blue-700/10 after:dark:from-sky-900 after:dark:via-[#0141ff]/40 before:lg:h-[360px]">
        <NovuProvider
          subscriberId={process.env.NEXT_PUBLIC_SUBSCRIBER_ID}
          applicationIdentifier={process.env.NEXT_PUBLIC_NOVU_APP_ID}
        >
          <Notification />
        </NovuProvider>
      </div>

      <div className="mb-32 grid text-center lg:max-w-5xl lg:w-full lg:mb-0 lg:grid-cols-4 lg:text-left">
        <a
          href="<https://nextjs.org/docs?utm_source=create-next-app&utm_medium=default-template-tw&utm_campaign=create-next-app>"
          className="group rounded-lg border border-transparent px-5 py-4 transition-colors hover:border-gray-300 hover:bg-gray-100 hover:dark:border-neutral-700 hover:dark:bg-neutral-800/30"
          target="_blank"
          rel="noopener noreferrer"
        >
          <h2 className={`mb-3 text-2xl font-semibold`}>
            Docs{" "}
            <span className="inline-block transition-transform group-hover:translate-x-1 motion-reduce:transform-none">
              -&gt;
            </span>
          </h2>
          <p className={`m-0 max-w-[30ch] text-sm opacity-50`}>
            Find in-depth information about Next.js features and API.
          </p>
        </a>

        <a
          href="<https://nextjs.org/learn?utm_source=create-next-app&utm_medium=default-template-tw&utm_campaign=create-next-app>"
          className="group rounded-lg border border-transparent px-5 py-4 transition-colors hover:border-gray-300 hover:bg-gray-100 hover:dark:border-neutral-700 hover:dark:bg-neutral-800/30"
          target="_blank"
          rel="noopener noreferrer"
        >
          <h2 className={`mb-3 text-2xl font-semibold`}>
            Learn{" "}
            <span className="inline-block transition-transform group-hover:translate-x-1 motion-reduce:transform-none">
              -&gt;
            </span>
          </h2>
          <p className={`m-0 max-w-[30ch] text-sm opacity-50`}>
            Learn about Next.js in an interactive course with&nbsp;quizzes!
          </p>
        </a>

        <a
          href="<https://vercel.com/templates?framework=next.js&utm_source=create-next-app&utm_medium=default-template-tw&utm_campaign=create-next-app>"
          className="group rounded-lg border border-transparent px-5 py-4 transition-colors hover:border-gray-300 hover:bg-gray-100 hover:dark:border-neutral-700 hover:dark:bg-neutral-800/30"
          target="_blank"
          rel="noopener noreferrer"
        >
          <h2 className={`mb-3 text-2xl font-semibold`}>
            Templates{" "}
            <span className="inline-block transition-transform group-hover:translate-x-1 motion-reduce:transform-none">
              -&gt;
            </span>
          </h2>
          <p className={`m-0 max-w-[30ch] text-sm opacity-50`}>
            Discover and deploy boilerplate example Next.js&nbsp;projects.
          </p>
        </a>

        <a
          href="<https://vercel.com/new?utm_source=create-next-app&utm_medium=default-template-tw&utm_campaign=create-next-app>"
          className="group rounded-lg border border-transparent px-5 py-4 transition-colors hover:border-gray-300 hover:bg-gray-100 hover:dark:border-neutral-700 hover:dark:bg-neutral-800/30"
          target="_blank"
          rel="noopener noreferrer"
        >
          <h2 className={`mb-3 text-2xl font-semibold`}>
            Deploy{" "}
            <span className="inline-block transition-transform group-hover:translate-x-1 motion-reduce:transform-none">
              -&gt;
            </span>
          </h2>
          <p className={`m-0 max-w-[30ch] text-sm opacity-50 text-balance`}>
            Instantly deploy your Next.js site to a shareable URL with Vercel.
          </p>
        </a>
      </div>
    </main>
  );
}

Note: Ensure this is the full code of the pages/index.js file to avoid missing anything.

Now, reload your app. It should resemble Dev.to's centered Notification page. Yaayyyy!!

Publish a new article on Dev.to and observe how the notifications arrive via the centralized Notifications component, even without a notification bell. The Notification unseen counter shows right there.

Go one step further, make the background light mode & change the Notification Center to light mode.

Up Next: Build Dev.to Email Community Digest

You've learned how to develop an In-App Notification System in under 30 minutes. Over time, I've learned that the best developers use battle-tested tools to build their apps and systems.

Fortunately, there's more. I have additional tips to share with you. 😉

Next, I'll demonstrate how to use Novu to build an Email Community Digest, similar to the excellent digest from Dev.to, which keeps us updated on the top published articles.

Stay tuned for the next part of this article!

A reminder to check out the completed code for this article on GitHub. Let me know if you run into any issues at all.

Don't hesitate to ask any questions or request support. You can find me on Discord and Twitter. Please feel free to reach out.

Building an Investor List App with Novu and Supabase

Prosper Otemuyiwa — Mon, 22 Apr 2024 09:22:46 +0000

Supabase is an impressive open-source alternative to Firebase. It provides multiple tools that enable you to build comprehensive backend systems, including features for authentication, databases, storage, and real-time updates.

In this article, I'll guide you through the process of integrating your Next.js Supabase app with Novu. This integration will allow for a seamless, quick, and stress-free notification experience. Novu is an open-source notification infrastructure designed to assist engineering teams in creating robust product notification experiences.

We'll create an AI investor list app. This app will enable users to add details of angel investors interested in funding AI startups at the Pre-seed, Seed, and Series A stages. It will also announce and send in-app notifications when new investors are added.

Prerequisites

Before diving into the article, make sure you have the following:

Node.js installed on your development machine.
A Novu account. If you don’t have one, sign up for free at the web dashboard.
A Supabase account. If you don’t have one, sign up for free at the dashboard.

If you want to explore the code right away, you can view the completed code on GitHub.

Set up a Next.js App

To create a Next.js app, open your terminal, cd into the directory you’d like to create the app in, and run the following command:



npx create-next-app@latest supabase-novu

Go through the prompts:

cd into the directory, supabase-novu and run to start the app in your browser:



npm run dev

Set up Supabase in the App

Run the following command to add Supabase to the project:



npm i @supabase/supabase-js

Ensure you have signed up and created a new project on Supabase. It takes a couple of minutes to have your project instance set up on the dashboard. Once done, it should look similar to the image below:

We’ll go ahead to create a database table, investors, in our newly created project. Click on the SQL Editor on the dashboard and add the following SQL query to the editor.



CREATE TABLE investors (
 id bigint generated by default as identity primary key,
 email_reach text unique,
 name text,
 website text,
 funding_amount text,
 funding_type text,
 inserted_at timestamp with time zone default timezone('utc'::text, now()) not null
);

alter table investors enable row level security;

create policy "Investors are public." on investors for
   select using (true);

It should look like so:

Click on “Run” to run the query, create the table and apply a Policy.

This will go ahead to create an investors table. It also enables row level permission that allows anyone to query for all investors. In this article we are not concerned with authentication. However, this is something you should consider if you are to make it a production grade app.

You should be able to see your table created successfully!

Next, we need to connect our Next.js app with our Supabase backend.

Connect Supabase with Next.js

Create a .env.local or .env file in the root of the Next.js app and add the following environment variables:



NEXT_PUBLIC_SUPABASE_URL=<insert-supabase-db-url>
NEXT_PUBLIC_SUPABASE_ANON_KEY=<insert-anon-key>

Please replace the placeholders here with the correct values from your dashboard.

Click on the “Project Settings icon” at the bottom left and click on “API” to show you the screen below to obtain the correct values.

Create an utils folder inside the src directory of our Next.js project. Then go ahead to create a supabase.js file in it. Add the code below:



import { createClient } from "@supabase/supabase-js";

const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL;
const supabaseKey = process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY;

export const supabase = createClient(supabaseUrl, supabaseKey);

This is the Supabase client that we can use anywhere in our app going forward. The createClient function that we imported from the supabase library makes it possible.

Next, let’s set up our UI components and wire them to the Supabase backend.

Build UI to Interact with Supabase

Open up the src/pages/index.js file. We will modify it a lot.

Replace the content of the file with the code below:



import Image from "next/image";
import { Inter } from "next/font/google";
import { supabase } from "@/utils/supabase";
import { useEffect, useState } from "react";

const inter = Inter({ subsets: ["latin"] });

export default function Home() {
  const [investors, setInvestors] = useState([]);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    fetchAllInvestors();
  }, []);

  async function fetchAllInvestors() {
    try {
      setLoading(true);
      const { data, error } = await supabase.from("investors").select("*");

      if (error) throw error;
      setInvestors(data);
    } catch (error) {
      alert(error.message);
    } finally {
      setLoading(false);
    }
  }

  async function addInvestor(
    email_reach,
    name,
    website,
    funding_amount,
    funding_type
  ) {
    try {
      const { data, error } = await supabase
        .from("investors")
        .insert([
          {
            email_reach,
            name,
            website,
            funding_amount,
            funding_type,
          },
        ])
        .single();
      if (error) throw error;
      alert("Investor added successfully");
      fetchAllInvestors();
    } catch (error) {
      alert(error.message);
    }
  }

  function handleSubmit(e) {
    e.preventDefault();

    const email_reach = e.target.email_reach.value;
    const name = e.target.name.value;
    const website = e.target.website.value;
    const funding_amount = e.target.funding_amount.value;
    const funding_type = e.target.funding_type.value;

    addInvestor(email_reach, name, website, funding_amount, funding_type);
  }

  return (
    <main
      className={`flex min-h-screen flex-col items-center justify-between p-24 ${inter.className}`}
    >
      <div className="z-10 max-w-5xl w-full items-center justify-between font-mono text-sm lg:flex">
        <p className="fixed left-0 top-0 flex w-full justify-center border-b border-gray-300 bg-gradient-to-b from-zinc-200 pb-6 pt-8 backdrop-blur-2xl dark:border-neutral-800 dark:bg-zinc-800/30 dark:from-inherit lg:static lg:w-auto lg:rounded-xl lg:border lg:bg-gray-200 lg:p-4 lg:dark:bg-zinc-800/30">
          NOVU SUPABASE DASHBOARD
        </p>
        <div className="fixed bottom-0 left-0 flex h-48 w-full items-end justify-center bg-gradient-to-t from-white via-white dark:from-black dark:via-black lg:static lg:h-auto lg:w-auto lg:bg-none">
          <a
            className="pointer-events-none flex place-items-center gap-2 p-8 lg:pointer-events-auto lg:p-0"
            href="<https://vercel.com?utm_source=create-next-app&utm_medium=default-template-tw&utm_campaign=create-next-app>"
            target="_blank"
            rel="noopener noreferrer"
          >
            By{" "}
            <Image
              src="/vercel.svg"
              alt="Vercel Logo"
              className="dark:invert"
              width={100}
              height={24}
              priority
            />
          </a>
        </div>
      </div>

      <div class="grid grid-cols-2">
        <div className="mt-1 flex justify-center">
          <form onSubmit={handleSubmit}>
            <div>
              <label className="p-3 block">Name:</label>
              <input
                className="text-black p-2"
                type="text"
                name="name"
                required
                placeholder="Enter name"
              />
            </div>
            <div>
              <label className="p-3 block">Email Reach:</label>
              <input
                className="text-black p-2"
                type="text"
                name="email_reach"
                required
                placeholder="Enter investor email"
              />
            </div>
            <div className="mt-5">
              <label className="p-2 block">Website:</label>
              <input
                className="text-black p-2"
                type="text"
                name="website"
                required
                placeholder="Enter website"
              />
            </div>
            <div className="mt-5">
              <label className="p-2 block">Funding Amount (Up to X USD):</label>
              <input
                className="text-black p-2"
                type="text"
                name="funding_amount"
                required
                placeholder="Enter funding amount"
              />
            </div>
            <div className="mt-5">
              <label className="p-2 block">Funding Type:</label>
              <input
                className="text-black p-2"
                type="text"
                name="funding_type"
                required
                placeholder="Enter type of Funding"
              />
            </div>

            <button
              type="submit"
              className="bg-blue-600 p-2 rounded-md mt-5 px-12"
            >
              Submit Investor Details
            </button>
          </form>
        </div>

        <div className="mt-1 flex justify-center">
          {investors?.length === 0 ? (
            <div>
              <p>There are no investors yet</p>
            </div>
          ) : (
            <div>
              <p className="mb-5">Here are the investors available: </p>
              <table>
                <thead>
                  <tr>
                    <th>Name </th>
                    <th>Email Reach</th>
                    <th>Website</th>
                    <th className="p-3">Funding Amt</th>
                    <th>Funding Type </th>
                  </tr>
                </thead>
                <tbody className="">
                  {investors?.map((item) => (
                    <tr key={item.id}>
                      <td>{item.name}</td>
                      <td>{item.email_reach}</td>
                      <td>{item.website}</td>
                      <td>{item.funding_amount}</td>
                      <td>{item.funding_type}</td>
                    </tr>
                  ))}
                </tbody>
              </table>
            </div>
          )}
        </div>
      </div>

      <div className="mb-32 grid text-center lg:max-w-5xl lg:w-full lg:mb-0 lg:grid-cols-4 lg:text-left">
        <a
          href="<https://nextjs.org/docs?utm_source=create-next-app&utm_medium=default-template-tw&utm_campaign=create-next-app>"
          className="group rounded-lg border border-transparent px-5 py-4 transition-colors hover:border-gray-300 hover:bg-gray-100 hover:dark:border-neutral-700 hover:dark:bg-neutral-800/30"
          target="_blank"
          rel="noopener noreferrer"
        >
          <h2 className={`mb-3 text-2xl font-semibold`}>
            Docs{" "}
            <span className="inline-block transition-transform group-hover:translate-x-1 motion-reduce:transform-none">
              -&gt;
            </span>
          </h2>
          <p className={`m-0 max-w-[30ch] text-sm opacity-50`}>
            Find in-depth information about Next.js features and API.
          </p>
        </a>

        <a
          href="<https://nextjs.org/learn?utm_source=create-next-app&utm_medium=default-template-tw&utm_campaign=create-next-app>"
          className="group rounded-lg border border-transparent px-5 py-4 transition-colors hover:border-gray-300 hover:bg-gray-100 hover:dark:border-neutral-700 hover:dark:bg-neutral-800/30"
          target="_blank"
          rel="noopener noreferrer"
        >
          <h2 className={`mb-3 text-2xl font-semibold`}>
            Learn{" "}
            <span className="inline-block transition-transform group-hover:translate-x-1 motion-reduce:transform-none">
              -&gt;
            </span>
          </h2>
          <p className={`m-0 max-w-[30ch] text-sm opacity-50`}>
            Learn about Next.js in an interactive course with&nbsp;quizzes!
          </p>
        </a>

        <a
          href="<https://vercel.com/templates?framework=next.js&utm_source=create-next-app&utm_medium=default-template-tw&utm_campaign=create-next-app>"
          className="group rounded-lg border border-transparent px-5 py-4 transition-colors hover:border-gray-300 hover:bg-gray-100 hover:dark:border-neutral-700 hover:dark:bg-neutral-800/30"
          target="_blank"
          rel="noopener noreferrer"
        >
          <h2 className={`mb-3 text-2xl font-semibold`}>
            Templates{" "}
            <span className="inline-block transition-transform group-hover:translate-x-1 motion-reduce:transform-none">
              -&gt;
            </span>
          </h2>
          <p className={`m-0 max-w-[30ch] text-sm opacity-50`}>
            Discover and deploy boilerplate example Next.js&nbsp;projects.
          </p>
        </a>

        <a
          href="<https://vercel.com/new?utm_source=create-next-app&utm_medium=default-template-tw&utm_campaign=create-next-app>"
          className="group rounded-lg border border-transparent px-5 py-4 transition-colors hover:border-gray-300 hover:bg-gray-100 hover:dark:border-neutral-700 hover:dark:bg-neutral-800/30"
          target="_blank"
          rel="noopener noreferrer"
        >
          <h2 className={`mb-3 text-2xl font-semibold`}>
            Deploy{" "}
            <span className="inline-block transition-transform group-hover:translate-x-1 motion-reduce:transform-none">
              -&gt;
            </span>
          </h2>
          <p className={`m-0 max-w-[30ch] text-sm opacity-50 text-balance`}>
            Instantly deploy your Next.js site to a shareable URL with Vercel.
          </p>
        </a>
      </div>
    </main>
  );
}

Let’s go over some sections of this code block:



function handleSubmit(e) {
    e.preventDefault();

    const email_reach = e.target.email_reach.value;
    const name = e.target.name.value;
    const website = e.target.website.value;
    const funding_amount = e.target.funding_amount.value;
    const funding_type = e.target.funding_type.value;

    addInvestor(email_reach, name, website, funding_amount, funding_type);
  }

This function handles the submission of the form. It grabs the value from the form fields and passes it to the <span style="background-color: initial; font-family: inherit; font-size: inherit; color: initial;">addInvestor</span> function.



async function addInvestor(
    email_reach,
    name,
    website,
    funding_amount,
    funding_type
  ) {
    try {
      const { data, error } = await supabase
        .from("investors")
        .insert([
          {
            email_reach,
            name,
            website,
            funding_amount,
            funding_type,
          },
        ])
        .single();
      if (error) throw error;
      alert("Investor added successfully");
      fetchAllInvestors();
    } catch (error) {
      alert(error.message);
    }
  }

The addInvestor function takes in the right arguments and makes a query to supabase to insert the values into the investors table. This function also calls the fetchAllInvestors() function that retrieves all data from the investors table.



async function fetchAllInvestors() {
    try {
      setLoading(true);
      const { data, error } = await supabase.from("investors").select("*");

      if (error) throw error;
      setInvestors(data);
    } catch (error) {
      alert(error.message);
    } finally {
      setLoading(false);
    }
  }

As you can see from the code above, the fetchAllInvestors() function makes a SELECT query to the investors table to return and all the investors to the frontend.



const [investors, setInvestors] = useState([]);
const [loading, setLoading] = useState(true);

useEffect(() => {
  fetchAllInvestors();
}, []);

When the page loads up, it calls the fetchAllInvestors() function by default.

Run your app with npm run dev. It should look like this:

Add some investor details and submit. Your app should look like this now:

As we add items, they are saved to the Supabase database and displayed on the screen.

Inspect the table on Supabase. The data should appear as follows:

Next, we'll set up notifications in the app. Our goal is to alert everyone when a new investor is added to the database. This is where Novu comes into play!

Set up Novu in the App

Run the following command to install the Novu node SDK:



npm install @novu/node

Run the following command to install the Novu Notification Center package:



npm install @novu/notification-center

The Novu Notification Center package provides a React component library that adds a notification center to your React app. The package is also available for non-React apps.

Before we can start sending and receiving notifications, we need to set up a few things:

Create a workflow for sending notifications,
Create a subscriber - recipient of notifications.

Create a Novu Workflow

A workflow is a blueprint for notifications. It includes the following:

Workflow name and Identifier
Channels: - Email, SMS, Chat, In-App and Push

Follow the steps below to create a workflow:

Click Workflow on the left sidebar of your Novu dashboard.
Click the Add a Workflow button on the top left. You can select a Blank workflow or use one of the existing templates.
The name of the new workflow is currently “Untitled”. Rename it to notify users of new investors.
Select In-App as the channel you want to add.

Click on the recently added “In-App” channel and add the following text to it. Once you’re done, click “Update” to save your configuration.

The {{name}},{{funding_amount}} and {{email}} are custom variables. This means that we can pass them to our payload before we trigger a notification. You’ll see this when we create the API route to send notifications.

Create a subscriber

If you click “Subscriber” on the left sidebar of the Novu dashboard, you’ll see the subscriber list. As a first time Novu user, it will be an empty list. Subscribers are your app users.

Open your terminal and run the following script to create a subscriber:



curl --location '<https://api.novu.co/v1/subscribers>' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: ApiKey <NOVU_API_KEY>' \
  --data-raw '{
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]",
    "phone": "+1234567890"
    }'

Note: You can get your NOVU API Key from the settings section of your Novu dashboard.

Refresh the Subscribers page on your Novu dashboard. You should see the recently added subscriber now! You can also add a subscriber to Novu by running this API endpoint.

The best option to add a subscriber is via code in your backend. With Node.js code, you can run the following code to create a subscriber:



import { Novu } from "@novu/node";

// Insert your Novu API Key here
const novu = new Novu("<NOVU_API_KEY>");

// Create a subscriber on Novu
await novu.subscribers.identify("132", {
  email: "[email protected]",
  firstName: "John",
  lastName: "Doe",
  phone: "+13603963366",
});

Set up Novu Notification Center in the App

Head over to scr/pages/index.js. We’ll modify this page again to include the following:

Import and display the Novu Notification Center.
A function to trigger the notification when a new investor is added.

Import the Notification Center components from the Novu notification center package like so:



...
import {
  NovuProvider,
  PopoverNotificationCenter,
  NotificationBell,
} from "@novu/notification-center";

Display the notification center by adding the imported components like so:



...
return (
    <main
      className={`flex min-h-screen flex-col items-center justify-between p-24 ${inter.className}`}
    >
      <div className="z-10 max-w-5xl w-full items-center justify-between font-mono text-sm lg:flex">
        <p className="fixed left-0 top-0 flex w-full justify-center border-b border-gray-300 bg-gradient-to-b from-zinc-200 pb-6 pt-8 backdrop-blur-2xl dark:border-neutral-800 dark:bg-zinc-800/30 dark:from-inherit lg:static lg:w-auto lg:rounded-xl lg:border lg:bg-gray-200 lg:p-4 lg:dark:bg-zinc-800/30">
          NOVU SUPABASE DASHBOARD
        </p>
        <div className="fixed bottom-0 left-0 flex h-48 w-full items-end justify-center bg-gradient-to-t from-white via-white dark:from-black dark:via-black lg:static lg:h-auto lg:w-auto lg:bg-none">
          <NovuProvider
            subscriberId={process.env.NEXT_PUBLIC_SUBSCRIBER_ID}
            applicationIdentifier={process.env.NEXT_PUBLIC_NOVU_APP_ID}
          >
            <PopoverNotificationCenter>
              {({ unseenCount }) => (
                <NotificationBell unseenCount={unseenCount} />
              )}
            </PopoverNotificationCenter>
          </NovuProvider>
        </div>
      </div>

      ...
      <div className="grid grid-cols-2">

Now, your app should display a notification bell. When this bell is clicked, a notification user interface will pop up.

Note: The NovuProvider root Component ships with many props that can be used to customize the Notification Center to your taste. The floating popover component that appears when clicking on the NotificationBell button. It renders the NotificationCenter component inside its content.

Add the following Novu env variables to your .env.local file:



NEXT_PUBLIC_SUBSCRIBER_ID=
NEXT_PUBLIC_NOVU_APP_ID=
NEXT_PUBLIC_NOVU_API_KEY=

The Novu API Key and APP ID can be found in the Settings section of your Novu dashboard.

The Subscriber ID too is on your dashboard. Earlier in this article, we created a subscriber. We need that ID now.

Note: Adding the Subscriber ID to the env file is only for the purpose of this article. Your subscriber ID is the user ID obtained from an authenticated user. When a user logs in, their ID should be the value passed to the subscriberId property of the NovuProvider component.

Develop a Simple API to Trigger Notifications

Create a send-notification.js file in the src/pages/api directory. Add the code below to it:



import { Novu } from "@novu/node";

const novu = new Novu(process.env.NEXT_PUBLIC_NOVU_API_KEY);

export const workflowTriggerID = "notify-users-of-new-investors";

export default async function handler(req, res) {
  const { email, name, amount } = JSON.parse(req.body);

  await novu.trigger(workflowTriggerID, {
    to: {
      subscriberId: process.env.NEXT_PUBLIC_SUBSCRIBER_ID,
    },
    payload: {
      name: name,
      funding_amount: amount,
      email: email,
    },
  });

  return res.json({ finish: true });
}

The workflowTriggerID value is obtained from the workflow dashboard. Earlier, when we set up a workflow titled notify users of new investors, Novu created a slug from this title to serve as the trigger ID.

You can see it here:

The block of code below triggers the notification via the Novu SDK:

Accepts the workflow trigger ID to determine which workflow to trigger.
Accepts the subscriber ID value to identify the notification recipient.
Accepts a payload object that represents the parameters to inject into the workflow variables.



await novu.trigger(workflowTriggerID, {
    to: {
      subscriberId: process.env.NEXT_PUBLIC_SUBSCRIBER_ID,
    },
    payload: {
      name: name,
      funding_amount: amount,
      email: email,
    },
  });

Next, we need to set up one more thing on the frontend before we test the notification experience in our app.

Add a Notification Function to Index.js

Create a function inside the Home() function to call our recently created API like so:



async function triggerNotification(email_reach, name, funding_amount) {
    await fetch("/api/send-notification", {
      method: "POST",
      body: JSON.stringify({
        email: email_reach,
        name: name,
        amount: funding_amount,
      }),
    });
  }

Call the triggerNotification function just after the addInvestor function within the handleSubmit function.

Your handleSubmit function should now appear as follows:



function handleSubmit(e) {
    e.preventDefault();

    const email_reach = e.target.email_reach.value;
    const name = e.target.name.value;
    const website = e.target.website.value;
    const funding_amount = e.target.funding_amount.value;
    const funding_type = e.target.funding_type.value;

    addInvestor(email_reach, name, website, funding_amount, funding_type);
    triggerNotification(email_reach, name, funding_amount);
  }

Run your app again and submit a new investor detail. You should get an instant In-App notification with the details of the new investor.

A Step Further - Notify All Investors

We currently have a database containing investor emails. This is valuable data. Let's consider adding a feature to email these investors about new investment rounds from startups seeking funding.

We will not add a UI for the save of brevity. You can add a UI as an improvement and challenge.

Create a new file, email-investors.js within the pages/api directory.

Add the code below to it:



import { Novu } from "@novu/node";
import { supabase } from "@/utils/supabase";

const novu = new Novu(process.env.NEXT_PUBLIC_NOVU_API_KEY);

export const workflowTriggerID = "new-opportunities";

export default async function handler(req, res) {
  /**
   * Grab all investors
   */
  const { data, error } = await supabase.from("investors").select("*");

  /**
   * Map into a new array of subscriber data
   */
  const subscriberData = data.map((item) => {
    return {
      subscriberId: item.id.toString(),
      email: item.email_reach,
    };
  });

  const extractIDs = (data) => {
    return data.map((item) => item.subscriberId);
  };

  const subscriberIDs = extractIDs(subscriberData);

  /**
   * Bulk create subscribers on Novu
   */
  await novu.subscribers.bulkCreate(subscriberData);

  /**
   * Create a Topic on Novu
   */
  await novu.topics.create({
    key: "all-investors",
    name: "List of all investors on our platform",
  });

  /**
   * Assign subscribers to Topic
   */
  const topicKey = "all-investors";

  /**
   * Add all investors to the Topic
   */
  await novu.topics.addSubscribers(topicKey, {
    subscribers: subscriberIDs,
  });

  /**
   * Trigger workflow to the Topic
   */
  await novu.trigger(workflowTriggerID, {
    to: [{ type: "Topic", topicKey: topicKey }],
  });

  return res.json({ finish: true });
}

There are a series of events happening in this file. I’ll explain the steps below:

Fetch all investors data from Supabase
Return an array of objects of the supabase data with “subscriberId” and “email”.
Create all the investors as subscribers on Novu. Thankfully Novu has a `bulkCreate" function to create hundreds of subscribers at once instead of doing a complex loop yourself.
Create a topic on Novu. Topics offers a great way of sending notifications to multiple subscribers at once. In this case, it’s perfect for us. Here, we created a “all-investors” topic and then proceeded to add all the investors as subscribers to the topic.
The last step is what triggers the notification to all the investors. This is a simple syntax that triggers notifications to a topic. This means every subscriber belonging to that topic will receive a notification!

This block of code is where I set the trigger ID of the new Email workflow i created.

javascript export const workflowTriggerID = "new-opportunities";

If you haven’t, go ahead and create an email workflow on Novu. Name the workflow and use the corresponding trigger ID like I did.

Add content to the email workflow and save.

Note: At this stage, it's crucial to ensure that an email provider has been selected from the Integrations Store. This allows Novu to identify the email provider to use for delivering the email.

Run the API, /api/email-investors. The investors should get an email like this:

Conclusion

The combination of two robust open-source tools, Novu and Supabase, enables the rapid development of apps with a rich notification experience.

I hope you enjoyed building this simple investor list app as much as I did. Novu offers different channels such as Email, SMS, and Push, gives you a detailed activity feed to help debug your notifications and much more!

Do you have an idea or an app you'd like to build with Novu and Supabase? We are excited to see the incredible apps you'll create. Don't hesitate to ask any questions or request support. You can find us on Discord and Twitter. Please feel free to reach out.

The Ultimate Guide to Laravel Reverb: Real-Time Notifications

Prosper Otemuyiwa — Tue, 09 Apr 2024 10:18:00 +0000

You learned a lot about using Laravel Reverb in the first part of this guide. Now, you’ll learn how to add real-time notifications seamlessly to your Laravel apps.

If you've used Laravel Nova, you're likely familiar with the Notification Center. But what if you didn't need to build one from scratch? Imagine being able to add a real-time notification center to your app in less than five minutes.

If you're eager to explore the code immediately, you can view the completed code on GitHub. Let's dive in!

Introducing Novu

Novu is a notification infrastructure tool, built for engineering teams to help them build and set up rich product notification experiences.

Novu provides embeddable Notification Center components, APIs, SDKs and more to help you manage product communication across multiple channels. It provides a full notification infrastructure that provides robust analytics, digest, notification center components, multi-channel notifications and hundreds of notification providers.

Set Up Novu

The first step is to sign up on Novu.

Now, run the following command to install the Novu Laravel SDK:



composer require novu/novu-laravel

Publish the configuration file using this command:



php artisan vendor:publish --tag="novu-laravel-config"

A configuration file named novu.php with some sensible defaults will be placed in your config directory. Open up your .env file and add the NOVU_API_KEY variable to it.

Note: Grab your API key from Settings in your Novu dashboard.

Before we can start sending and receiving notifications in our app, we need to set up a few things:

Create a Novu workflow for sending notifications,
Create a subscriber - recipient of notifications,
Add a Novu Notification Center component inside our view to display real-time notifications.

Create a Novu Workflow

A workflow is a blueprint for notifications. It includes the following:

Workflow name and Identifier
Channels: - Email, SMS, Chat, In-App and Push.
Channel Notification Content Editor

Follow the steps below to create a workflow:

Click Workflow on the left sidebar of your Novu dashboard.
Click the Add a Workflow button on the top left. You can select a Blank workflow or use one of the existing templates.
The name of the new workflow is currently “Untitled”. Rename it to Laravel In-App Notifications
Select In-App as the channel you want to add.

5. Click on the recently added “In-App” channel and add the following text to it. Once you’re done, click “Update” to save your configuration.

The {{deliveryStatus }}, and {{deliveryHandler}} are custom variables. This means that we can pass them to our payload before we trigger a notification.

You’ll see this when we add the code to trigger a notification.

Create a subscriber

This implies that when a user registers an account in our app, we must also add them as a subscriber in Novu.

For a test run, open your terminal and run the following script to create a subscriber:



curl --location '<https://api.novu.co/v1/subscribers>' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: ApiKey <NOVU_API_KEY>' \
  --data-raw '{
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]",
    "phone": "+1234567890"
    }'

Note: You can use the details of the user that is already signed up on the app. Refresh the Subscribers page on your Novu dashboard. You should see the recently added subscriber. The one you added via the terminal!

The optimal approach is to add a subscriber through backend code. Just as the user is being added to the database, invoke the code to add the user as a subscriber on Novu. Let’s do that in our app.

We utilized the Laravel JetStream kit. Therefore, our authentication and login logic should be located within the app/Actions/Fortify directory.

Open up app/Actions/Fortify/CreateNewUser.php and modify the class to include Novu logic to create a subscriber on Novu from the user’s details.



<?php

namespace App\Actions\Fortify;

use App\Models\User;
use Illuminate\Support\Facades\Hash;
use Illuminate\Support\Facades\Validator;
use Laravel\Fortify\Contracts\CreatesNewUsers;
use Laravel\Jetstream\Jetstream;

class CreateNewUser implements CreatesNewUsers
{
    use PasswordValidationRules;

    /**
     * Validate and create a newly registered user.
     *
     * @param  array<string, string>  $input
     */
    public function create(array $input): User
    {
        Validator::make($input, [
            'name' => ['required', 'string', 'max:255'],
            'email' => ['required', 'string', 'email', 'max:255', 'unique:users'],
            'password' => $this->passwordRules(),
            'terms' => Jetstream::hasTermsAndPrivacyPolicyFeature() ? ['accepted', 'required'] : '',
        ])->validate();

        $user = User::create([
            'name' => $input['name'],
            'email' => $input['email'],
            'password' => Hash::make($input['password']),
        ]);

        // Create subscriber on Novu
        novu()->createSubscriber([
            'subscriberId' => $user->id,
            'email' => $user->email,
            'firstName' => $user->name,
        ])->toArray();

        return $user;
    }
}

Reload your app, create a brand new user and check the Novu subscribers section of your dashboard.

Set up & Display Novu Notification Center in your Laravel App

Head over to resources/views/components directory.

Create a notification-center.blade.php file in the directory and add the following code to it:



<notification-center-component
      style="{{ $style ?? '' }}"
      application-identifier="{!! $appId ?? '' !!}"
      subscriber-id="{!! $subscriberId ?? '' !!}"
    ></notification-center-component>

<script type="text/javascript">
    let nc = document.getElementsByTagName('notification-center-component')[0];
    nc.onLoad = () => console.log('notification center loaded!');
</script>

Head over to resources/views/layouts/app.blade.php file. At the scripts section, add the following to invoke the Novu Notification Center component:



<script src="<https://novu-web-component.netlify.app/index.js>" type="text/javascript" defer></script>

In the body, call the notification center blade component like so:



...
<div class="min-h-screen bg-gray-100 dark:bg-gray-900">
            @livewire('navigation-menu')


            @if (isset($header))


            <header class="bg-white dark:bg-gray-800 shadow">
                    <div class="max-w-7xl mx-auto py-6 px-4 sm:px-6 lg:px-8">
                        {{ $header }}  
                    </div>
                    <div class="max-w-7xl mx-auto py-6 px-4 sm:px-6 lg:px-8">
                        <x-notification-center app-id="MavBpIkktq7-" 
                                    subscriber-id="{{ auth()->user()->id }}" 
                                    style="display: inline-flex;">
                        </x-notification-center>
                    </div>
                </header>
            @endif

            <livewire:delivery-history />


            <main>
                {{ $slot }}
            </main>

</div>
...

From the code above, you can see that we added the following:



<div class="max-w-7xl mx-auto py-6 px-4 sm:px-6 lg:px-8">
      <x-notification-center app-id="MavBpIkktq7-" 
                  subscriber-id="{{ auth()->user()->id }}" 
                  style="display: inline-flex;">
      </x-notification-center>
</div>

Note: I have added the APP ID & Subscriber ID. The value of the APP ID is from the Novu Settings dashboard while the Subscriber ID is the ID of the logged in user.

Now you should have something like this on your dashboard showing the notification bell:

Trigger Real-time Notifications in your Laravel App

Open up app/Livewire/DeliveryHistory.php file. Here, we will add Novu code to trigger notification when a new delivery status is entered.

Add the code to the submitStatus() function like so:



public function submitStatus()
{
        PackageSent::dispatch(auth()->user()->name, $this->status, Carbon::now());

        /**
         *  Trigger Novu to fire the in-app notifications
         */
        novu()->triggerEvent([
            'name' => 'laravel-in-app-notifications',
            'payload' => [
                'deliveryStatus' => $this->status,
                'deliveryHandler' => auth()->user()->name
            ],
            'to' => [
                'subscriberId' => auth()->user()->id,
            ]
        ])->toArray();

        $this->reset('status');
}

The value of the name is the workflow trigger ID. Open up the Novu workflow we created on Novu dashboard, you will be able to identify the trigger ID like so:

Next, we included both deliveryStatus and deliveryHandler as payload items in the trigger code call. This allows our workflow to receive and display them as part of the notification content in the Notification Center.

Finally, we add the ID of the subscriber that we want to see the real-time notification when it has been triggered. This should always be the ID of the logged-in-user so that they can see the notification once it comes into the app.

One more thing…

Open up routes/channel.php and modify it to the code below:



<?php

use Illuminate\Support\Facades\Broadcast;

Broadcast::channel('delivery', function ($user) {
    return true;
});

We need to do this (return true always regardless of whoever is logged in) else we won’t be allowed to enter a status because the user that is logged in is no longer of ID 1.

Reload your app and attempt to add a status. You'll notice the notification appear in real time in the Notification Center. It's quick, instantaneous, and visually pleasing!

You can try different things in the Notification center pop up:

You can mark an individual message as read.
You can delete one individual message
You can mark all as read at once.

Novu makes it a breeze to add as many notification channels as possible without having to incorporate the logic of each notification provider. Write once, run as many channels as possible!

Check out the documentation on all the many things you can do with Novu’s Notification Center

Conclusion

We've covered how to use Laravel Reverb, from setup and configuration to building a real-time app. You've also learned how to leverage Novu in setting up effective, scalable real-time in-app notifications.

Laravel and Novu are powerful tools. When combined, they provide everything you need to build fast, robust, scalable, and real-time apps. I'm excited to see your next app.

If you have any questions, feel free to explore our documentation and quickstarts. You can also find me on Discord and Twitter. Don't hesitate to reach out.

The Ultimate Guide to Laravel Reverb

Prosper Otemuyiwa — Tue, 09 Apr 2024 10:11:13 +0000

Laravel Reverb is a first-party WebSocket server for Laravel applications, providing real-time communication capabilities between the client and server seamlessly.

Laravel Reverb has numerous appealing features, including:

Speed and scalability.
Support for thousands of simultaneous connections.
Integration with existing Laravel broadcasting features.
Compatibility with Laravel Echo.
First-class integration and deployment with Laravel Forge.

In this guide, I'll demonstrate how to use Laravel Reverb to develop a real-time Laravel app. You'll learn about channels, events, broadcasting, and how to use Laravel Reverb to create quick and real-time applications in Laravel.

If you're eager to explore the code immediately, you can view the completed code on GitHub. Let's get started!

Install a Fresh Laravel App

Go ahead and create a new laravel app.



laravel new carryon

I love to start new Laravel apps with one of the starter kits that ships with login, registration, email verification, etc. In this guide, I’ll use Laravel JetStream with Livewire.

You can follow the Laravel console prompt to ensure everything is set up properly with the right starter kit.

Run your migrations to set up the database with the users, jobs, cache & access tokens table.



php artisan migrate

Now, run your app with php artisan serve. For folks with Herd or Valet, your app should already be available on http://carryon.test

You should have something like this:- A fresh new Laravel app with JetStream enabled. So beautiful! 🎉

Install Laravel Reverb

Now, we need to install Laravel Reverb - our WebSocket Server into the Laravel app.

Run the following command in your console and choose the Yes option for any of the prompts that show up:



php artisan install:broadcasting

This command will do the following:

Publish the broadcasting config and channels route file.
Install Laravel Reverb (WebSocket server)
Install and build the Node dependencies required.

Next, open two new terminals to start up the reverb server and also run the client side.

First terminal: Start and run reverb server



php artisan reverb:start

The reverb server is usually run on the 8080 port by default. You can see that in your console. If you need to specify a custom host or port, you may do so via the --host and --port options when starting the server like so:



php artisan reverb:start --host=127.0.0.1 --port=9000

Second terminal: Run Vite to ensure any changes on the client is hot reloaded & instant.



npm run dev

Check your .env file. You will notice a few additions to it. It added the credentials for running Reverb. And for the frontend to connect with the Reverb server.

The BROADCAST_CONNECTION has been set to use reverb. Alternative broadcast drivers are pusher, ably and log.



BROADCAST_CONNECTION=reverb
...

REVERB_APP_ID=872050
REVERB_APP_KEY=ed5zsi5ebpdmawcqbwva
REVERB_APP_SECRET=zbttdgtacvuhfdo3dl0o
REVERB_HOST="localhost"
REVERB_PORT=8080
REVERB_SCHEME=http

VITE_REVERB_APP_KEY="${REVERB_APP_KEY}"
VITE_REVERB_HOST="${REVERB_HOST}"
VITE_REVERB_PORT="${REVERB_PORT}"
VITE_REVERB_SCHEME="${REVERB_SCHEME}"

One more thing. Open up resources/js/echo.js file:



import Echo from 'laravel-echo';

import Pusher from 'pusher-js';
window.Pusher = Pusher;

window.Echo = new Echo({
    broadcaster: 'reverb',
    key: import.meta.env.VITE_REVERB_APP_KEY,
    wsHost: import.meta.env.VITE_REVERB_HOST,
    wsPort: import.meta.env.VITE_REVERB_PORT ?? 80,
    wssPort: import.meta.env.VITE_REVERB_PORT ?? 443,
    forceTLS: (import.meta.env.VITE_REVERB_SCHEME ?? 'https') === 'https',
    enabledTransports: ['ws', 'wss'],
});

This file shows how Laravel Echo connects with the Reverb server. If you take a step further into the bootstrap.js file, you’ll see the echo file was imported. This means on start up, our app now uses and connects to reverb!

Show Workings - Test Reverb Connection

We have set up Laravel and Laravel Reverb. How do we test that our WebSocket server is working and the app is properly set up receive events on the Laravel frontend?

Step 1: Head over to the resources/js/echo.js file again. Here, we will set up a channel and tell it to listen to an event (doesn’t matter that we haven’t created it yet).

Add the following code to the file:



/** 
 * Testing Channels & Events & Connections
 */
window.Echo.channel("delivery").listen("PackageSent", (event) => {
    console.log(event);
});

Here, we have created a delivery channel & are listening on a PackageSent (This is imaginary for now) ****event.

Step 2: Restart the reverb server but with this command:



php artisan reverb:start --debug

We added a debug option to allow us to see the logs of the WebSocket connections from the terminal. It’s also a good idea to debug your realtime connections problem if it’s not working as intended.

Step 3: Now, reload your Laravel app. Click on the Login or Dashboard link and open the chrome dev tools. Ensure you narrow it down to WS as shown below.

You should see the realtime connections and events in the devtools like so:

See the delivery channel we created. Now, you can also see the ping and pong events. This means our server is ready and waiting to stream real-time connections. Yaaay!

You can also see the evidence on the server. Check the console of the reverb debug. You should see something like this:

Step 4: Create the PackageSent event so that we can send events.

Run the following artisan command to create it quickly:



php artisan make:event PackageSent

Open up the app/Events/PackageSent.php to see the event boilerplate created.



<?php

namespace App\Events;

use Illuminate\Broadcasting\Channel;
use Illuminate\Broadcasting\InteractsWithSockets;
use Illuminate\Broadcasting\PresenceChannel;
use Illuminate\Broadcasting\PrivateChannel;
use Illuminate\Contracts\Broadcasting\ShouldBroadcast;
use Illuminate\Foundation\Events\Dispatchable;
use Illuminate\Queue\SerializesModels;

class PackageSent
{
    use Dispatchable, InteractsWithSockets, SerializesModels;

    /**
     * Create a new event instance.
     */
    public function __construct()
    {
        //
    }

    /**
     * Get the channels the event should broadcast on.
     *
     * @return array<int, \Illuminate\Broadcasting\Channel>
     */
    public function broadcastOn(): array
    {
        return [
            new PrivateChannel('channel-name'),
        ];
    }
}

Now, replace it with the code below:

app/Events/PackageSent.php



<?php

namespace App\Events;

use Illuminate\Broadcasting\Channel;
use Illuminate\Broadcasting\InteractsWithSockets;
use Illuminate\Broadcasting\PresenceChannel;
use Illuminate\Broadcasting\PrivateChannel;
use Illuminate\Contracts\Broadcasting\ShouldBroadcast;
use Illuminate\Foundation\Events\Dispatchable;
use Illuminate\Queue\SerializesModels;

class PackageSent implements ShouldBroadCast
{
    use Dispatchable, InteractsWithSockets, SerializesModels;

    /**
     * Create a new event instance.
     */
    public function __construct(
        public string $status,
        public string $deliveryHandler
    )
    {

    }

    /**
     * Get the channels the event should broadcast on.
     *
     * @return Illuminate\Broadcasting\Channel
     */
    public function broadcastOn(): Channel
    {
        return new Channel('delivery');
    }
}

The following happened:

Now the class implements ShouldBroadCast. This means the event should be broadcasted via Laravel Echo.
Passed in two parameters to the constructor. Status of the package and the handler. We need this to know the status of the package and who is responsible for it at anytime.
The broadCastOn() method by default allows us to broadcast to many channels at a time. However, in this case we want to broadcast to only one. So it was modified to return only one channel; delivery , instead of an array of channels.

Note: This is a public channel. We are broadcasting the PackageSent event on a public channel. The channels are either instances of Channel, PrivateChannel, or PresenceChannel. PrivateChannel and PresenceChannel require authorization for any user to subscribe to while any random user can subscribe public channels.

Step 5: Dispatch the PackageSent event.

Open your terminal and fire up the amazing artisan tinker by running the following command:



php artisan tinker

Just before we write code in the tinker terminal. Open a new terminal and ensure your queue is running like so:



php artisan queue:listen

Note: This is very important because event jobs are queued to the database by default. So our queue needs to be able to listen to the jobs to fire them.

Now call the event and dispatch it like so within the tinker terminal:



> use App\Events\PackageSent;
> PackageSent::dispatch('processed', 'prosper');

> PackageSent::dispatch('delivered', 'olamide');

This will go ahead and fire the PackageSent event twice.

Check your queue console to see if the jobs were processed.

Yaaay, it was processed!

Now, go ahead and check your Laravel app in the dev tools console. You should see the dispatched event and the data we sent.

Woow! Just amazing!!

We’ve been doing this from the terminal. Next, let’s do this straight from the UI with user interaction.

Build A Real-time Delivery History UI

Open your terminal and run the command below to create a livewire component.



php artisan make:livewire DeliveryHistory

Laravel will create a class and corresponding delivery-history blade view for the UI elements.

Open up resources/views/layouts/app.blade.php file:

Add the delivery-history livewire component just below the @if code block in the code like so:



....
<body class="font-sans antialiased">
        <x-banner />

        <div class="min-h-screen bg-gray-100 dark:bg-gray-900">
            @livewire('navigation-menu')


            @if (isset($header))
                <header class="bg-white dark:bg-gray-800 shadow">
                    <div class="max-w-7xl mx-auto py-6 px-4 sm:px-6 lg:px-8">
                        {{ $header }}
                    </div>
                </header>
            @endif

            <livewire:delivery-history />


            <main>
                {{ $slot }}
            </main>

        </div>

        @stack('modals')

        @livewireScripts
    </body>

Open up resources/views/livewire/delivery-history.blade.php file & let’s add a full blown UI to it. Copy the code below and add it:



<div class="py-12">
    <div class="space-y-4">
        <div class="rounded-lg max-w-7xl mx-auto sm:px-6 lg:px-8 dark:bg-gray-800">
            <div class="py-2">
            <form wire:submit.prevent="submitStatus" class="flex gap-2">
                <input type="text" placeholder="Enter delivery status....." wire:model="status" x-ref="statusInput" name="status" id="status" class="block w-full" />
                <button class=" hover:bg-blue-500 text-blue-700 font-semibold hover:text-white py-2 px-4 border border-blue-500 hover:border-transparent rounded">
                  ENTER
                </button>
        </form>
            </div>
        </div>
    </div>

    <div class="mt-5">
        <div class="rounded-lg max-w-7xl mx-auto sm:px-6 lg:px-8 dark:bg-gray-800">
            <div class="flex items-center justify-between"><h5 class="forge-h5">Package Delivery History</h5></div>
            <div class="py-2">
                <table class="w-full text-left">

                   @if( count($packageStatuses) > 0)
                    <thead class="text-gray-500">
                        <tr class="h-10">
                            <th class="pr-4 font-normal">User</th>
                            <th class="w-full pr-4 font-normal">Written Status</th>
                            <th class="pr-4 font-normal">Time</th>
                            <th class="pr-4 font-normal">Status</th>
                            <th></th>
                        </tr>
                    </thead>
                    <tbody class="max-w-full text-white">
                        @foreach($packageStatuses as $status)
                            <tr class="h-12 border-t border-gray-100 dark:border-gray-700">


                                <td class="whitespace-nowrap pr-4">
                                    <div class="flex items-center">
                                        <div class="text-truncate w-32"> {{ $status['deliveryPersonnel'] }}</div>
                                    </div>
                                </td>
                                <td class="whitespace-nowrap pr-4">
                                    <div class="flex items-center">
                                        <div class="text-truncate w-32">{{ $status['deliveryStatus'] }}</div>
                                    </div>
                                </td>
                                <td class="whitespace-nowrap pr-4">
                                    <div class="flex items-center">
                                        <div class="text-truncate w-32">{{ Carbon\\\\Carbon::parse($status['deliveryTime'])->diffForHumans() }} </div>
                                    </div>
                                </td>
                                <td class="whitespace-nowrap pr-4">
                                    <div class="flex items-center">
                                        <div class="text-truncate w-32">

                                            @if ($status['deliveryStatus'] == 'Port')
                                                <div class="h-2 rounded-full bg-blue-600 transition-all transition-2s ease-in-out">
                                                </div>
                                            @endif

                                            @if ($status['deliveryStatus'] == 'Processing')
                                                <div class="h-2 rounded-full bg-yellow-600 transition-all transition-2s ease-in-out">
                                                </div>
                                            @endif

                                            @if ($status['deliveryStatus'] == 'Shipped')
                                                <div class="h-2 rounded-full bg-pink-600 transition-all transition-2s ease-in-out">
                                                </div>
                                            @endif

                                            @if ($status['deliveryStatus'] == 'Delivered')
                                                <div class="h-2 rounded-full bg-green-600 transition-all transition-2s ease-in-out">
                                                </div>
                                            @endif

                                            @if (!in_array($status['deliveryStatus'], ['Port', 'Processing', 'Shipped', 'Delivered']))
                                                <div class="h-2 rounded-full bg-red-600 transition-all transition-2s ease-in-out">
                                                </div>
                                            @endif
                                        </div>
                                    </div>
                                </td>   
                            </tr>
                        @endforeach
                    </tbody>
                   @else
                    <h3> No History yet... </h3>
                   @endif
                </table>
            </div>
        </div>
    </div>
</div>

Let’s look at the code above for a bit and understand what’s going on:

There’s a livewire form field with an input text field and button.
When the button is clicked, it calls the submitStatus function. Now this function will be defined later in the DeliveryHistory class component.
In the table section, we are looping over a $packageStatuses array variable and displaying the contents in the UI.
If the $packageStatuses array is empty, we show a “No History yet…” section.

Wire Up The Delivery History Class Component

Open up the app/Livewire/DeliveryHistory.php class and replace the content with the code below:



<?php

namespace App\Livewire;

use Carbon\Carbon;
use Livewire\Component;
use Livewire\Attributes\On;
use App\Events\PackageSent;

class DeliveryHistory extends Component
{
    public array $packageStatuses = [
    ];

    public string $status = '';

    public function submitStatus()
    {
        PackageSent::dispatch(auth()->user()->name, $this->status, Carbon::now());

        $this->reset('status');
    }

    #[On('echo:delivery,PackageSent')]
    public function onPackageSent($event)
    {
        $this->packageStatuses[] = $event;
    }

    public function render()
    {
        return view('livewire.delivery-history');
    }
}

Let’s break down what’s happening the code above and see how it connects with the blade UI.

The render() method fetches and display the content of the delivery-history blade file to the UI.
There are two class variables, $status and $packageStatuses. Livewire automatically makes them accessible from the corresponding blade view.
The submitStatus() method is called when the form is submitted from the UI via livewire. In this method, we dispatch the PackageSent event with 3 arguments. The logged-in user’s name, the value of the text field in the UI, and the current time. When the PackageSent event is dispatched, how do we get the result of the event real-time via Reverb?
Laravel livewire has a seamless way of retrieving real-time events with Laravel Echo via the On Attribute. We defined a function onPackageSent() that dumps the payload of the recently dispatched $event into the $packageStatuses array. The attribute #[On('echo:delivery,PackageSent')] makes it possible for us to specify the channel name and the event for livewire to listen to! Feels magical!

Modify the PackageSent Laravel Event

Before we test the app, we need to modify the constructor arguments of the PackageSent event class.

Open up app/Events/PackageSent.php and modify the constructor to take in 3 arguments; $deliveryPersonnel, $deliveryStatus, $deliveryTime.



<?php

namespace App\Events;

use Illuminate\Broadcasting\Channel;
use Illuminate\Broadcasting\InteractsWithSockets;
use Illuminate\Broadcasting\PresenceChannel;
use Illuminate\Broadcasting\PrivateChannel;
use Illuminate\Contracts\Broadcasting\ShouldBroadcast;
use Illuminate\Foundation\Events\Dispatchable;
use Illuminate\Queue\SerializesModels;

class PackageSent implements ShouldBroadCast
{
    use Dispatchable, InteractsWithSockets, SerializesModels;

    /**
     * Create a new event instance.
     */
    public function __construct(
        public string $deliveryPersonnel,
        public string $deliveryStatus,
        public string $deliveryTime
    )
    {

    }

    /**
     * Get the channels the event should broadcast on.
     *
     * @return Illuminate\Broadcasting\Channel
     */
    public function broadcastOn(): Channel
    {
        return new Channel('delivery');
    }
}

Reload and Test The App

Now, you can test the app.

Enter any status in the textfield and hit the Enter button OR hit Enter on your keyboard and watch everything come together.

Note: In the delivery history blade view, we defined a list of statuses: Port, Processing, Shipped, Delivered.

Test The App While Firing Events From The Console

We have been able to test the app via the UI and it works really well!

Now, open up tinker again and fire the event and watch how the UI updates in realtime! 🎉

BroadCast Events Only To A Private Channel

We’ve been listening and broadcasting events on a public channel. Now, let’s see how to do this securely on a private channel.

We want to restrict subscription to our delivery channel to authorized users only. Let's make some changes in several areas across the app.

Step 1: Change Channel to PrivateChannel in PackageSent Event.



...
/**
 * Get the channels the event should broadcast on.
 *
 * @return Illuminate\Broadcasting\PrivateChannel
 */
public function broadcastOn(): Channel
{
    return new PrivateChannel('delivery');
}
...

Step 2: Instruct the Livewire DeliveryHistory Component to also listen on a Private Channel by changing the value from echo:delivery to echo-private:delivery in the On Attribute like so:



...
#[On('echo-private:delivery,PackageSent')]
public function onPackageSent($event)
{
    $this->packageStatuses[] = $event;
}
...

Reload your app, you will see a 403 forbidden error now for WebSocket connections.

Step 3: Open up the routes/channels.php file. This is where the authorization logic resides to determine who can listen to a given channel. Replace the code there with the following:



use Illuminate\Support\Facades\Broadcast;

Broadcast::channel('delivery', function ($user) {
    return (int) $user->id === 1;
});

In the above code, the channel method accepts two arguments: the name of the channel and a callback which returns true or false indicating whether the user is authorized to listen on the channel.

Here, we have instructed the app to permit and authorize only a logged-in user with ID 1 to listen to the delivery channel.

Now, ensure that the user with ID 1 is logged into the app and check if there's a WebSocket forbidden error.

Viola! No error and we can listen on the channel!

Try logging with another user and see what happens.

Forbidden! This user is not authorized to listen on this channel.

Ideally, in a more robust scenario, each user should be subscribed to their own private channels. This method prevents users from accessing each other's specific events. This is great for game rooms, chat rooms, log history specific boards, etc.

So your authorization might need to look like this:



use Illuminate\Support\Facades\Broadcast;

Broadcast::channel('delivery.{id}', function ($user, $id) {
    return (int) $user->id === $id;
});

This means the following:

Authenticated user with ID 1 can only listen to channel delivery.1
Authenticated user with ID 2 can only listen to channel delivery.2
Authenticated user with ID 3 can only listen to channel delivery.3

All authorization callbacks receive the currently authenticated user as their first argument and any additional wildcard parameters as their subsequent arguments.

Take It Further!

Laravel Reverb is a fantastic addition to the extensive collection of impressive developer packages in the Laravel ecosystem.

In this guide, I invite you to extend the app by adding a persistent layer for delivery statuses. When the event is triggered, it should also be stored in the database.

Next Up: Handle Notifications in Your Laravel Reverb App

I hope you found this guide enjoyable and informative. In the next section, I'll demonstrate how to seamlessly integrate real-time notifications into your Laravel Reverb App.

Stay tuned for more, as I'm confident you'll acquire new strategies and abilities that will assist you in building your next app!

If you have an idea that requires real-time capabilities, Laravel and Reverb could be the perfect fit. You can find me on Discord and Twitter. Don't hesitate to reach out.

DEV Community: Prosper Otemuyiwa

Building Multi-Agent Research Systems using Vercel AI SDK

The Architecture

Why Parallel Dispatch Matters

Data Flow: From Query to Report

Setup

The Specialist Agents

Financial Analyst

Scientist

Journalist

The Orchestrator

The API Route

Running it

What @valyu/ai-sdk Provides

Extending the System

Perplexity Sonar Alternatives for Developers (2026)

What Perplexity Sonar Actually Is

Why Developers Are Switching

Alternatives for Standard Sonar Use Cases

Valyu DeepSearch API

Linkup

Tavily

Alternatives for Sonar Deep Research Specifically

Head-to-Head Comparison Table

Which Alternative for Which Use Case

A Note on What Sonar Does Well

FAQ

What is AI Search?

Table of Contents

Why AI Agents Need Search

AI-Native Search vs Traditional Keyword Search

The Five Things That Need to Be First-Class

1. Breadth: Web + Proprietary Sources

2. Depth: Content, Not Links

3. Freshness: Real-Time, Not Stale Caches

4. AI-Native Query Understanding

5. LLM Integration: First-Class, Not Bolted On

The Evaluation Checklist

The Good, and the Bad

The Good

The Bad

Benchmark Reality Check

FAQ

Deep Research API for AI Agents: The Complete Guide (2026)

What Is a Deep Research API?

The Deep Research API Landscape in 2026

On pricing transparency

The critical column: Data Sources

When Web Search Is Not Enough

Deep Research API for Researchers & Non-Developers

Building with Valyu's Deep Research API (for Developers)

Installation

Quick Start

Waiting for Results

Research Modes

Proprietary Source Selection

Structured JSON Output

Webhooks for Production

Date Filtering

Attach Documents for Analysis & Inclusion

Deep Research API in Production

Benchmarks

Frequently Asked Questions

Summary

Why your AI agent keeps hallucinating financial data (and how to fix it)

Why the training cutoff ruins financial agents

The two approaches that don't actually work

Approach 1: Prompt the model harder

Approach 2: RAG with financial documents

The actual fix: live data as tools

Basic setup

Building a financial research agent

Going deeper: SEC filings and Earnings data

Combining multiple financial data sources

Handling the response in a streaming UI

What changes once you do this

FAQ

How I Built a Live Stock Market AI Agent in ~40 Lines of TypeScript

What we're building

Setup

What `@valyu/ai-sdk` Provides