How to use an agent to find clinical trials for a research question

An agent can save hours when a researcher asks, “Which studies might matter for this treatment question?” The output should be a shortlist with reasons, not a page of vaguely related links. To demonstrate, consider: Which studies involving pembrolizumab and advanced non-small-cell lung cancer (NSCLC) are recruiting adults, and what populations and treatment arms do they study? This is a research-landscape question, not a determination that a particular person is eligible.

We use three providers from the market map: Valyu to search a clinical-trials dataset, Dimensions to query structured trial metadata, and Perplexity to search public registry pages. Each offers a different route to candidate studies; the ClinicalTrials.gov record remains the place to inspect current study details. Search for Agents is produced by Valyu. The library calls below follow documented TypeScript interfaces for Valyu and Perplexity and Dimensions' Python client; without subscriber credentials, we did not run the three provider queries or compare their retrieval quality. The named ClinicalTrials.gov record was inspected separately on 25 September 2026.

Install valyu-js and @perplexity-ai/perplexity_ai for the TypeScript examples with npm install valyu-js @perplexity-ai/perplexity_ai. The Dimensions example uses Dimcli (pip install dimcli), the Python client documented by its publisher. Set VALYU_API_KEY, DIMENSIONS_API_KEY, and PERPLEXITY_API_KEY in your environment; Dimensions also needs the API endpoint supplied by your institution. Keep these examples on the server side, away from browser bundles.

State the research question before searching

Give the agent five fields: condition (advanced NSCLC), intervention (pembrolizumab, including combinations), population (adults), status (recruiting), and geography (anywhere initially; United States if location matters). Ask it to return a study table with registry ID (NCT for ClinicalTrials.gov), phase, treatment arms, biomarker and prior-treatment criteria, overall status, location status, last update, and registry link. This keeps a broad match from becoming a misleading recommendation.

In particular, a study that mentions NSCLC somewhere in its description and pembrolizumab somewhere in its interventions may be relevant only to a subset of patients or arms. Let the agent search broadly, then narrow by reading each registry record.

1. Discover candidate registry records

Valyu's clinical-trials dataset can be selected explicitly using its TypeScript SDK:

import { Valyu } from "valyu-js";

const results = await new Valyu().search(
  "Recruiting clinical trials for adults with advanced non-small cell lung cancer involving pembrolizumab, including combination arms",
  {
    searchType: "proprietary",
    includedSources: ["valyu/valyu-clinical-trials"],
    maxNumResults: 10,
    responseLength: "medium",
  },
);
if (!results.success) throw new Error("Trial search did not complete");
for (const hit of results.results) {
  console.log(hit.title, hit.url, hit.content.slice(0, 500));
}

For each hit, have the agent record the NCT number and the registry URL, then expand synonyms if the first pass is thin: “NSCLC,” “non-small-cell lung cancer,” “Keytruda,” and a particular mutation. Check the response status and warnings for incomplete search results. Valyu documents this clinical-trials collection as subscription-only and says its trial data can lag by 24–48 hours. Search relevance is a discovery tool, not an assertion that the study is still recruiting or that all its cohorts use pembrolizumab.

2. Filter the trial landscape

Dimensions' clinical-trials source exposes fields such as overall_status, phase, conditions, interventions, study_eligibility_criteria, and linkout. With institutional API access, Dimcli handles authentication and runs a Dimensions Search Language (DSL) query. Set DIMENSIONS_ENDPOINT to your institution's full DSL v2 endpoint, such as https://app.dimensions.ai/api/dsl/v2:

import os
import dimcli

dimcli.login(
    key=os.environ["DIMENSIONS_API_KEY"],
    endpoint=os.environ["DIMENSIONS_ENDPOINT"],
)
data = dimcli.Dsl().query('''
search clinical_trials for "non-small cell lung cancer pembrolizumab"
return clinical_trials[id + title + linkout + phase + overall_status + interventions + study_eligibility_criteria] limit 20
''').data
if "errors" in data:
    raise RuntimeError("Dimensions trial query did not complete")
for study in data.get("clinical_trials", []):
    print(study.get("id"), study.get("linkout"), study.get("overall_status"))

Dimensions returns JSON. Compare the returned overall_status values with the recruiting criterion and page beyond the first 20 records if necessary. If you add a server-side where overall_status="..." filter, inspect the actual status strings first rather than assuming one capitalization or registry vocabulary works everywhere. Dimensions' id is its own trial identifier; follow linkout to the original registry and obtain that registry's study ID (an NCT number for ClinicalTrials.gov). Check whether a trial's phase, intervention arms, and eligibility meet the question. The indexed status may lag the registry; Dimensions' Analytics API requires an institutional subscription and is designed for analytical research, not as a general-purpose application backend.

3. Search public trial pages

Perplexity's Search SDK returns ranked web results and supports search_domain_filter. This lets an agent look for ClinicalTrials.gov study pages using a separate web index:

import Perplexity from "@perplexity-ai/perplexity_ai";

const results = await new Perplexity().search.create({
  query: "recruiting advanced non-small cell lung cancer pembrolizumab combination clinical trial adults",
  search_domain_filter: ["clinicaltrials.gov"],
  max_results: 10,
});
for (const page of results.results) {
  console.log(page.title, page.url, page.snippet);
}

Read the result URLs and excerpts to locate candidate NCT records, then open the originals. This is a useful second discovery route if a dataset query has missed a name or synonym, not a structured filter on registry status. A result's rank or snippet cannot establish that a trial is recruiting now; a web index may be incomplete or behind the registry. For publications associated with a shortlisted trial, search PubMed separately and keep those bibliographic records distinct from the trial registrations.

What the agent can learn from one real registry hit

A direct ClinicalTrials.gov study search for NSCLC, pembrolizumab, and overall recruiting status surfaced NCT05789082 in our 25 September 2026 check. Its registry API record describes a phase 1/2 study of divarasib, alone or in combinations, for previously untreated advanced or metastatic NSCLC with a KRAS G12C mutation. The overall study status was recruiting; its September 2026 update includes U.S. locations with different site-level statuses.

That result changes the research answer in three ways. First, it is not a phase 3 pembrolizumab trial. Second, pembrolizumab appears in combination cohorts A and B, while other cohorts use divarasib without it. Third, the biomarker, prior-treatment, and study-arm criteria matter: the title and overall recruiting label alone cannot tell a reader which cohort or site is relevant. The agent should place those details next to the NCT link, not merely output “recruiting pembrolizumab study.” Trial status, sites, and eligibility may change after this check.

Ask for a research shortlist, not an eligibility decision

Close the workflow with a prompt the reader can adapt:

From the trial records, build a table of studies recruiting adults with advanced NSCLC that include pembrolizumab in at least one arm. Give the registry ID (NCT where applicable), phase, combination partner, relevant arm, mutation and prior-treatment restrictions, overall status, location status, last update, and original registry link. Deduplicate results from the three searches by registry ID. Flag any uncertain match and list the questions a researcher should check with the study team.

For NCT05789082, the useful takeaway is not “eligible” or “effective.” It is: a recruiting phase 1/2 divarasib study includes pembrolizumab in some arms for a defined NSCLC population; inspect the mutation requirement, specific cohort, and current site before following up. That is knowledge a researcher can act on by opening the registry record and contacting the study team. The industry-search source check shows why a discovered study and an official decision support different claims.

Method note: Library syntax and access requirements were checked against the linked provider SDK documentation on 25 September 2026. The NCT05789082 example comes from the ClinicalTrials.gov v2 study-search response checked that day, not from a matched test of Valyu, Dimensions, and Perplexity. Recheck the live registry before using the record for current recruitment or location information.