DEV Community: Marcus ma

How to Add a Real-Time Search Layer to an Agent Graph

Marcus ma — Thu, 06 Aug 2026 05:32:27 +0000

Marcus ma

Aug 6

How to Add a Real-Time Search Layer to an Agent Graph

#ai #agents #api #webdev

7 min read

How I Built a Source-Backed Research Paper Search Workflow

Marcus ma — Thu, 06 Aug 2026 05:27:26 +0000

How I Built a Source-Backed Research Paper Search Workflow

Searching for research papers sounds straightforward when you already know the title, author, DOI, or exact academic terminology.

The harder cases begin with incomplete information.

You may only remember:

A research question
An experimental result
A rough description of the method
The relationship between two variables
A paper you saw months ago but cannot name

Traditional keyword search can struggle in these situations. The paper may use terminology that differs from the words you remember, even when the underlying research question is highly relevant.

I wanted to design a workflow that could start with an ordinary natural-language question, discover potentially relevant public research sources, read the original material, and keep every extracted finding connected to its source.

The resulting workflow looks like this:

Research Question
      ↓
Query Expansion
      ↓
Search API
      ↓
Result Filtering
      ↓
Original Source Reading
      ↓
Research Matrix
      ↓
Manual Verification

Disclosure: This article uses Cloudsway SmartSearch and Reader as one implementation example. The overall workflow is provider-agnostic and can be adapted to other search and document-processing APIs.

The Problem With Searching by Exact Keywords

Academic concepts are often described using multiple terms.

For example, a researcher studying communication between AI agents might search for:

multi-agent communication frequency

But related papers may use phrases such as:

agent coordination
cooperative agents
decentralized collaboration
message passing
team communication
coordination overhead

A single keyword query can miss relevant work simply because the authors used different vocabulary.

Natural-language search provides another starting point.

Instead of trying to predict the exact terminology, the researcher can describe the underlying problem:

Find recent research investigating whether increasing communication between AI agents always improves collaborative task performance.

This query provides more context than a short keyword string.

It contains:

The research domain: multi-agent systems
The independent variable: communication frequency
The outcome: collaborative performance
The suspected relationship: more communication may not always help
A recency requirement: recent research

A search-enabled research assistant can use these signals to create several narrower queries rather than depending on one exact phrase.

Step 1: Define the Research Question

Before calling a search API, the workflow should structure the user's question.

A useful research-question object might contain:

research_question = {
    "topic": "multi-agent coordination",
    "independent_variable": "communication frequency",
    "outcome": "collaborative task performance",
    "research_interest": "whether more communication always improves performance",
    "date_range": "recent research",
}

The fields will vary by discipline, but the general principle is consistent: extract the concepts that should guide retrieval.

For empirical research, useful fields may include:

Population or system
Intervention or independent variable
Outcome
Method
Context
Time range
Language
Publication type

The workflow should preserve the original user question alongside this structured version. The structured fields help generate queries, while the original wording helps evaluate whether a result actually answers the user's question.

Step 2: Generate Query Variations

The next stage expands the research question into multiple search formulations.

For example:

queries = [
    "multi-agent communication frequency collaborative performance research",
    "agent communication overhead coordination experiments",
    "does more communication improve multi-agent cooperation",
    "decentralized agent coordination message frequency study",
    "limited communication multi-agent task performance paper",
]

These queries cover different ways researchers might describe the same problem.

A more advanced planner could generate separate query categories:

query_groups = {
    "direct": [
        "multi-agent communication frequency performance",
    ],
    "alternative_terms": [
        "agent message passing coordination quality",
        "cooperative agents communication overhead",
    ],
    "contradictory_evidence": [
        "excessive communication reduces multi-agent performance",
        "limited communication improves agent collaboration",
    ],
    "source_specific": [
        "site:arxiv.org multi-agent communication coordination",
        "site:acm.org multi-agent communication performance",
    ],
}

Searching for contradictory evidence is especially useful.

A research workflow should not only retrieve sources that appear to confirm the initial assumption. It should also look for papers reporting null effects, boundary conditions, trade-offs, or opposing findings.

Step 3: Search Across Public Research Sources

A search API can act as the discovery layer.

