How to Use the OpenAI Agents SDK with the Twitter (X) API

OpenAI ships three different things that people call "an OpenAI agent", and X data is attached differently to each. ChatGPT gets tools through connectors and custom GPT actions (connect ChatGPT to the Twitter (X) API). Codex gets tools through ~/.codex/config.toml (Codex + Twitter (X) API). The Agents SDK is a library: your Python process creates an Agent, hands it tools, and calls Runner.run. There is no settings screen; everything on this page is code.

The SDK's building blocks, verified against version 0.24.0 of openai-agents and its documentation: Agent(name, instructions, tools=[...], mcp_servers=[...], model, model_settings, output_type, tool_use_behavior); Runner.run(agent, input, max_turns=10) (async, returns a RunResult with final_output and to_input_list()), plus Runner.run_sync and Runner.run_streamed; @function_tool from agents to turn a Python function into a tool (the current docs also show it as @tool from agents.decorators; both names are exported); and agents.mcp.MCPServerStreamableHttp, MCPServerStdio and HostedMCPTool for MCP servers. Python 3.10 or newer is required.

There are three ways to give that agent X data, and they differ in where the tool code runs and what the model reads:

Route A, @function_tool. You write search_tweets, get_user_last_tweets and get_user_info as Python functions that call twitterapi.io REST endpoints with requests. The SDK builds the JSON schema from the type hints and the docstring. Your code decides what the model sees, so you can return a slim projection, enforce a request cap and count credits.

Route B, MCPServerStreamableHttp. Your process connects to the hosted MCP server at https://mcp.twitterapi.io/mcp (Streamable HTTP, key in an X-API-Key header), lists its 12 read tools, and passes the server in mcp_servers. No tool code to write, but each result arrives as the server's full JSON.

Route C, HostedMCPTool. The same MCP server, but configured as a Responses API tool: OpenAI's servers connect to mcp.twitterapi.io and call the tools; your process only sees the model's answer. One round trip less, and the key travels to OpenAI in the tool configuration.

The rest of this guide sets up all three and then measures them. The headline from the measurement: a raw 20-post page is about 33,709 tokens, and Route A's projection is about 3,010. Use Route B or C to prototype in an afternoon, and Route A for anything that pages, runs unattended or needs a bill you can predict.

You need two keys. OPENAI_API_KEY pays for the model, as in every Agents SDK example; the SDK reads it from the environment. TWITTERAPI_IO_API_KEY pays for the X data: sign in at twitterapi.io with Google and copy the key from the dashboard. Reads need no X developer account, no X app and no OAuth. Up to $1 in free credits for new accounts that pass the bot check; expires after 31 days; see /pricing.

Install the SDK and requests into a Python 3.10 or newer environment. On a machine whose default python3 is 3.9 (macOS with the Xcode tools, for example), pip install openai-agents quietly resolves to an old release that fails on import with a float | None type error; use python3.12 -m venv or uv so the current version installs.

Before any agent code, prove the data side works from your shell with one curl against /twitter/user/info. The response puts the profile in data with camelCase fields (followers, statusesCount, createdAt). If that call works, every failure after this point is agent configuration, not the API.

Keep the X data key out of your repository and out of the model's view: load it from the environment in the tool module, never pass it as a tool argument, and never echo it in tool output. Accounts that have never paid are limited to 0.2 requests per second (20 once paid); the code below waits and retries on HTTP 429 instead of failing.

A function tool is a Python function with type hints and a docstring. The SDK parses the signature with inspect and builds a Pydantic model for the arguments; it parses the docstring with griffe (Google, Sphinx and NumPy styles are supported) and uses the summary as the tool description and the Args: entries as parameter descriptions. That text is what the model reads when deciding whether and how to call the tool, so write it for the model: say what the tool returns, give an example query, and explain the cursor.

The three tools map onto three twitterapi.io endpoints. The shapes differ in one way that bites agent code: the search puts tweets, has_next_page and next_cursor at the top level, while the timeline nests the list under data.tweets and keeps the cursor fields at the top level. The profile endpoint puts the user in data. Tweets use likeCount, retweetCount, replyCount, viewCount, createdAt and author.userName; there is no public_metrics object as in the official X API.

Project before you return. The tool returns a string, and that string lands in the model's context verbatim. Our _slim function keeps nine fields per post (id, url, created_at, author, text, likes, reposts, replies, views) and swaps a repost's truncated "RT @..." text for the original's. That is the whole difference between the two dots on the chart below.

