feat(examples): add Baizhi web research workflow

[ct-jaryn]

What is the current behavior?

Existing MCP examples show how to connect an agent to tools. This example adds a complete public-web research question: search candidate sources, read the relevant pages, and extract fields for a cited comparison.

What is the new behavior?

Adds examples/with-baizhi-research, a one-shot VoltAgent CLI using Baizhi's hosted MCP service over Streamable HTTP. The example discovers tool names but exposes only websearch_search, web_scrape and web_extract, with explicit schemas, six shared tool-call attempts, cancellation, request/run deadlines and connection cleanup. Discovery stops once the three required tools are found; a missing-tool result and the ten-page limit have distinct safe errors. The CLI distinguishes cancellation and run timeout. API-key echoes are replaced in output; raw remote errors are not logged or returned to the model.

Baizhi is a paid external tool service, not an LLM provider. Users provide both Baizhi and OpenAI credentials. The README documents data flow, usage charges, public-source restrictions and the limits of these controls. No service backend, released framework package, model provider or registry listing is added.

Validation

• 26 offline tests using the actual MCP SDK protocol and synthetic in-memory/HTTP transports; one runs a real VoltAgent Agent with an AI SDK fake model through all three tool calls and checks the tool responses reach the model prompt.
• Tests pass on Node 20.6.0, 20.20.2 and 22.22.2. Node 20.6 is the minimum because the example uses --env-file. Example TypeScript build and test-source typecheck pass against published package dependencies.
• Biome check, README Prettier check, and an offline frozen-lockfile-only validation with pnpm 8.10.5 pass.
• Live tools/list confirmed the three names/input shapes. No paid tool invocation or live LLM answer is claimed by this validation.
• Full monorepo build/test and upstream CI were not run locally.

Notes for reviewers

Prepared with AI assistance as part of the Baizhi Agent Toolkit outreach effort. The official MCP SDK wrapper makes per-operation cancellation and the shared tool budget explicit without changing framework APIs. Tests need no credentials. This private example is ignored by .changeset/config.json (voltagent-example-*), so no released-package changeset is included.

Related scope proposal: #1419. The contribution guide recommends opening an issue first; this PR provides the concrete example for review. Maintainer scope acceptance is still pending.

PR Checklist

• Conventional commit title prepared
• Related scope issue linked (feat: public web research example with Baizhi MCP tools #1419); no maintainer feedback received yet
• Tests added
• Docs added
• Changeset applicability checked: ignored private example only

[changeset-bot]

⚠️ No Changeset found

Latest commit: f768371

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: e83c0e15-00b5-4332-9ca5-7091a71f05da

📥 Commits

Reviewing files that changed from the base of the PR and between 092cbdc and f768371.

📒 Files selected for processing (6)

• examples/with-baizhi-research/README.md
• examples/with-baizhi-research/package.json
• examples/with-baizhi-research/src/index.spec.ts
• examples/with-baizhi-research/src/index.ts
• examples/with-baizhi-research/src/session.spec.ts
• examples/with-baizhi-research/src/session.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• examples/with-baizhi-research/README.md

Included review availability: Your plan provides up to 10 included reviews per hour; 8 remain after this review.

---

📝 Walkthrough

Walkthrough

This PR adds a with-baizhi-research example. It connects a VoltAgent agent to Baizhi’s MCP service, exposes three validated tools, enforces call and time limits, redacts secrets, supports cancellation, and includes offline tests and setup documentation.

Changes

Baizhi research example

Layer / File(s)	Summary
Example package and setup examples/with-baizhi-research/.env.example, examples/with-baizhi-research/package.json, examples/with-baizhi-research/tsconfig*.json, examples/with-baizhi-research/vitest.config.ts, examples/with-baizhi-research/README.md	Adds package scripts, dependencies, TypeScript and Vitest configuration, environment variables, and documentation for setup, limits, data handling, and offline validation.
Research session and tool contract examples/with-baizhi-research/src/session.ts	Connects to Baizhi MCP, discovers the required tools, validates inputs, forwards fixed parameters, redacts secrets, enforces six calls and 30-second request timeouts, and handles cancellation and closure.
CLI research workflow examples/with-baizhi-research/src/index.ts, examples/with-baizhi-research/src/index.spec.ts	Adds a CLI that validates the question and API keys, runs openai/gpt-4o-mini, enforces a two-minute deadline, handles signals, reports distinct failure types, prints a redacted answer, and closes the session.
Offline session validation examples/with-baizhi-research/src/session.spec.ts	Tests the agent flow, tool mapping, discovery pagination, validation failures, redaction, call limits, cancellation, timeouts, idempotent closure, and authenticated HTTP transport options.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant CLI as src/index.ts
  participant Session as openResearchSession
  participant MCP as Baizhi MCP service
  participant Agent as VoltAgent Agent
  CLI->>Session: Open session with API key and AbortSignal
  Session->>MCP: Connect with Bearer authentication
  MCP-->>Session: Discover research tools
  CLI->>Agent: Generate answer with session tools
  Agent->>Session: Call research tool
  Session->>MCP: Forward validated request
  MCP-->>Session: Return redacted result
  Agent-->>CLI: Return research answer

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 5 functions across 5 files. (2 skipped: 2 …
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly and concisely describes the primary change: adding a Baizhi web research workflow example.
Description check	✅ Passed	The description covers the current and new behavior, validation, tests, documentation, issue linkage, changeset applicability, and reviewer notes. It provides sufficient detail for review.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cubic-dev-ai]

All reported issues were addressed across 10 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>