The goal at this stage is not to generate a literature review immediately. It is to identify potentially useful sources and preserve enough metadata to evaluate them.

Possible destinations include:

arXiv
PubMed
Semantic Scholar
Conference websites
University repositories
Research-group websites
Journal landing pages
Publicly accessible PDFs

In this workflow, I use Cloudsway SmartSearch as the search layer.

The search response should be normalized into a consistent format before other parts of the application process it.

For example:

from typing import TypedDict


class SearchResult(TypedDict):
    title: str
    url: str
    summary: str
    published_at: str | None
    source_domain: str | None
    query: str

The provider-specific response can then be converted into this schema:

def normalize_search_result(result: dict, query: str) -> SearchResult:
    return {
        "title": result.get("title", ""),
        "url": result.get("url", ""),
        "summary": result.get("summary", ""),
        "published_at": result.get("published_at"),
        "source_domain": result.get("source"),
        "query": query,
    }

This keeps the rest of the workflow independent from the search provider's exact response format.

Step 4: Filter and Deduplicate the Results

The same paper may appear in several places:

A preprint platform
A journal page
A university repository
An author's personal website
A conference page
A secondary article discussing the paper

Without deduplication, an application may mistakenly treat these pages as separate pieces of evidence.

A basic deduplication process can compare:

Normalized titles
DOI values, when available
Author names
Publication year
Canonical URLs
Similarity between abstracts

Conceptually:

def normalize_title(title: str) -> str:
    return " ".join(
        title.lower()
        .replace(":", "")
        .replace("-", " ")
        .split()
    )


def deduplicate(results: list[SearchResult]) -> list[SearchResult]:
    unique_results = []
    seen_titles = set()

    for result in results:
        normalized = normalize_title(result["title"])

        if normalized and normalized not in seen_titles:
            seen_titles.add(normalized)
            unique_results.append(result)

    return unique_results

This example is deliberately simple. A production system would need stronger matching logic, especially when titles differ between preprint and published versions.

After deduplication, results can be ranked using criteria such as:

Relevance to the research question
Publication date
Source authority
Availability of the original paper
Presence of an abstract or full text
Methodological relevance
Language

The workflow should also distinguish between source types.

A journal landing page, preprint, university repository, and blog post may all be useful, but they do not provide the same level of evidence.

Step 5: Read the Original Source

A title and search snippet are not enough for a literature review.

They may help determine whether a paper is worth opening, but they rarely provide sufficient detail about:

Research design
Sample or dataset
Experimental environment
Variables
Evaluation metrics
Main findings
Limitations
Boundary conditions

The workflow therefore needs a separate reading stage.

In this implementation, Cloudsway Reader processes selected webpages and supported PDF content after SmartSearch discovers the sources.

The separation is useful:

SmartSearch
  ↓
Find potentially relevant sources
  ↓
Reader
  ↓
Process selected original content
  ↓
Structured extraction

Search is responsible for discovery.

Reader is responsible for turning the selected source into usable context.

The application can then ask the extraction model to return a structured record:

class PaperRecord(TypedDict):
    title: str
    source_url: str
    research_question: str
    method: str
    dataset_or_sample: str
    metrics: list[str]
    main_findings: list[str]
    limitations: list[str]
    verification_notes: list[str]

An extraction prompt might look like this:

Read the provided research source and extract:

1. The research question
2. The proposed method
3. The dataset, sample, or experimental environment
4. The evaluation metrics
5. The main findings
6. The limitations explicitly reported by the authors
7. Statements that cannot be verified from the available content

Do not infer missing methodological details.
Keep every extracted statement connected to the source URL.

The final instruction matters.

A research assistant should distinguish between information that appears in the source and conclusions inferred by the model.

Step 6: Build a Research Matrix

The extracted paper records can be stored in a research matrix.

For example:

Paper	Source	Method	Dataset or Setting	Main Finding	Limitations	Verification
Paper A	Original URL	Experimental study	Multi-agent simulation	Finding summary	Reported limitations	Needs full-text review
Paper B	Original URL	Benchmark evaluation	Collaborative task environment	Finding summary	Limited task diversity	Abstract verified
Paper C	Original URL	Theoretical analysis	Decentralized agents	Finding summary	No empirical test	Full source reviewed

