> For the complete documentation index, see [llms.txt](/llms.txt).
> A full single-fetch corpus is available at [llms-full.txt](/llms-full.txt).
---
title: OpenAI SDK
description: Run agents built with the raw OpenAI SDK or the OpenAI Agents SDK inside an AGNT5 worker, with traces captured automatically.
last_verified: 2026-08-26
---



You don't rewrite an OpenAI-based agent to run it on AGNT5 — wrap it in a plain `@function` (Python) or `fn()` (TypeScript) that calls the framework exactly as you already do, and return plain data. AGNT5 auto-attaches capture to both `openai` (the raw client) and `openai-agents` (the Agents SDK) when they're installed, so every LM call, agent span, and tool call shows up in Studio traces with no manual instrumentation.

---

## Wrapping pattern

A financial-research pipeline built on the OpenAI Agents SDK, wrapped as a single AGNT5 function:



**Python:**

```python
from agnt5 import FunctionContext, Worker, function
from financial_research_agent.manager import FinancialResearchManager

DEFAULT_QUERY = "Write a short analysis of Apple's long-term revenue drivers and key risks."


@function(name="financial_research_agent")
async def financial_research_agent(
    ctx: FunctionContext, query: str = DEFAULT_QUERY
) -> dict[str, object]:
    manager = FinancialResearchManager()
    report, verification = await manager.run(query)
    ctx.logger.info("Financial research completed")
    return {
        "query": query,
        "report": report.model_dump(mode="json"),
        "verification": verification.model_dump(mode="json"),
    }
```

`FinancialResearchManager` is ordinary OpenAI Agents SDK code — a `Runner`/`Agent` pipeline under the hood. Nothing about it needs to know it's running inside AGNT5.





**TypeScript:**

```typescript
import { fn, Worker } from '@agnt5/sdk';
import type { Context } from '@agnt5/sdk';
import { withTrace } from '@openai/agents';
import { FinancialResearchManager } from './manager.js';

const DEFAULT_QUERY =
  "Write a short analysis of Apple's long-term revenue drivers and key risks.";

export const financialResearchAgentFunction = fn(
  'financial_research_agent',
).run(async (_ctx: Context, input: { query?: string }) => {
  const query = input.query?.trim() || DEFAULT_QUERY;
  const result = await withTrace('Financial research workflow', async () => {
    const manager = new FinancialResearchManager();
    return manager.run(query);
  });
  return { query, ...result };
});
```

Wrapping the run in `withTrace(...)` from `@openai/agents` groups the whole pipeline into one trace — AGNT5's capture attaches to the Agents SDK's own tracing processor, so this is the same call you'd make with or without AGNT5.



Register the function on a `Worker` the same way as any other AGNT5 function — see [Functions](/docs/build/functions.md) and [Local development](/docs/cli/dev.md).

---

## What gets captured

| Library | What's patched | Journal events |
|---|---|---|
| `openai` | Chat completions, Responses API, and embeddings (sync + async, streaming included) | `lm.started`, `lm.completed`, `lm.failed` |
| `openai-agents` | Agent, generation/response, and function spans via the SDK's public tracing API (`add_trace_processor`) | `agent.*`, `lm.*`, `tool_call.*` |

Capture is observational only — it never alters a request or response, and a capture failure never fails your agent's call.

---

## Requirements

Capture activates the moment the library is importable — no separate AGNT5 flag or install extra is required. (`agnt5[openai]` / `agnt5[openai-agents]` just pin the version band below for your own dependency resolution.)

```bash
pip install openai openai-agents
```

```bash
npm install openai @openai/agents
```

| Library | Minimum | Max major (exclusive) |
|---|---|---|
| `openai` | 1.66.0 | 3 |
| `openai-agents` | 0.3.0 | 1 |

An installed version outside this band is left unpatched rather than risking a broken instrumentation hook.

---

## Disable it

| Environment variable | Effect |
|---|---|
| `AGNT5_CAPTURE=off` | Master kill switch — disables capture for every library |
| `AGNT5_CAPTURE_OPENAI=0` | Disables raw `openai` client capture only |
| `AGNT5_CAPTURE_OPENAI_AGENTS=0` | Disables OpenAI Agents SDK capture only |

---

## Related

- [Google ADK](/docs/integrations/third-party/google-adk.md): the same wrapping pattern and capture behavior for Google's Agent Development Kit.
- [AI providers](/docs/integrations/ai-providers.md): configure the `OPENAI_API_KEY` credential your agents and prompts call.
- [Functions](/docs/build/functions.md): how `@function` / `fn()` works.
- [Integrations overview](/docs/integrations/overview.md)