feat(examples): add Xquik tools example

[kriptoburak]

PR Checklist

Please check if your PR fulfills the following requirements:

• The commit message follows our guidelines: https://voltagent.dev/docs/community/contributing/#commit-convention

Bugs / Features

• Related issue(s) linked
• Tests for the changes have been added
• Docs have been added / updated
• Changesets have been added https://voltagent.dev/docs/community/contributing/#creating-a-changeset

What is the current behavior?

VoltAgent has external API examples such as Tavily search, but no example showing how to expose public X/Twitter research tools from Xquik as typed VoltAgent tools.

What is the new behavior?

Adds examples/with-xquik-tools, a private example package with typed tools for Xquik public REST API reads:

• Search public X/Twitter posts
• Look up a public post by ID
• Look up a public user by username or ID
• Fetch a user's public posts
• Fetch public trends by WOEID

The example follows the existing example package structure, documents required environment variables, and adds the example to examples/README.md.

fixes: none

Notes for reviewers

No changeset is included because this only adds a private example package and does not change a published package.

Validation run:

• pnpm install --frozen-lockfile --ignore-scripts --filter voltagent-example-with-xquik-tools...
• pnpm exec biome check examples/with-xquik-tools examples/README.md pnpm-lock.yaml
• pnpm --filter voltagent-example-with-xquik-tools build
• git diff --check

Xquik endpoint paths, query parameters, and xquik-api-contract: 2026-04-29 were checked against the Xquik OpenAPI source before opening this PR.

---

Summary by cubic

Adds examples/with-xquik-tools, an example that exposes Xquik public X/Twitter endpoints as typed VoltAgent tools. Lets agents search posts, look up posts and users, fetch user posts, and get trends.

• New Features
  • New private example examples/with-xquik-tools with tools: search posts, get post, get user, get user posts, get trends.
  • Uses Xquik REST API with x-api-key and xquik-api-contract: 2026-04-29, plus a 20s request timeout.
  • Example agent xquik-research-agent using openai/gpt-4o-mini via @voltagent/server-hono.
  • Docs and .env.example included; added to examples/README.md. Requires OPENAI_API_KEY, XQUIK_API_KEY, optional XQUIK_BASE_URL. Added descriptive tool docstrings.

^{Written for commit 5ef4be9. Summary will update on new commits. Review in cubic}

Summary by CodeRabbit

• New Features

  • Added a new example showcasing an AI research agent for exploring public X/Twitter posts, users, and trends using Xquik tooling (search, lookup, user posts, trends).

• Documentation

  • Added comprehensive README with setup, run instructions, required environment variables (OpenAI and Xquik keys + base URL), and troubleshooting tips.

• Chores

  • Included example package configuration and an env example to simplify running the sample.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 5ef4be9

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: Pro

Run ID: f039cb60-09a8-48ec-8f6a-a80cab3cb3a2

📥 Commits

Reviewing files that changed from the base of the PR and between 2c72297 and 5ef4be9.

📒 Files selected for processing (1)

• examples/with-xquik-tools/src/tools.ts

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

• examples/with-xquik-tools/src/tools.ts

---

📝 Walkthrough

Walkthrough

This PR adds a new example: a VoltAgent research agent wired with Xquik REST API tools (search posts, get post, get user, get user posts, trends), agent/server setup, package/tsconfig, env template, and documentation; it also registers the example in the examples index.

Changes

Xquik Research Agent Example

Layer / File(s)	Summary
Xquik API Tools Implementation examples/with-xquik-tools/src/tools.ts	Defines constants and helpers for URL/identifier normalization and query building; implements callXquik (authenticated GET with timeout and structured results) and exports five tools: searchXPostsTool, getXPostTool, getXUserTool, getXUserPostsTool, getXTrendsTool, bundled as xquikTools.
VoltAgent Setup with Xquik Tools examples/with-xquik-tools/src/index.ts, examples/with-xquik-tools/package.json	Creates a Pino logger, defines xquikResearchAgent using openai/gpt-4o-mini and the Xquik tools, and instantiates VoltAgent with a Hono server. package.json declares dependencies/devDependencies and npm scripts for the example.
Example Documentation and Configuration examples/with-xquik-tools/README.md, examples/with-xquik-tools/.env.example, examples/with-xquik-tools/tsconfig.json, examples/README.md	Adds a comprehensive README describing tools, setup, env vars, and troubleshooting; .env.example provides OPENAI_API_KEY, XQUIK_API_KEY, and XQUIK_BASE_URL; tsconfig.json configures TypeScript build; updates main examples index with an “Xquik Tools” entry.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 I hopped through code and API streams,
Seeking tweets and user dreams,
With Xquik tools I sniff and find,
VoltAgent guides the searching mind. ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and concisely describes the main change: adding a new example for Xquik tools to the examples directory.
Description check	✅ Passed	The description comprehensively covers the change with current behavior, new behavior, documentation updates, validation steps, and notes explaining the lack of changeset for a private example package.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint skipped: no ESLint configuration detected in root package.json. To enable, add eslint to devDependencies.

---

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 and usage tips.}

[cubic-dev-ai]

No issues found across 8 files

_{Re-trigger cubic}

[omeraplak]

Thank you so much @kriptoburak !