The research matrix makes it easier to:

Compare methods
Identify conflicting findings
Track missing information
Detect repeated datasets
Organize papers by theme
Preserve source links
Prepare a literature review

A simple data structure could look like:

research_matrix = []

for paper in selected_papers:
    record = read_and_extract(paper)
    research_matrix.append(record)

This matrix should not be treated as the final literature review.

It is an intermediate research artifact that helps a human researcher understand and verify the source set.

Step 7: Keep Claims Connected to Sources

One of the biggest risks in AI-assisted research is losing the connection between a generated statement and its original source.

For example, the system might generate:

Increased communication improves coordination only up to a certain threshold.

That statement should not exist in the final output without metadata showing:

Which paper reported it
Where the paper was found
Whether the full text was read
Whether the finding came from the authors or was inferred
Whether another source reported a conflicting result

A claim object can preserve this connection:

claim = {
    "text": "Increased communication improved coordination only up to a threshold.",
    "source_title": "Example Paper",
    "source_url": "https://example.org/paper",
    "evidence_type": "reported finding",
    "verification_status": "full text reviewed",
}

The final synthesis stage should consume these claim objects rather than disconnected summaries.

This reduces the likelihood of citations being added after the answer has already been generated.

Step 8: Handle Missing or Incomplete Evidence

The workflow must be allowed to return incomplete results.

A search API cannot guarantee that every important paper will be found. Some papers may be:

Behind paywalls
Missing from public indexes
Published under unexpected terminology
Available only in a different language
Incorrectly dated
Poorly represented by search snippets
Accessible only through metadata pages

The workflow should therefore support statuses such as:

source_found
full_text_available
abstract_only
metadata_only
requires_manual_access
insufficient_evidence

A result with limited access might be stored as:

{
    "title": "Example Research Paper",
    "url": "https://example.org/paper",
    "access_status": "abstract_only",
    "extraction_status": "partial",
    "manual_review_required": True,
}

This is more reliable than allowing the model to fill in missing information.

A Simplified End-to-End Workflow

The complete process can be represented with provider-agnostic pseudocode:

def build_research_matrix(question: str, search_client, reader_client):
    # 1. Structure the research question
    research_scope = parse_research_question(question)

    # 2. Create several query variations
    queries = generate_query_variations(research_scope)

    # 3. Search for public research sources
    search_results = []

    for query in queries:
        raw_results = search_client.search(query=query)

        for result in raw_results:
            search_results.append(
                normalize_search_result(result, query)
            )

    # 4. Remove likely duplicates
    unique_results = deduplicate(search_results)

    # 5. Rank and select promising sources
    selected_results = rank_and_select(
        results=unique_results,
        research_scope=research_scope,
    )

    # 6. Read and extract information
    research_matrix = []

    for result in selected_results:
        source_content = reader_client.read(url=result["url"])

        record = extract_paper_record(
            content=source_content,
            source_url=result["url"],
        )

        research_matrix.append(record)

    # 7. Mark records requiring human verification
    return add_verification_status(research_matrix)

A production version would also need:

API error handling
Rate-limit handling
Search-result caching
Maximum query budgets
PDF-processing limits
Source-domain filters
Prompt-injection defenses
DOI and author extraction
Better duplicate detection
Logging and tracing
Manual approval steps

What This Workflow Can and Cannot Do

This workflow can help with:

Starting from an incomplete description
Expanding academic terminology
Discovering public research sources
Reading selected pages and supported PDFs
Structuring methods and findings
Building a source-linked research matrix
Identifying records that require manual verification

It cannot guarantee:

Complete literature coverage
Access to every paywalled paper
Correct interpretation of every method
Accurate citation formatting
Identification of every duplicate
Elimination of hallucinated conclusions
Replacement of expert academic judgment

Search and extraction APIs can reduce manual work, but the researcher still needs to evaluate inclusion criteria, methodological quality, theoretical relevance, and the accuracy of the final synthesis.

Practical Checks Before Using the Results

Before using an AI-generated research matrix in a paper or report, I would check:

Source identity