Pass a failure_error_function. When a tool raises, the SDK does not crash the run; it sends an error string to the model and lets it continue. The default string is a generic "An error occurred while running the tool. Please try again.", which we confirmed in a replay test hides both the API's user not found message and our own request-cap exception. The model then retries the same call. The one-line fix is @function_tool(failure_error_function=_tool_error) with a function that returns str(error) and tells the model not to retry with the same arguments. Note that twitterapi.io answers an unknown handle with HTTP 200 and status: "error", msg: "user not found", so the tool has to check status itself; raise_for_status() sees nothing.

Cap requests in code. The agent loop will happily page through a timeline until max_turns (default 10) stops it. X_MAX_REQUESTS (20 by default) raises before that, and because the error reaches the model, the agent reports the cap instead of looping. Strict JSON schema mode is on by default, so give optional arguments like cursor a default and the model will pass an empty string for the first page.

twitterapi.io runs an MCP server at https://mcp.twitterapi.io/mcp over Streamable HTTP; it authenticates with the same API key in an X-API-Key header and exposes 12 read tools: search_tweets, get_user_info, get_user_about, get_user_followers, get_user_followings, get_user_last_tweets, get_user_mentions, get_tweets_by_ids, get_tweet_replies, get_tweet_quotes, get_tweet_retweeters and get_trends. There is also an npm package, @twitterapi_io/mcp-server, for stdio clients (npx -y @twitterapi_io/mcp-server with TWITTERAPI_IO_API_KEY in the environment; the old @kaitoinfra/... name is deprecated). Client configs for other tools live on the Twitter (X) MCP server page.

Route B: MCPServerStreamableHttp. Construct it with params={"url": ..., "headers": {"X-API-Key": key}, "timeout": 30}, use it as an async context manager so it connects and disconnects cleanly, and pass it to Agent(mcp_servers=[server]). The SDK calls list_tools on every run unless cache_tools_list=True, so set it; the tool list is stable. Restrict the tools with tool_filter=create_static_tool_filter(allowed_tool_names=[...]): fewer tools means shorter tool descriptions in every model call and fewer wrong picks. Two settings matter in practice: client_session_timeout_seconds defaults to 5, which is a read timeout per tool call and is tight for a search that pages, so raise it to 60; and max_retry_attempts (default 0) retries a failed tool call with exponential backoff if you want the SDK to handle transient errors. require_approval can gate specific tools behind a human, which matters if you ever enable write tools.

If you prefer the stdio package, MCPServerStdio(params={"command": "npx", "args": ["-y", "@twitterapi_io/mcp-server"], "env": {"TWITTERAPI_IO_API_KEY": key}}) works the same way. Either way the model reads the server's JSON as returned, which is the raw page measured below; the SDK cannot slim it for you.

Route C: HostedMCPTool. This is the Responses API's mcp tool wrapped for the SDK: HostedMCPTool(tool_config={"type": "mcp", "server_label": "twitterapi", "server_url": "https://mcp.twitterapi.io/mcp", "headers": {"X-API-Key": key}, "allowed_tools": [...], "require_approval": "never"}) goes in tools=[...], not mcp_servers. OpenAI's documentation describes headers as optional HTTP headers sent to the MCP server for authentication, allowed_tools as a filter, and require_approval as "always", "never" or a per-tool mapping. The tool calls happen on OpenAI's servers: the API fetches the tool list and calls the tools, and your process never touches mcp.twitterapi.io. That removes a network hop from your infrastructure and means the X data key is part of the request you send to OpenAI; use a dedicated key you can rotate from the dashboard. OpenAI's guide also says, in its own words, that it is very important to trust any remote MCP server you connect, because a malicious server can exfiltrate anything that enters the model's context.

Which MCP route? Route B when you run your own process anyway and want the tool traffic in your logs; Route C when you want the smallest amount of code and are fine with OpenAI's servers holding the connection. Both give the model raw pages, and both charge the same 15 credits per tweet returned on the twitterapi.io side.

We made the calls an agent would make and measured what came back. 8 developer-tool organization accounts (@OpenAIDevs, @OpenAI, @vercel, @github, @Docker, @CloudflareDev, @huggingface, @llama_index), 10 pages of /twitter/user/last_tweets each, and 15 pages of /twitter/tweet/advanced_search for the query "openai agents sdk" with queryType=Latest. Tokens are tiktoken o200k_base counts of the JSON exactly as the API returns it (compact) and of the same page after the _slim projection.

