Use SocialCrawl with Google ADK
Give a Google ADK agent social media data, with the price shown before it spends.
Google's Agent Development Kit turns plain Python functions into agent tools, and it can also attach the hosted SocialCrawl MCP server as a toolset. SocialCrawl publishes no ADK package, and either route needs none.
Setup
Install ADK and requests, then set both keys. Create the SocialCrawl key in the dashboard under API Keys; it looks like sc_your_key_here. The Gemini key goes in GOOGLE_API_KEY.
pip install google-adk requests
export SOCIALCRAWL_API_KEY=sc_your_key_here
export GOOGLE_API_KEY=your_gemini_keyConnect
ADK reads an agent from a folder that holds __init__.py with from . import agent, and agent.py with a root_agent. Plain functions in tools are wrapped for you, and the docstring becomes the tool description. The functions take params as a query string such as handle=nasa.
import os
import requests
BASE = "https://www.socialcrawl.dev"
HEADERS = {"x-api-key": os.environ["SOCIALCRAWL_API_KEY"]}
def estimate_cost(endpoint: str, params: str) -> dict:
"""Quote the credits a SocialCrawl call will hold. Free. Call it before call_endpoint.
Args:
endpoint: The endpoint as platform/resource, for example tiktok/profile.
params: The call's query string, for example handle=nasa.
"""
r = requests.get(
f"{BASE}/v1/utility/estimate?id={endpoint}&{params}", headers=HEADERS, timeout=30
)
body = r.json()
return body.get("data", body)
def call_endpoint(platform: str, resource: str, params: str) -> dict:
"""Run one SocialCrawl call. Paid, so quote it with estimate_cost first.
Args:
platform: For example tiktok.
resource: For example profile or profile/videos.
params: The call's query string, for example handle=nasa.
"""
r = requests.get(
f"{BASE}/v1/{platform}/{resource}?{params}", headers=HEADERS, timeout=60
)
body = r.json()
if body.get("success"):
return body["data"]
err = body.get("error", {})
return {"error": err.get("type"), "message": err.get("message"), "status": r.status_code}
from google.adk import Agent
root_agent = Agent(
name="socialcrawl_agent",
model="gemini-2.5-flash",
instruction=(
"Read public social media data with SocialCrawl. Call estimate_cost and report the hold "
"before any call_endpoint. If a call returns INSUFFICIENT_CREDITS, tell the user and stop."
),
tools=[estimate_cost, call_endpoint],
)Read a profile and its posts
Run the agent from the folder that holds socialcrawl_agent, and ask for the price first. The estimate is free, and its hold is the most the call can take.
adk run socialcrawl_agent
# [user]: Quote tiktok/profile for handle=nasa, then read it and its latest videos.Keep spend in check
Call estimate_cost before any paid call and show the answer to the person who owns the key. The instruction above makes the agent quote first, and max_credits stops a list walk where you set it. A 402 means the account is out of credits. Tell the user it is an offer to top up and stop, because a retry cannot succeed. See Errors and Credits.
Use the MCP toolset
The hosted server at https://mcp.socialcrawl.dev/mcp takes your key as a bearer header and brings its own estimate tool, so there are no functions to write. Swap the toolset in for the two functions.
import os
from google.adk import Agent
from google.adk.tools.mcp_tool import McpToolset, StreamableHTTPConnectionParams
root_agent = Agent(
name="socialcrawl_agent",
model="gemini-2.5-flash",
instruction="Use socialcrawl_estimate and report the cost before any paid call.",
tools=[
McpToolset(
connection_params=StreamableHTTPConnectionParams(
url="https://mcp.socialcrawl.dev/mcp",
headers={"Authorization": f"Bearer {os.environ['SOCIALCRAWL_API_KEY']}"},
)
)
],
)