Skip to content

armgit / camel

Public Imported from GitHub
0

🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org

[feat] add XquikToolkit for read-only X/Twitter search (#3997) (#3998)

Burak Bayır158bb8c1fd3c
diff --git a/camel/toolkits/__init__.py b/camel/toolkits/__init__.py
index 76f768fe9..5beea9c77 100644
--- a/camel/toolkits/__init__.py
+++ b/camel/toolkits/__init__.py
@@ -46,6 +46,7 @@ from .wechat_official_toolkit import WeChatOfficialToolkit
from .dingtalk import DingtalkToolkit
from .lark_toolkit import LarkToolkit
from .twitter_toolkit import TwitterToolkit
+from .xquik_toolkit import XquikToolkit
from .open_api_toolkit import OpenAPIToolkit
from .retrieval_toolkit import RetrievalToolkit
from .notion_toolkit import NotionToolkit
@@ -128,6 +129,7 @@ __all__ = [
'LarkToolkit',
'ImageGenToolkit',
'TwitterToolkit',
+ 'XquikToolkit',
'WeatherToolkit',
'RetrievalToolkit',
'OpenAPIToolkit',
diff --git a/camel/toolkits/xquik_toolkit.py b/camel/toolkits/xquik_toolkit.py
new file mode 100644
index 000000000..6c236df23
--- /dev/null
+++ b/camel/toolkits/xquik_toolkit.py
@@ -0,0 +1,260 @@
+# ========= Copyright 2023-2026 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2026 @ CAMEL-AI.org. All Rights Reserved. =========
+import json
+import os
+import urllib.parse
+import urllib.request
+from typing import Any, Dict, List, Optional
+
+from camel.logger import get_logger
+from camel.toolkits import FunctionTool
+from camel.toolkits.base import BaseToolkit
+from camel.utils import MCPServer, api_keys_required
+
+logger = get_logger(__name__)
+
+_BASE = "https://xquik.com/api/v1"
+
+
+@MCPServer()
+class XquikToolkit(BaseToolkit):
+ r"""A toolkit for read-only X (Twitter) operations via the Xquik API.
+
+ Provides tweet search, tweet lookup, user profile lookup, and trending
+ topics. Requires only ``XQUIK_API_KEY`` (1 env var) and no OAuth setup.
+
+ For write operations (posting, deleting tweets), use
+ :class:`TwitterToolkit` instead.
+
+ References:
+ https://xquik.com
+
+ Notes:
+ To use this toolkit, set the ``XQUIK_API_KEY`` environment variable.
+ Get a key at https://xquik.com
+ """
+
+ @api_keys_required([(None, "XQUIK_API_KEY")])
+ def __init__(self, timeout: Optional[float] = None):
+ r"""Initialize the XquikToolkit with API credentials from env vars."""
+ super().__init__(timeout=timeout)
+ self.api_key = os.environ.get("XQUIK_API_KEY", "")
+
+ def _xquik_get(
+ self, path: str, params: Optional[Dict[str, Any]] = None
+ ) -> Dict[str, Any]:
+ r"""Make a GET request to the Xquik API.
+
+ Args:
+ path (str): API endpoint path.
+ params (Optional[Dict[str, Any]]): Query parameters.
+
+ Returns:
+ Dict[str, Any]: Parsed JSON response.
+
+ Raises:
+ RuntimeError: If the API request fails.
+ """
+ url = f"{_BASE}{path}"
+ if params:
+ qs = urllib.parse.urlencode(
+ {k: v for k, v in params.items() if v is not None}
+ )
+ url = f"{url}?{qs}"
+
+ req = urllib.request.Request(
+ url,
+ headers={
+ "X-API-Key": self.api_key,
+ "Accept": "application/json",
+ "User-Agent": "camel-ai/1.0",
+ },
+ )
+ with urllib.request.urlopen(req, timeout=15) as resp:
+ return json.loads(resp.read().decode("utf-8"))
+
+ def xquik_search_tweets(
+ self,
+ query: str,
+ max_results: int = 10,
+ sort_order: str = "Top",
+ ) -> str:
+ r"""Search for tweets on X (Twitter).
+
+ Supports X search operators: ``from:user``, ``#hashtag``,
+ ``"exact phrase"``, ``since:YYYY-MM-DD``, ``until:YYYY-MM-DD``,
+ ``-is:retweet``, ``-is:reply``, ``has:media``.
+
+ Args:
+ query (str): The search query.
+ max_results (int): Maximum number of tweets to return (1-200).
+ (default: :obj:`10`)
+ sort_order (str): Sort order, "Top" (engagement) or "Latest"
+ (chronological). (default: :obj:`"Top"`)
+
+ Returns:
+ str: A JSON-formatted string containing the search results with
+ tweet text, author info, engagement metrics, and URLs.
+ """
+ try:
+ max_results = max(1, min(max_results, 200))
+ data = self._xquik_get(
+ "/x/tweets/search",
+ {"q": query, "limit": max_results, "queryType": sort_order},
+ )
+ tweets = data.get("tweets", [])
+ results = []
+ for tweet in tweets:
+ author = tweet.get("author", {})
+ results.append(
+ {
+ "id": tweet.get("id", ""),
+ "text": tweet.get("text", ""),
+ "created_at": tweet.get("createdAt", ""),
+ "author": {
+ "username": author.get("username", ""),
+ "name": author.get("name", ""),
+ "verified": author.get("verified", False),
+ },
+ "metrics": {
+ "likes": tweet.get("likeCount", 0),
+ "retweets": tweet.get("retweetCount", 0),
+ "replies": tweet.get("replyCount", 0),
+ "quotes": tweet.get("quoteCount", 0),
+ "views": tweet.get("viewCount", 0),
+ "bookmarks": tweet.get("bookmarkCount", 0),
+ },
+ "url": (
+ "https://x.com/"
+ f"{author.get('username', 'unknown')}"
+ f"/status/{tweet.get('id', '')}"
+ ),
+ }
+ )
+ return json.dumps(
+ {"query": query, "count": len(results), "tweets": results},
+ indent=2,
+ )
+ except Exception as e:
+ logger.exception("Error searching tweets via Xquik")
+ return json.dumps({"error": str(e), "query": query})
+
+ def xquik_get_tweet(self, tweet_id: str) -> str:
+ r"""Retrieve a single tweet by ID with full engagement metrics.
+
+ Args:
+ tweet_id (str): The tweet ID to look up.
+
+ Returns:
+ str: A JSON-formatted string containing the tweet text, author
+ info, and engagement metrics.
+ """
+ try:
+ data = self._xquik_get(f"/x/tweets/{tweet_id}")
+ tweet = data.get("tweet")
+ if not isinstance(tweet, dict):
+ tweet = data
+ author = data.get("author")
+ if not isinstance(author, dict):
+ author = tweet.get("author", {})
+ result = {
+ "id": tweet.get("id", ""),
+ "text": tweet.get("text", ""),
+ "created_at": tweet.get("createdAt", ""),
+ "author": {
+ "username": author.get("username", ""),
+ "name": author.get("name", ""),
+ "verified": author.get("verified", False),
+ },
+ "metrics": {
+ "likes": tweet.get("likeCount", 0),
+ "retweets": tweet.get("retweetCount", 0),
+ "replies": tweet.get("replyCount", 0),
+ "quotes": tweet.get("quoteCount", 0),
+ "views": tweet.get("viewCount", 0),
+ "bookmarks": tweet.get("bookmarkCount", 0),
+ },
+ "url": (
+ f"https://x.com/{author.get('username', 'unknown')}"
+ f"/status/{tweet.get('id', '')}"
+ ),
+ }
+ return json.dumps(result, indent=2)
+ except Exception as e:
+ logger.exception("Error fetching tweet via Xquik")
+ return json.dumps({"error": str(e)})
+
+ def xquik_get_user_info(self, username: str) -> str:
+ r"""Retrieve information about a specific X (Twitter) user.
+
+ Args:
+ username (str): The username (without @) to look up.
+
+ Returns:
+ str: A JSON-formatted string with the user's profile information.
+ """
+ try:
+ data = self._xquik_get(f"/x/users/{username.lstrip('@')}")
+ result = {
+ "id": data.get("id", ""),
+ "name": data.get("name", ""),
+ "username": data.get("username", ""),
+ "description": data.get("description", ""),
+ "followers": data.get("followers", 0),
+ "following": data.get("following", 0),
+ "tweet_count": data.get("statusesCount", 0),
+ "verified": data.get("verified", False),
+ "url": f"https://x.com/{data.get('username', username)}",
+ }
+ return json.dumps(result, indent=2)
+ except Exception as e:
+ logger.exception("Error fetching user info via Xquik")
+ return json.dumps({"error": str(e)})
+
+ def xquik_get_trends(self, woeid: int = 1, count: int = 20) -> str:
+ r"""Get trending topics on X (Twitter).
+
+ Args:
+ woeid (int): WOEID for region. 1=Global, 23424977=US,
+ 23424975=UK. (default: :obj:`1`)
+ count (int): Number of trends to return (1-50).
+ (default: :obj:`20`)
+
+ Returns:
+ str: A JSON-formatted string with a list of trending topics.
+ """
+ try:
+ count = max(1, min(count, 50))
+ data = self._xquik_get(
+ "/x/trends", {"woeid": woeid, "count": count}
+ )
+ return json.dumps({"trends": data.get("trends", [])}, indent=2)
+ except Exception as e:
+ logger.exception("Error fetching trends via Xquik")
+ return json.dumps({"error": str(e)})
+
+ def get_tools(self) -> List[FunctionTool]:
+ r"""Returns a list of FunctionTool objects representing the
+ functions in the toolkit.
+
+ Returns:
+ List[FunctionTool]: A list of FunctionTool objects
+ representing the functions in the toolkit.
+ """
+ return [
+ FunctionTool(self.xquik_search_tweets),
+ FunctionTool(self.xquik_get_tweet),
+ FunctionTool(self.xquik_get_user_info),
+ FunctionTool(self.xquik_get_trends),
+ ]
diff --git a/examples/toolkits/xquik_toolkit.py b/examples/toolkits/xquik_toolkit.py
new file mode 100644
index 000000000..3021cb52e
--- /dev/null
+++ b/examples/toolkits/xquik_toolkit.py
@@ -0,0 +1,66 @@
+# ========= Copyright 2023-2026 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2026 @ CAMEL-AI.org. All Rights Reserved. =========
+
+import os
+
+from camel.agents import ChatAgent
+from camel.models import ModelFactory
+from camel.toolkits import XquikToolkit
+from camel.types import ModelPlatformType, ModelType
+
+
+def main() -> None:
+ r"""Run read-only X (Twitter) research with ChatAgent and XquikToolkit.
+
+ Set ``XQUIK_API_KEY`` and your model provider credentials before running
+ this example.
+ """
+ if not os.environ.get("XQUIK_API_KEY"):
+ raise RuntimeError("Set XQUIK_API_KEY before running this example.")
+
+ tools = XquikToolkit().get_tools()
+ model = ModelFactory.create(
+ model_platform=ModelPlatformType.DEFAULT,
+ model_type=ModelType.DEFAULT,
+ )
+
+ agent = ChatAgent(
+ system_message=(
+ "You are a social research assistant. Use Xquik tools for "
+ "read-only X/Twitter search, profile lookup, and trends. "
+ "Summarize results concisely and include source URLs when present."
+ ),
+ model=model,
+ tools=tools,
+ )
+ agent.reset()
+
+ user_messages = [
+ (
+ "Search X for recent posts about CAMEL-AI and multi-agent "
+ "frameworks. Return three concise findings."
+ ),
+ "Look up the X profile CamelAIOrg and summarize the public profile.",
+ "Get the top five global X trends and group them by topic.",
+ ]
+
+ for user_message in user_messages:
+ response = agent.step(user_message)
+ print(f"User: {user_message}")
+ print(f"Tool calls: {response.info.get('tool_calls', [])}")
+ print(f"Agent: {response.msg.content}\n")
+
+
+if __name__ == "__main__":
+ main()
diff --git a/test/toolkits/test_xquik_toolkit.py b/test/toolkits/test_xquik_toolkit.py
new file mode 100644
index 000000000..9d255ee36
--- /dev/null
+++ b/test/toolkits/test_xquik_toolkit.py
@@ -0,0 +1,288 @@
+# ========= Copyright 2023-2026 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2026 @ CAMEL-AI.org. All Rights Reserved. =========
+
+import json
+from typing import Any, Dict, List, Tuple
+from urllib.parse import parse_qs, urlparse
+
+import pytest
+
+from camel.toolkits import FunctionTool, XquikToolkit
+
+
+class FakeResponse:
+ def __init__(self, payload: Dict[str, Any]) -> None:
+ self.payload = payload
+
+ def __enter__(self) -> "FakeResponse":
+ return self
+
+ def __exit__(self, *args: Any) -> None:
+ return None
+
+ def read(self) -> bytes:
+ return json.dumps(self.payload).encode("utf-8")
+
+
[email protected](autouse=True)
+def set_xquik_api_key(monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setenv("XQUIK_API_KEY", "test-api-key")
+
+
+def test_xquik_get_builds_authorized_request(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ captured: Dict[str, Any] = {}
+
+ def fake_urlopen(request: Any, timeout: int) -> FakeResponse:
+ captured["url"] = request.full_url
+ captured["timeout"] = timeout
+ captured["headers"] = {
+ key.lower(): value for key, value in request.header_items()
+ }
+ return FakeResponse({"ok": True})
+
+ monkeypatch.setattr(
+ "camel.toolkits.xquik_toolkit.urllib.request.urlopen",
+ fake_urlopen,
+ )
+
+ result = XquikToolkit()._xquik_get(
+ "/x/tweets/search",
+ {"q": "camel ai", "limit": 10, "empty": None},
+ )
+
+ parsed_url = urlparse(captured["url"])
+ assert result == {"ok": True}
+ assert parsed_url.scheme == "https"
+ assert parsed_url.netloc == "xquik.com"
+ assert parsed_url.path == "/api/v1/x/tweets/search"
+ assert parse_qs(parsed_url.query) == {
+ "limit": ["10"],
+ "q": ["camel ai"],
+ }
+ assert captured["timeout"] == 15
+ assert captured["headers"]["x-api-key"] == "test-api-key"
+ assert captured["headers"]["accept"] == "application/json"
+ assert captured["headers"]["user-agent"] == "camel-ai/1.0"
+
+
+def test_xquik_search_tweets_formats_results(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ calls: List[Tuple[str, Dict[str, Any]]] = []
+ toolkit = XquikToolkit()
+
+ def fake_xquik_get(
+ path: str, params: Dict[str, Any] | None = None
+ ) -> Dict[str, Any]:
+ calls.append((path, params or {}))
+ return {
+ "tweets": [
+ {
+ "id": "123",
+ "text": "CAMEL adds a toolkit",
+ "createdAt": "2026-05-12T00:00:00Z",
+ "author": {
+ "username": "CamelAIOrg",
+ "name": "CAMEL-AI",
+ "verified": True,
+ },
+ "likeCount": 12,
+ "retweetCount": 3,
+ "replyCount": 2,
+ "quoteCount": 1,
+ "viewCount": 1000,
+ "bookmarkCount": 4,
+ }
+ ]
+ }
+
+ monkeypatch.setattr(toolkit, "_xquik_get", fake_xquik_get)
+
+ result = json.loads(
+ toolkit.xquik_search_tweets(
+ "from:CamelAIOrg -is:retweet",
+ max_results=500,
+ sort_order="Latest",
+ )
+ )
+
+ assert calls == [
+ (
+ "/x/tweets/search",
+ {
+ "limit": 200,
+ "q": "from:CamelAIOrg -is:retweet",
+ "queryType": "Latest",
+ },
+ )
+ ]
+ assert result == {
+ "count": 1,
+ "query": "from:CamelAIOrg -is:retweet",
+ "tweets": [
+ {
+ "author": {
+ "name": "CAMEL-AI",
+ "username": "CamelAIOrg",
+ "verified": True,
+ },
+ "created_at": "2026-05-12T00:00:00Z",
+ "id": "123",
+ "metrics": {
+ "bookmarks": 4,
+ "likes": 12,
+ "quotes": 1,
+ "replies": 2,
+ "retweets": 3,
+ "views": 1000,
+ },
+ "text": "CAMEL adds a toolkit",
+ "url": "https://x.com/CamelAIOrg/status/123",
+ }
+ ],
+ }
+
+ calls.clear()
+ toolkit.xquik_search_tweets("CAMEL-AI", max_results=1)
+
+ assert calls == [
+ (
+ "/x/tweets/search",
+ {"limit": 1, "q": "CAMEL-AI", "queryType": "Top"},
+ )
+ ]
+
+
+def test_xquik_get_tweet_formats_single_tweet(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ calls: List[Tuple[str, Dict[str, Any] | None]] = []
+ toolkit = XquikToolkit()
+
+ def fake_xquik_get(
+ path: str, params: Dict[str, Any] | None = None
+ ) -> Dict[str, Any]:
+ calls.append((path, params))
+ return {
+ "tweet": {
+ "id": "456",
+ "text": "A specific tweet",
+ "createdAt": "2026-05-12T01:00:00Z",
+ "likeCount": 5,
+ "retweetCount": 4,
+ "replyCount": 3,
+ "quoteCount": 2,
+ "viewCount": 100,
+ "bookmarkCount": 1,
+ },
+ "author": {"username": "CamelAIOrg", "name": "CAMEL-AI"},
+ }
+
+ monkeypatch.setattr(toolkit, "_xquik_get", fake_xquik_get)
+
+ result = json.loads(toolkit.xquik_get_tweet("456"))
+
+ assert calls == [("/x/tweets/456", None)]
+ assert result["id"] == "456"
+ assert result["author"]["username"] == "CamelAIOrg"
+ assert result["metrics"]["likes"] == 5
+ assert result["url"] == "https://x.com/CamelAIOrg/status/456"
+
+
+def test_xquik_get_user_info_strips_at_sign(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ calls: List[Tuple[str, Dict[str, Any] | None]] = []
+ toolkit = XquikToolkit()
+
+ def fake_xquik_get(
+ path: str, params: Dict[str, Any] | None = None
+ ) -> Dict[str, Any]:
+ calls.append((path, params))
+ return {
+ "description": "Multi-agent framework",
+ "followers": 100,
+ "following": 10,
+ "id": "789",
+ "name": "CAMEL-AI",
+ "statusesCount": 50,
+ "username": "CamelAIOrg",
+ "verified": True,
+ }
+
+ monkeypatch.setattr(toolkit, "_xquik_get", fake_xquik_get)
+
+ result = json.loads(toolkit.xquik_get_user_info("@CamelAIOrg"))
+
+ assert calls == [("/x/users/CamelAIOrg", None)]
+ assert result == {
+ "description": "Multi-agent framework",
+ "followers": 100,
+ "following": 10,
+ "id": "789",
+ "name": "CAMEL-AI",
+ "tweet_count": 50,
+ "url": "https://x.com/CamelAIOrg",
+ "username": "CamelAIOrg",
+ "verified": True,
+ }
+
+
+def test_xquik_get_trends_clamps_count(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ calls: List[Tuple[str, Dict[str, Any]]] = []
+ toolkit = XquikToolkit()
+
+ def fake_xquik_get(
+ path: str, params: Dict[str, Any] | None = None
+ ) -> Dict[str, Any]:
+ calls.append((path, params or {}))
+ return {"trends": [{"name": "CAMEL", "tweet_volume": 1234}]}
+
+ monkeypatch.setattr(toolkit, "_xquik_get", fake_xquik_get)
+
+ result = json.loads(toolkit.xquik_get_trends(woeid=23424977, count=99))
+
+ assert calls == [("/x/trends", {"count": 50, "woeid": 23424977})]
+ assert result == {"trends": [{"name": "CAMEL", "tweet_volume": 1234}]}
+
+ result = json.loads(toolkit.xquik_get_trends(woeid=1, count=-1))
+
+ assert calls[-1] == ("/x/trends", {"count": 1, "woeid": 1})
+ assert result == {"trends": [{"name": "CAMEL", "tweet_volume": 1234}]}
+
+
+def test_xquik_toolkit_get_tools() -> None:
+ tools = XquikToolkit().get_tools()
+
+ assert len(tools) == 4
+ assert all(isinstance(tool, FunctionTool) for tool in tools)
+ assert [tool.get_function_name() for tool in tools] == [
+ "xquik_search_tweets",
+ "xquik_get_tweet",
+ "xquik_get_user_info",
+ "xquik_get_trends",
+ ]
+
+
+def test_xquik_toolkit_requires_api_key(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ monkeypatch.delenv("XQUIK_API_KEY")
+
+ with pytest.raises(ValueError, match="XQUIK_API_KEY"):
+ XquikToolkit()