Every page was full. All 95 pages held exactly 20 posts, and has_next_page was true on the last page of every account and of the search. A tool that assumes shorter pages near the end, or that stops when a page is short, is guessing; stop on has_next_page false, a missing cursor or an empty list, or on your own cap. One account we tried first, @LangChainAI, returned status: "success" with an empty tweets list and has_next_page: false on page 1; that request was still billed at the 15-credit minimum, and we replaced the account. An agent needs to say "no posts came back", not "the account was quiet".

A raw page is about 33,709 tokens. The median timeline page was 111,472 characters of compact JSON, 33,709 tokens, and 48,796 tokens pretty-printed with a two-space indent, which is how many MCP servers serialize results. Per post that is about 1,366 tokens, of which the embedded author profile object alone is about 378 (30% of the characters), repeated on every post of the same account. The search page was larger, 36,907 tokens, because posts about the Agents SDK are long: the median search post had 742 characters of text and 74% were over 280 characters, against 240 and 36% on the organization timelines.

The projection is about 3,010 tokens. Slimmed to id, text, createdAt, likeCount and author.userName (plus url and three more counts in the shipped code), the median timeline page was 3,010 tokens, 91% less, and the search page 9,202, 75% less (the text is most of what is left). Per post: 111 tokens on timelines and 254 in the search. In a 128k context that is 3 raw timeline pages or 42 slim ones; 3 raw search pages or 13 slim ones; 2 pretty-printed pages. A "summarize this account's last 200 posts" request is 10 pages, about 337,090 raw tokens, which no single context holds, and about 30,100 slim tokens, which fits with room for the answer.

Medians per account over 10 pages of 20 posts; tokens are tiktoken o200k_base. The spread is content: @CloudflareDev's pages carry more cards and media, @llama_index's posts are longer, so its slim pages are the largest. The character/4 approximation most people use lands about 17% under the real count for this JSON (27,868 vs 33,709 for the median raw page); the ratio between raw and slim is the same either way.

What this means for the route choice. Through Routes B and C the raw page is what the model reads, every time. Through Route A the model reads your projection. For a chat feature that answers one question per run, either works. For anything that pages, summarizes, or runs on a schedule, Route A is the difference between a run that fits and a run that compacts, and it also shrinks the model bill, since input tokens are billed by OpenAI.

A projection is only safe if the fields it reads are there. We checked all 30 top-level tweet fields of the recorded response shape, plus author.userName, across the 1,600 timeline posts and the 300 search posts. Every key was present on every post; what varies is whether the value is null or empty.

Three consequences for the tools. First, the slim projection uses only 100% fields, so it never raises. Second, createdAt is Www Mmm DD HH:MM:SS +0000 YYYY, not ISO 8601; the tool passes it through as a string and the model reads it fine, but code that sorts or filters must parse it with %a %b %d %H:%M:%S %z %Y. Third, the two endpoints see different posts: the timeline included 5.8% reposts and 12.2% quotes and, with the default includeReplies, no replies to other accounts; the search returned no reposts but 11.3% replies and 17.7% quotes, and 78.7% of its posts were in English (9.3% Japanese, 7.7% Chinese), which is why the example query adds lang:en.

What each call costs. twitterapi.io bills per item returned: 15 credits per tweet (minimum 15 per request) and 18 credits per profile, with $1 = 100,000 credits. The model side is billed by OpenAI on tokens, which is where the projection pays twice.

Per 1,000 posts that is $0.15 on twitterapi.io against $5 at the official X API pay-per-use rate of $0.005 per post read, about 33x less, and the official route also needs an X developer account with a saved card and an OAuth flow before the first call. Plans with higher rate limits and bonus credits are on the pricing page. Note the asymmetry: the 1,900 posts cost about $0.29 in X data, but at the timeline medians a model that read them all would take in about 2,595,400 raw tokens or about 210,900 slim ones; for most agents the model bill, not the data bill, is the one to watch.

Post text is untrusted input. Everything the tools return was written by someone else, and a post can contain "ignore previous instructions and ...". The shipped INSTRUCTIONS tell the model to treat post text as data, never follow instructions inside a post, never open or recommend links from posts, and quote text only inside quotation marks. The tools help by returning JSON, so post text sits inside a quoted string with an author and a URL around it rather than as free text. For stronger control the SDK offers input_guardrails and output_guardrails on the Agent, and require_approval on MCP servers.

