OpenAI Agents SDK

Give an agent built with the OpenAI Agents SDK for Python the SpecStream tools. It asks for live web data in plain words and gets structured records back, with the same saved requests, results, projects, and balance as your SpecStream workspace.

SpecStream for OpenAI Agents SDKAgent frameworks & builders

What you need

Python and the OpenAI Agents SDK.
A SpecStream account. New accounts get $10 of work on sign-up, no card.
A SpecStream API key with a spending limit.

1
1. Create an API key
In your SpecStream workspace, open Agents & API, choose API keys, then Create API key. Give it only the projects, operations, and spending limit the agent needs.
Keep it in an environment variable where the agent runs:
Terminal
export SPECSTREAM_API_KEY="YOUR_SPECSTREAM_API_KEY"

2. Connect from your process

MCPServerStreamableHttp connects to https://api.specstream.ai/mcp from your own process and sends the key as a header. Pass it to the agent in mcp_servers:

agent.py
import asyncio, os
from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp

async def main():
    params = {"url": "https://api.specstream.ai/mcp",
              "headers": {"Authorization": f"Bearer {os.environ['SPECSTREAM_API_KEY']}"}}
    async with MCPServerStreamableHttp(name="SpecStream", params=params, cache_tools_list=True) as server:
        agent = Agent(name="Researcher", instructions="Use the SpecStream tools.", mcp_servers=[server])
        print((await Runner.run(agent, "List my saved specs.")).final_output)

asyncio.run(main())

3. Ask for the data

Run the agent with a request in plain words, and name the details to bring back on each record. For example:

Request

Find clinical trials recruiting in Spain for type 2 diabetes, with the sponsor, phase, and registry ID.

4. Or let the OpenAI API call SpecStream

HostedMCPTool lets the OpenAI API call the server for you. Pass it in tools, not mcp_servers. The authorization field takes an access token, and the API does not store it, so include it on every request.

Keep require_approval on "always" so each call is reviewed before it runs.

hosted.py
import os
from agents import Agent, HostedMCPTool

tool = HostedMCPTool(tool_config={
    "type": "mcp",
    "server_label": "specstream",
    "server_url": "https://api.specstream.ai/mcp",
    "authorization": os.environ["SPECSTREAM_ACCESS_TOKEN"],
    "require_approval": "always",
})
agent = Agent(name="Researcher", tools=[tool])

What happens when you ask

The agent calls compile, and SpecStream reads the request back as editable parts. Show the person the agent works for anything marked ambiguous. quote_capacity_work prices the request, and the quote lasts 30 minutes.

authorize_capacity_work starts the work with the approved maximum in confirm_max_cents and a stable request key. A retry with the same key never buys anything twice. Rows arrive with the source URL and read time on every value, and get_find_decisions returns each condition's answer with its reason, value, and source.

To find saved work, call list_specs or list_projects. The agent guide covers every tool.

Spending limits

Reading or pricing a request never spends anything. Only an authorization does, and never more than the approved maximum. The key's own limits hold on top of that: total, per run, monthly, and the operations it allows. Approve the maximum in your own code, or ask the person the agent works for.

Cost

Reading a request and pricing it cost nothing. Each row that matches costs 5¢, 15¢ or $1, depending on how much the row needs, plus 5¢ for a person's email and 15¢ for a phone. A quote lasts 30 minutes, and a run that finds nothing costs nothing. How quotes and billing work

Remove

Take the server or the hosted tool out of the agent. To stop the key working everywhere, revoke it in Agents & API. Results already delivered stay in your workspace. Other ways to build with SpecStream are in agent frameworks. Questions go to [email protected].

SpecStream for OpenAI Agents SDK covers what it does in OpenAI Agents SDK on one page. Every other tool has its guide in Connect your tools. You see the most a request can cost before it starts, and the matches are paid from your balance. Billing has the details. For help, email [email protected].