Is this the original paper?
Is it a preprint, accepted manuscript, or final version?
Are the title, authors, and publication year correct?

Methodology

Was the method extracted from the full paper or only the abstract?
Are the sample and dataset accurately described?
Are causal claims supported by the research design?

Findings

Does the generated summary match the authors' wording?
Were limitations or boundary conditions omitted?
Are statistically insignificant findings being overstated?

Coverage

Were several query variations used?
Were references from key papers reviewed?
Were different languages and source categories considered?
Could terminology differences have excluded relevant papers?

Traceability

Does every important claim include a source URL?
Can the original passage be located?
Is the distinction between source content and model inference visible?

Final Takeaway

A useful AI research assistant needs more than a search box and a summarization prompt.

It needs a workflow that separates:

Question definition
Query expansion
Source discovery
Result filtering
Original-source reading
Structured extraction
Human verification

In my implementation, Cloudsway SmartSearch handles source discovery while Reader processes selected webpages and supported PDFs.

The more important design principle is provider-independent: every extracted claim should remain traceable to an original source, and the system should clearly identify information that still requires manual review.

Search can make literature discovery faster.

A trustworthy research workflow still depends on careful source selection, original-text verification, and human academic judgment.

How are you currently organizing source discovery and verification in your research workflows?

How to Add a Real-Time Search Layer to an Agent Graph

Marcus ma — Thu, 06 Aug 2026 03:53:48 +0000

How to Add a Real-Time Search Layer to an Agent Graph

Agent frameworks make it easier to build systems that can plan tasks, call tools, maintain state, and decide what to do next.

But a well-designed workflow can still produce a confidently structured wrong answer.

The graph may execute exactly as expected while relying on information that is outdated, incomplete, duplicated, or difficult to verify. This becomes especially noticeable when an agent handles recent news, product information, market research, academic research, or other knowledge-intensive tasks.

One way to address this is to treat real-time search as a shared evidence layer inside the agent graph.

In this article, I will break down a practical architecture for doing that.

Disclosure: This article uses Cloudsway SmartSearch as one implementation example. The overall architecture is provider-agnostic and can work with other search APIs that return structured results and source metadata.

The Difference Between an Agent Loop and an Agent Graph

A basic tool-using agent often follows a loop:

Reason
  ↓
Choose a tool
  ↓
Observe the result
  ↓
Decide what to do next

This pattern works well for relatively simple tasks.

As the number of tools, branches, and stopping conditions grows, however, the system prompt may begin carrying too much responsibility. It must describe the tools, maintain context, control branching, evaluate results, and decide when the task is complete.

An agent graph makes that control flow explicit.

Instead of asking one model to manage the entire process, the workflow can be divided into nodes such as:

User Request
  ↓
Router
  ↓
Query Planner
  ↓
Search
  ↓
Source Verification
  ↓
Answer Generation

Each node has a narrower responsibility.

The router decides whether external information is required. The planner creates focused search queries. The search node retrieves evidence. The verifier evaluates the quality of that evidence. The final node generates an answer from the verified sources.

If the evidence is insufficient, the graph can return to the query planner and run another search round.

This structure makes the workflow easier to test, observe, and improve.

Anthropic makes a useful distinction between workflows and agents: workflows follow predefined code paths, while agents have more control over their own processes and tool usage.

Many production systems combine both approaches. Code defines the available paths and safety boundaries, while the model makes decisions inside those boundaries.

Why Search Should Be a Shared Layer

A straightforward approach is to give every node access to its own search tool.

That works, but it can create several problems:

Different nodes may search for the same information repeatedly.
Search results may use inconsistent formats.
Citation metadata may be lost between nodes.
One node may use recent sources while another uses outdated pages.
Verification becomes difficult because evidence is scattered across the workflow.

A shared search layer provides a cleaner alternative.

Instead of passing unstructured snippets between nodes, the workflow can normalize each result into a common evidence object.

For example:

from typing import TypedDict


class Evidence(TypedDict):
    title: str
    url: str
    content: str
    published_at: str | None
    source: str | None
    relevance_score: float | None

The search node creates these evidence objects, and the rest of the graph consumes them.

A simplified agent state might look like this:

class AgentState(TypedDict):
    user_request: str
    search_required: bool
    queries: list[str]
    evidence: list[Evidence]
    verification_status: str
    answer: str

With this structure, research, analysis, verification, and answer-generation nodes all work with the same evidence format.

A Practical Search-Enabled Agent Graph

The architecture can be broken into five main stages.

1. Decide Whether Search Is Required

Not every task needs web access.

Requests such as rewriting text, changing formatting, translating content, or summarizing information already provided by the user can usually bypass the search branch.

Search becomes useful when the request depends on:

Recent information
External facts
Multiple independent sources
Product or market changes
Publication dates
Explicit citations
Information outside the model's internal knowledge

The router can produce a simple decision:

{
    "search_required": True,
    "reason": "The request depends on recent external information."
}

This reduces unnecessary API calls and keeps simple tasks fast.

2. Break the Request Into Focused Queries

Complex questions should rarely be sent to a search API as one broad query.

Consider this request:

Compare three AI search APIs for building a multilingual research agent.

A planner could decompose it into smaller queries:

- API A multilingual search documentation
- API B supported languages and freshness filters
- API C citation and source metadata support
- independent comparisons of AI search APIs

The planner can also create separate queries for:

Different entities
Different time periods
Supporting and opposing evidence
Product documentation
Independent third-party evaluations

Independent searches can run in parallel before their results are combined.

3. Normalize the Search Results

Search providers return different response formats.

One API may return snippets, another may return generated summaries, and another may return extracted page content. Downstream nodes should not need custom logic for every provider.

The search node should convert provider-specific responses into the shared evidence schema.

Conceptually:

def normalize_result(result: dict) -> Evidence:
    return {
        "title": result.get("title", ""),
        "url": result.get("url", ""),
        "content": result.get("summary") or result.get("content", ""),
        "published_at": result.get("published_at"),
        "source": result.get("source"),
        "relevance_score": result.get("score"),
    }

The exact field names will depend on the API you use.

The important part is that normalization happens once, at the boundary between the search provider and the agent graph.

4. Verify the Evidence

Retrieval and verification should be separate steps.

A search result can be relevant while still being outdated, duplicated, promotional, or unsupported by other sources.

A verification node can evaluate several dimensions:

Relevance:
Does the source address the actual question?

Freshness:
Is the publication date appropriate for the request?

Authority:
Is the source official, primary, or otherwise credible?

Diversity:
Do the results come from independent sources?

Agreement:
Do multiple sources support the same important claim?

The verifier should also be allowed to return:

insufficient_evidence

This is important.

A workflow that must produce an answer after every search round will eventually produce unsupported conclusions. A safer graph can refine the search queries, perform another retrieval round, or clearly state that reliable evidence was not found.

The feedback path could look like this:

Query Planner
      ↓
Search API
      ↓
Source Verification
      │
      └── Insufficient evidence ──→ Query Planner

5. Generate the Answer From Evidence and Metadata

The answer-generation node should receive both the extracted content and the original source metadata.

For example:

{
    "evidence": [
        {
            "title": "Example documentation page",
            "url": "https://example.com/docs",
            "content": "Relevant extracted information...",
            "published_at": "2026-07-30"
        }
    ]
}

The model can then connect claims to the URLs that support them.

Citations should come directly from the search results. They should not be reconstructed after the answer has already been written.

That reduces the risk of:

Invented URLs
Citations pointing to unrelated pages
Claims that are not supported by the linked source

Using Cloudsway SmartSearch as the Search Node

One implementation option is Cloudsway SmartSearch.

It is designed for AI-agent retrieval and can return original source URLs together with summaries and other structured result formats. It also supports multilingual search and freshness filters for recent results.

Inside an agent graph, it can fill the search-node role:

Query Planner
      ↓
Cloudsway SmartSearch
      ↓
Normalized Evidence Objects
      ↓
Source Verification

The rest of the workflow does not need to depend directly on the provider's response format. The search adapter converts the response into the graph's shared evidence schema.

This also makes the architecture easier to change later. The search provider can be replaced without rewriting the router, verifier, or answer-generation nodes.

When Search Snippets Are Not Enough

