toolcue Join the waitlist

OpenAI Agents SDK: enable only the tools each turn needs

The Agents SDK asks each function tool's is_enabled before every model call. Toolcue fills that in: select the turn's tools once before Runner.run, keep them in your run context, and every model call of the run sees only those.

Verified on 2026-11-02 with openai-agents 0.24.0, with 6 end-to-end tests. Toolcue is in early access: join the waitlist.

Install#

bash
pip install "toolcue[openai-agents]"       # toolcue + openai-agents
export TOOLCUE_URL=...  TOOLCUE_TOKEN=...  TOOLCUE_ADMIN_TOKEN=...

Use it#

python
from dataclasses import dataclass
from agents import Agent, RunConfig, Runner
from toolcue.openai_agents import ToolcueTurn, find_tools_tool, gate_tools

@dataclass
class MyContext:
    toolcue: ToolcueTurn

agent = Agent(name="billing", instructions="You are Acme's billing assistant.",
              tools=gate_tools(TOOLS) + [find_tools_tool("acme-billing")])

turn = ToolcueTurn.select("acme-billing", user_text, history=items, user={"roles": session.roles})  # once per turn
result = await Runner.run(agent, items + [{"role": "user", "content": user_text}], context=MyContext(toolcue=turn),
                          run_config=RunConfig(tool_not_found_behavior="return_error_to_model"))
items = result.to_input_list()                        # the history for the next turn

What happens#

  • ToolcueTurn.select sends the user's message and the earlier items (messages, function calls and their outputs) to Toolcue. If Toolcue fails, the turn allows every tool.
  • gate_tools returns copies of your function tools whose is_enabled reads the turn from the run context. Tools outside your Toolcue catalog stay enabled; hosted tools aren't gated.
  • find_tools searches the whole catalog and enables what it finds for the rest of the run.
  • With tool_not_found_behavior="return_error_to_model", a model that names a disabled tool gets an error back instead of the run failing, and the tool doesn't run.

Don't change agent.tools per request: agents are shared between concurrent runs. Keeping the selection in the run context is what the SDK recommends.