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?