AI Agent / Web3·off-chain (any)
OpenAI Agents SDK
Official OpenAI TypeScript/Python SDK plus the Agents SDK for building tool-using LLM agents. General-purpose AI inference layer commonly wrapped by Web3 agent frameworks for reasoning and function-calling.
- 01LLM inference
- 02function calling / tools
- 03agent orchestration
- 04MCP server integration
- 05structured outputs with Zod
- pnpm add openai @openai/agents zod
| Variable | Scope | Description |
|---|---|---|
| OPENAI_API_KEY | Server | OpenAI API key from platform.openai.com — required for all model calls. |
Use the OpenAI Agents SDK to build tool-using agents. Define an agent with `import { Agent, tool } from '@openai/agents'; const swap = tool({ name: 'swap', parameters: z.object({...}), execute: async (args) => {...} }); const agent = new Agent({ name: 'TraderAgent', instructions: '...', tools: [swap], model: 'gpt-5' });` then `await run(agent, 'swap 10 USDC to ETH')`. For raw inference use `import OpenAI from 'openai'; const client = new OpenAI(); const res = await client.responses.create({ model: 'gpt-5', input: '...' });`. Hosted tools (web_search, file_search, code_interpreter) and MCP servers attach via the same `tools: [...]` array.
- ⚑API keys must never ship to the client — proxy all calls through a server route or signed edge function; key leakage is the #1 outage cause.
- ⚑Tool-calling models can hallucinate arguments — validate with the Zod schema you pass to `tool({ parameters })` and reject invalid calls inside `execute`.
- ⚑Streaming responses (`stream: true`) require Server-Sent Events handling; in Next.js use `Response` with the SDK's stream helper, not `res.write` from pages router.
- ⚑Cost scales with tokens — long agent loops with multiple tool calls can rack up $$$; cap with `maxTurns` and log per-run token usage.
- ⚑Network reliability: OpenAI APIs occasionally 429 or 503; wrap in retry-with-backoff and have a fallback model (Haiku/Llama via Bedrock) for production agents.
- ⚑Model deprecations happen quickly — pin `model: 'gpt-5'` strings rather than `gpt-5-2026-xx-xx` aliases that get retired.