Skip to content

Open-source AI coworkers that each get a computer of their own: a browser, files and tools, with every action decided before it happens and recorded after. Bring any AG-UI agent.

Add Parallel search and extraction to OpenBot (#701)

Rowan Aldean45d8c9449e9b
diff --git a/README.md b/README.md
index 0a391dd4..3d611fab 100644
--- a/README.md
+++ b/README.md
@@ -393,6 +393,7 @@ Use `bash scripts/start.sh` for the whole stack and `bash scripts/stop.sh` to ta
- [docs/coworkers.md](docs/coworkers.md)
- [docs/deployment.md](docs/deployment.md)
- [docs/releasing.md](docs/releasing.md)
+- [docs/parallel-research.md](docs/parallel-research.md): public-web search and extraction through Parallel
## Contributing
diff --git a/docs/parallel-research.md b/docs/parallel-research.md
new file mode 100644
index 00000000..b948719e
--- /dev/null
+++ b/docs/parallel-research.md
@@ -0,0 +1,19 @@
+# Public-web research with Parallel
+
+Parallel provides public-web search and extraction for OpenBot. When both its `web_search` and `web_fetch` tools are granted to a Bot, the built-in Bot guidance describes them to it for public-web research, alongside whatever other tools it holds. The shipped Research Desk example also includes a public-web research skill. This configuration is conditional on ordinary authorization: no existing Bot receives new access automatically.
+
+## Enable research
+
+1. As an administrator, open Plugins and add **Parallel Search** from the catalogue. This pins `https://search.parallel.ai/mcp` and discovers its tools. No API key is needed for anonymous light use.
+2. Grant **web_search** and **web_fetch** to the Bots that should research the public web. For the shipped fintech package, select **Research Desk**. Its `research-public-web` skill already declares these tools; the declaration alone grants no access.
+3. Ask the Bot to research a topic. It should search, read selected sources, and cite their URLs. Run `/research-public-web` to explicitly select the example skill if your deployment has many tools.
+
+For production or higher limits, instead add **Parallel Search (API key)**, with your Parallel API key stored through the existing deployment credential flow. Grant its two tools and remove the anonymous grants. Both use the official endpoint; the authenticated entry sends the key as a Bearer token. If both are granted, the guidance selects the authenticated connector. Keys remain in the server-side credential vault.
+
+## Choice and controls
+
+Administrators can revoke either tool, remove the connector, or grant another provider. Users can explicitly request a different authorized provider. Existing tool selection, action policies, audit records, vendor error handling, and background-run authorization are unchanged. Every call goes through `PluginStore.callTool`; no raw MCP server is added to the agent configuration.
+
+The provider receives model-selected objectives, search queries, requested public URLs and a conversation session identifier. These arguments can contain information from the user's request: avoid sending private context that is not needed for public research. Full conversations are not automatically forwarded. Free anonymous access has provider-managed limits; failures remain visible and are not silently retried through another provider. Source URLs and excerpts use the existing tool-result rendering; this change adds no custom source-card UI.
+
+See [Parallel's official Search MCP documentation](https://docs.parallel.ai/integrations/mcp/search-mcp) for the two tools, free access, API-key authentication and limits.
diff --git a/examples/fintech/agents/research-desk.yaml b/examples/fintech/agents/research-desk.yaml
index cfbba516..ed1f7da4 100644
--- a/examples/fintech/agents/research-desk.yaml
+++ b/examples/fintech/agents/research-desk.yaml
@@ -14,6 +14,8 @@ role_description: >-
avatar_seed: research-desk
type: built-in
system_prompt: >-
+ Use the Parallel search and extraction tools for public-web research when granted,
+ unless the user chooses another authorized provider. Do not bypass missing or revoked grants.
Finding first, in one sentence somebody could act on. Then the evidence, each line naming the
document or page it came from. Then what you looked for and did not find, and the questions still
open. Never let a summary of a source outrank the source.
@@ -21,3 +23,4 @@ skills:
- find-a-document
- find-a-notion-page
- check-a-claim
+ - research-public-web
diff --git a/examples/fintech/skills.yaml b/examples/fintech/skills.yaml
index ce5ff531..62f5aa3d 100644
--- a/examples/fintech/skills.yaml
+++ b/examples/fintech/skills.yaml
@@ -20,6 +20,24 @@
# Refs are `<serverId>/<toolName>`, the same form a grant is written in. `google-drive` and `notion`
# are catalogue connectors; a server an administrator adds by URL uses the id it was given.
skills:
+ - slug: research-public-web
+ title: Research the public web
+ summary: Search current public sources with Parallel and write a cited brief.
+ instructions: >-
+ Use Parallel to discover relevant public sources and read
+ selected pages before answering. Use the authenticated connector when it is granted;
+ otherwise use the anonymous connector when granted. Honor an explicit user choice of another
+ authorized provider. Keep search objectives specific and queries concise. Use one session_id
+ per conversation across related search and fetch calls. Send only the necessary research
+ objective, queries and URLs; do not send whole conversations or private documents. Cite the
+ source URLs and state missing evidence or provider errors. A missing grant requires an
+ administrator; never work around a denial.
+ tools:
+ - parallel/web_search
+ - parallel/web_fetch
+ - parallel-authenticated/web_search
+ - parallel-authenticated/web_fetch
+
- slug: find-a-document
title: Find a document
summary: Search the connected document sources for a file and read what it says.
diff --git a/server/src/plugins/catalogue.ts b/server/src/plugins/catalogue.ts
index afd26582..759a0bc1 100644
--- a/server/src/plugins/catalogue.ts
+++ b/server/src/plugins/catalogue.ts
@@ -160,6 +160,31 @@ export type CatalogueEntry = {
* the other end of it.
*/
export const CATALOGUE: readonly CatalogueEntry[] = Object.freeze([
+ {
+ key: "parallel",
+ title: "Parallel Search",
+ vendor: "Parallel",
+ summary:
+ "Public-web search and source extraction. Free anonymous access for light use.",
+ host: "https://search.parallel.ai",
+ path: "/mcp",
+ auth: { kind: "none" },
+ writeTools: Object.freeze([]),
+ docsUrl: "https://docs.parallel.ai/integrations/mcp/search-mcp",
+ },
+ {
+ key: "parallel-authenticated",
+ title: "Parallel Search (API key)",
+ vendor: "Parallel",
+ summary:
+ "Public-web search and extraction using this deployment's Parallel API key.",
+ host: "https://search.parallel.ai",
+ path: "/mcp",
+ auth: { kind: "deployment-bearer" },
+ writeTools: Object.freeze([]),
+ docsUrl: "https://docs.parallel.ai/integrations/mcp/search-mcp",
+ },
+
{
key: "google-drive",
title: "Google Drive",
diff --git a/server/src/plugins/tools.ts b/server/src/plugins/tools.ts
index e6e5c09b..19300b76 100644
--- a/server/src/plugins/tools.ts
+++ b/server/src/plugins/tools.ts
@@ -133,6 +133,20 @@ export function grantedToolGuidance(
(system) => !held.includes(system),
);
+ const researchConnector = ["parallel-authenticated", "parallel"].find(
+ (server) =>
+ ["web_search", "web_fetch"].every((name) =>
+ tools.some((tool) => tool.ref === `${server}/${name}`),
+ ),
+ );
+ const researchTools = researchConnector
+ ? tools.filter(
+ (tool) =>
+ tool.ref === `${researchConnector}/web_search` ||
+ tool.ref === `${researchConnector}/web_fetch`,
+ )
+ : [];
+
return [
...(tools.length > 0
? [
@@ -154,6 +168,13 @@ export function grantedToolGuidance(
"access, and the thing that is missing is yours, not theirs.",
]
: []),
+ ...(researchConnector
+ ? [
+ `Parallel provides public-web search and extraction: ${researchTools.map((tool) => tool.name).join(" and ")} discover sources and read selected pages.`,
+ "Parallel searches the public web; it does not connect a person's private account. Send only the research objective, necessary search queries and requested URLs, not a full transcript or private documents. Generate one session_id for the conversation and reuse it on related search/fetch calls. Omit model_name unless the exact configured model identifier is known.",
+ "Cite source URLs and distinguish excerpts from full-page reads. Report provider errors or missing sources; do not invent evidence or quietly bypass a denial. Interactive browser work still uses the authorized computer tools when needed.",
+ ]
+ : []),
/*
* The vendors this deployment connects to and this Bot does not hold.
*
diff --git a/server/tests/parallel-research.test.ts b/server/tests/parallel-research.test.ts
new file mode 100644
index 00000000..55888850
--- /dev/null
+++ b/server/tests/parallel-research.test.ts
@@ -0,0 +1,97 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { parse } from "yaml";
+import { z } from "zod";
+import {
+ catalogueEntry,
+ classifyTool,
+ resolveServerUrl,
+ serverCredentialKind,
+} from "../src/plugins/catalogue";
+import { type GrantedTool, grantedToolGuidance } from "../src/plugins/tools";
+
+const tool = (server: string, name: string): GrantedTool => ({
+ name: `mcp__${server}__${name}`,
+ ref: `${server}/${name}`,
+ description: "Public web",
+ parameters: z.object({}),
+ execute: async () => "unused",
+});
+const pair = (server = "parallel") => [
+ tool(server, "web_search"),
+ tool(server, "web_fetch"),
+];
+describe("Parallel public-web research", () => {
+ test("pins anonymous and authenticated configurations to the official endpoint", () => {
+ for (const key of ["parallel", "parallel-authenticated"]) {
+ const resolved = resolveServerUrl(key, "https://attacker.example");
+ expect(resolved?.url).toBe("https://search.parallel.ai/mcp");
+ expect(classifyTool(resolved!.entry, "web_search", true)).toBe("read");
+ expect(classifyTool(resolved!.entry, "web_fetch", true)).toBe("read");
+ expect(classifyTool(resolved!.entry, "not_advertised", false)).toBe(
+ "write",
+ );
+ expect(classifyTool(resolved!.entry, "web_search", true, "write")).toBe(
+ "write",
+ );
+ }
+ expect(catalogueEntry("parallel")?.auth.kind).toBe("none");
+ expect(serverCredentialKind(catalogueEntry("parallel")!)).toBeNull();
+ expect(
+ serverCredentialKind(catalogueEntry("parallel-authenticated")!),
+ ).toBe("mcp");
+ });
+ test("describes Parallel only while both research tools are actually offered", () => {
+ expect(grantedToolGuidance(pair())).toContain(
+ "Parallel provides public-web search and extraction",
+ );
+ // Described, not preferred: a Bot holding another search tool is not told to pass it over.
+ expect(grantedToolGuidance(pair())).not.toContain("by default");
+ expect(grantedToolGuidance([tool("parallel", "web_search")])).not.toContain(
+ "Parallel provides public-web search and extraction",
+ );
+ expect(grantedToolGuidance([], ["parallel"])).not.toContain(
+ "Parallel provides public-web search and extraction",
+ );
+ expect(grantedToolGuidance([])).toBe("");
+ });
+ test("uses deployment-authenticated research when both connectors are authorized", () => {
+ const guidance = grantedToolGuidance([
+ ...pair(),
+ ...pair("parallel-authenticated"),
+ ]);
+ expect(guidance).toContain(
+ "mcp__parallel-authenticated__web_search and mcp__parallel-authenticated__web_fetch discover sources",
+ );
+ expect(guidance).toContain(
+ "it does not connect a person's private account",
+ );
+ });
+ test("ships a Research Desk declaration referencing catalogue tools without granting access", () => {
+ const skills = parse(
+ readFileSync(
+ new URL("../../examples/fintech/skills.yaml", import.meta.url),
+ "utf8",
+ ),
+ ).skills;
+ const skill = skills.find(
+ (item: { slug: string }) => item.slug === "research-public-web",
+ );
+ expect(skill.tools).toEqual([
+ "parallel/web_search",
+ "parallel/web_fetch",
+ "parallel-authenticated/web_search",
+ "parallel-authenticated/web_fetch",
+ ]);
+ const desk = parse(
+ readFileSync(
+ new URL(
+ "../../examples/fintech/agents/research-desk.yaml",
+ import.meta.url,
+ ),
+ "utf8",
+ ),
+ );
+ expect(desk.skills).toContain("research-public-web");
+ });
+});