Search results often provide enough information to identify useful sources, but a short snippet may not contain the details required for deeper analysis.

This is especially common with:

Long documentation pages
JavaScript-rendered websites
Research papers
PDF reports
Tables and structured pages
Pages containing important information inside images

In that situation, the workflow can separate source discovery from content extraction.

For example:

SmartSearch
  ↓
Discover relevant URLs
  ↓
Reader
  ↓
Extract clean page content
  ↓
Verification and analysis

Cloudsway Reader can convert static or JavaScript-rendered pages into formats such as text, Markdown, or HTML. It also supports content from PDFs and images.

This creates a useful division of responsibility:

Search finds the most relevant sources.
Reader retrieves and structures the full content.
Verifier evaluates whether the evidence is reliable.
Generator produces the cited answer.

A Provider-Agnostic Workflow Example

The complete workflow can be represented as conceptual Python:

def run_agent(user_request: str, search_client):
    state = {
        "user_request": user_request,
        "search_required": False,
        "queries": [],
        "evidence": [],
        "verification_status": "not_started",
        "answer": "",
    }

    # 1. Route the request
    state["search_required"] = route_request(user_request)

    if not state["search_required"]:
        state["answer"] = generate_without_search(user_request)
        return state

    # 2. Plan focused queries
    state["queries"] = plan_queries(user_request)

    # 3. Search and normalize
    for query in state["queries"]:
        raw_results = search_client.search(query=query)

        for result in raw_results:
            state["evidence"].append(normalize_result(result))

    # 4. Verify the collected evidence
    state["verification_status"] = verify_evidence(
        request=user_request,
        evidence=state["evidence"],
    )

    # 5. Retry when the evidence is insufficient
    if state["verification_status"] == "insufficient_evidence":
        refined_queries = refine_queries(
            request=user_request,
            previous_queries=state["queries"],
            evidence=state["evidence"],
        )

        for query in refined_queries:
            raw_results = search_client.search(query=query)

            for result in raw_results:
                state["evidence"].append(normalize_result(result))

        state["verification_status"] = verify_evidence(
            request=user_request,
            evidence=state["evidence"],
        )

    # 6. Generate an answer grounded in the evidence
    state["answer"] = generate_cited_answer(
        request=user_request,
        evidence=state["evidence"],
        verification_status=state["verification_status"],
    )

    return state

This is intentionally simplified.

A production system would also need to handle:

Timeouts
Rate limits
Duplicate URLs
Query budgets
Search result caching
Unsafe or untrusted content
Source-domain restrictions
Maximum retry counts
Logging and tracing

The core architectural idea remains the same: search results should enter the graph as structured evidence rather than untracked text.

What I Would Check Before Shipping

Before deploying a search-enabled agent, I would test the following cases:

Search routing

Does the agent avoid search for simple rewriting tasks?
Does it activate search for recent or citation-heavy questions?
Can users explicitly request or disable search?

Query planning

Does the planner generate specific queries?
Does it cover different aspects of a complex question?
Does it avoid repeatedly searching for the same information?

Evidence quality

Are duplicate pages removed?
Are publication dates preserved?
Are original URLs available to downstream nodes?
Can the workflow distinguish official documentation from commentary?

Verification

Can the verifier reject weak evidence?
Can it request another search round?
Does it check important claims against independent sources?

Answer generation

Can each major claim be traced back to a source?
Are citations attached to the correct statements?
Does the answer acknowledge missing or conflicting evidence?

Final Takeaway

Agent frameworks solve orchestration problems. They help models plan tasks, call tools, pass state between nodes, and control execution paths.

Real-time search solves a different part of the system: access to current and verifiable evidence.

Treating search as a shared layer gives every node access to consistent source objects, reduces duplicated retrieval, and makes verification easier to implement.

The resulting graph looks less like a model with a search button and more like a research pipeline:

Request
  ↓
Route
  ↓
Plan
  ↓
Retrieve
  ↓
Verify
  ↓
Answer with citations

That pattern can be applied to research agents, enterprise copilots, market-analysis tools, technical-support systems, and other workflows where the quality of the answer depends on the quality of the evidence.

How are you handling retrieval and source verification in your agent workflows?