Bound the loop twice. Runner.run(..., max_turns=8) caps the agent loop (the SDK default is 10 and raises MaxTurnsExceeded); X_MAX_REQUESTS caps the data calls inside the tools. The instructions ask for at most 3 tool calls per question. With all three in place, a confused model costs you at most a few cents of X data and a predictable number of model calls. The script prints a usage line on stderr (# 3 API requests, 900 credits (about $0.0090 in X data)) so you can see it.

Keep writes out of the agent. The MCP server and the tools on this page are read-only. twitterapi.io does offer write endpoints: one /twitter/user_login_v2 login ($0.10, with a proxy you supply) returns login_cookies, and each post, like, retweet or follow is then $0.002, billed per HTTP 200 call. Those calls act as that X account, which X can rate-limit, lock or suspend if it posts too fast; keep a human pace and expect to log in again when the session expires. An injected instruction that reaches a write tool can post as you, so if you ever add one, put it behind needs_approval on the function tool or require_approval on the MCP server and have a person confirm each action.

ImportError or a float | None type error on import agents. Your interpreter is older than 3.10 and pip installed an old release. Create the environment with Python 3.10 or newer and reinstall.

The model says "An error occurred while running the tool" and retries. You are on the default failure_error_function. Pass your own so the API's msg (for example user not found) and your cap message reach the model.

user not found for a real account. The API answers HTTP 200 with status: "error"; your tool must check status. Also try the handle without the @, which the tools strip, and remember that some accounts return an empty list with status: "success", as @LangChainAI did in our sample.

MCP tool calls time out. client_session_timeout_seconds defaults to 5 seconds. Raise it to 60 on MCPServerStreamableHttp, and set "timeout": 30 in params for the HTTP connection itself.

The model calls the wrong MCP tool. Twelve tools is a lot of choice. Use tool_filter=create_static_tool_filter(allowed_tool_names=[...]) (Route B) or allowed_tools (Route C) to expose the three you need.

HTTP 429. Accounts that have never paid are limited to 0.2 requests per second (20 once paid). The tools wait and retry; for MCP routes, ask for one call at a time or upgrade.

The context fills up or the run compacts. You are reading raw pages, about 33,700 tokens each. Move the tools to Route A and return the projection, or ask for narrower results (since:, min_faves:, lang:en, one page at a time).

Totals look wrong. A repost's likeCount is the original post's count, and its text is cut short. The projection swaps in the original's text; exclude reposts before summing engagement.

Question: when an Agents SDK agent calls a Twitter (X) data tool backed by twitterapi.io, what does the call return and cost: posts per page, characters and tokens of raw JSON versus a slim projection, which fields are populated how often, and credits per call.

Accounts and query: 8 developer-tool organization accounts (@OpenAIDevs, @OpenAI, @vercel, @github, @Docker, @CloudflareDev, @huggingface and @llama_index), 10 pages of /twitter/user/last_tweets each with the default includeReplies; plus 15 pages of /twitter/tweet/advanced_search for "openai agents sdk" with queryType=Latest. @LangChainAI was tried first and returned an empty list with status: "success"; it is reported above and excluded from the measurements. 96 requests in total through a rate-limited, read-only client; 1,900 posts. Collected in 2026.

Measurements: tokens are tiktoken o200k_base counts of each page as returned (compact JSON), pretty-printed with a two-space indent, and after the slim projection (id, text, createdAt, likeCount, author.userName); characters/4 is reported alongside in the results file. Field coverage counts a field as set when it is neither null nor an empty string, list or object. Credits follow the published rate of 15 per tweet returned with a 15-credit minimum and 18 per profile; the whole collection cost 28,515 credits.

The code on this page was run end to end against the recorded responses: the three function tools were invoked through the SDK's own tool-call path (FunctionTool.on_invoke_tool with a ToolContext) with requests.get replaced by a replay, covering two-page pagination with next_cursor, the empty account, the user not found error, the request cap and the credit counter; both the function-tool agent and the MCP-server agent were constructed. We did not run a live model session for this guide, so the model's choices and the OpenAI bill are not measured here. SDK facts were checked against openai-agents 0.24.0 installed locally and its documentation.

What the sample cannot show: 8 organization accounts and one developer topic are not all of X. Organization timelines carry more links, media and cards than personal accounts, and posts about an SDK are longer than average, so token counts for other topics will differ; the ratio between raw and slim pages depends mostly on the author object and the entity blocks, which every post carries. Replies to other accounts were excluded from the timelines by the default parameter. Token counts are for one tokenizer; other models count differently, though the ~90% reduction from projecting is a property of the JSON.

Aggregates only. The accounts named on this page are organizations; the topic search's raw pages were kept out of the published study because its authors are individuals, and the study's row-level sample carries no ids, text, handles or URLs for them. The analysis script, results, chart script, agent script, replay test and gzip-compressed raw pages for the organization accounts are kept with the study.