> ## Documentation Index
> Fetch the complete documentation index at: https://trytilde.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAI Agents SDK

> Run an OpenAI Agents SDK agent on Tilde with the TypeScript or Python adapter.

The OpenAI Agents SDK adapter runs an OpenAI `Agent`, and its handoffs, on Tilde. It works with `@openai/agents` 0.18 in TypeScript, and `openai-agents` 0.22 in Python.

<Columns cols={2}>
  <Card title="TypeScript example" icon="github" href="https://github.com/trytilde/tilde/tree/main/sdk/ts/examples/openai-agents-example-agent">
    A complete OpenAI Agents SDK agent in TypeScript.
  </Card>

  <Card title="Python example" icon="github" href="https://github.com/trytilde/tilde/tree/main/sdk/py/examples/example-agent-openai-agents">
    A complete OpenAI Agents SDK agent in Python.
  </Card>
</Columns>

## Install

<CodeGroup>
  ```bash TypeScript theme={"system"}
  npm i @trytilde/sdk @trytilde/sdk-openai-agents-node @openai/agents openai
  ```

  ```bash Python theme={"system"}
  pip install trytilde trytilde-openai-agents openai-agents
  ```
</CodeGroup>

## How it works

On each invocation, the adapter returns a copy of your agent with the channel's tools, the agent's Tilde and bundled tools, and skills. It also returns run options that pass new user input to the model, and the abort signal. Your module-level agent is never changed.

<CodeGroup>
  ```typescript TypeScript theme={"system"}
  import { inference, type AgentContext } from "@trytilde/sdk";
  import {
    convertToOpenAIAgentsMessages,
    tildeOpenAIAgents,
  } from "@trytilde/sdk-openai-agents-node";
  import { Agent, OpenAIResponsesModel, run, setTracingDisabled } from "@openai/agents";
  import OpenAI from "openai";
  import { bundledTools } from "./bundled-tools.js";

  // The SDK's own tracing sends prompts and tool data to OpenAI.
  setTracingDisabled(true);

  const openai = new OpenAI({ ...inference("default") });

  export const agent = new Agent({
    name: "support-agent",
    instructions: "You are a support assistant. Reply with the channel tools.",
    model: new OpenAIResponsesModel(openai, "gpt-4o-mini"),
  });

  export async function respond(ctx: AgentContext) {
    const history = await ctx.message.history();
    const items = await convertToOpenAIAgentsMessages({
      messages: history.items,
      context: ctx,
    });
    const tilde = await tildeOpenAIAgents(ctx, agent, { bundled: bundledTools });
    await run(tilde.agent, items, { ...tilde.options, maxTurns: 8 });
  }
  ```

  ```python Python theme={"system"}
  import tilde
  from agents import Agent, OpenAIResponsesModel, Runner, set_tracing_disabled
  from openai import AsyncOpenAI
  from tilde_openai_agents import convert_to_openai_agents_messages, tilde_openai_agents

  from bundled_tools import TOOLS

  # The SDK's own tracing sends prompts and tool data to OpenAI.
  set_tracing_disabled(True)

  INFERENCE = tilde.inference("default")
  client = AsyncOpenAI(
      base_url=INFERENCE.base_url,
      api_key=INFERENCE.api_key,
      http_client=INFERENCE.async_client(),
  )

  agent = Agent(
      name="support-agent",
      instructions="You are a support assistant. Reply with the channel tools.",
      model=OpenAIResponsesModel(model="gpt-4o-mini", openai_client=client),
  )

  async def respond(ctx: tilde.AgentContext) -> None:
      history = await ctx.message.history()
      items = await convert_to_openai_agents_messages(history.items, context=ctx)
      run_agent, run_config = await tilde_openai_agents(ctx, agent, bundled=TOOLS)
      await Runner.run(run_agent, items, run_config=run_config, max_turns=8)
  ```
</CodeGroup>

## Feature compatibility

| Feature | Support | Notes |
| - | - | - |
| Inference gateway | Yes | |
| Framework trace spans | Partial | Turn off the SDK's own tracing. It exports prompts and tool data to OpenAI. Tilde records its own spans. |
| Tilde and channel tools | Yes | Tool names that contain `-` are rewritten with `_`. |
| Bundled tools | Yes | Function tools carry no metadata, so pass summaries to `defineTools` as options. |
| Prompt versioning | Yes | Registers `<name>/instructions` and `<name>/handoff_description`. Instructions written as a function become a dynamic prompt. |
| Native skills | Partial | An agent with a local shell tool loads skills natively. Otherwise, skills arrive as tools. |
| New input during a run | Yes | |

### Handoffs and agents as tools

| | TypeScript | Python |
| - | - | - |
| Handoff targets | Receive Tilde tools and skills, like the root agent. | Run as you defined them. Only the root agent receives Tilde tools. |
| Agents used through `asTool()` or `as_tool()` | Run without Tilde's run options. | Run without Tilde's run options. |

## Limitations

* **Hosted prompts.** A prompt referenced by an OpenAI prompt ID is versioned by OpenAI, not Tilde. Discovery warns.
* **Hosted tools.** OpenAI hosted tools, such as web search, are not published to Tilde, and their calls are not recorded.
* **Failed tool calls.** The SDK turns a tool error into a result for the model. Tilde records the call as completed.
* **Server-managed conversations in Python.** If you use `previous_response_id`, new user input during a run can reach the model twice.
* **CrewAI in the same environment.** The Python adapter needs a different major version of the `openai` package from CrewAI. Keep them in separate environments.
* **Item IDs.** Converted history items carry no IDs, because the Responses API rejects IDs it did not create.