OpenAI Integration Agent Skill

---
description: GPT API patterns, function calling, structured outputs with Zod, streaming, and token management.
homepage: https://yepapi.com/skills/openai-integration
metadata:
  tags: [openai, gpt, function-calling, ai]
---

# OpenAI Integration

## Rules

- Use the official `openai` package — `new OpenAI({ apiKey: process.env.OPENAI_API_KEY })`
- Streaming for chat: `stream: true` with async iterator — never block on full completion for user-facing responses
- Function calling: define functions with JSON Schema, handle `tool_calls` in response, return results as tool messages
- Structured outputs: use `response_format: { type: "json_schema", json_schema: {...} }` or Zod with AI SDK
- Token management: estimate tokens before sending (roughly 4 chars per token), trim context to stay within limits
- Model selection: `gpt-4o` for complex reasoning, `gpt-4o-mini` for simple tasks — make it configurable
- System prompt as first message — set tone, constraints, and output format
- Temperature: 0 for deterministic outputs (data extraction), 0.7-1.0 for creative tasks
- Rate limiting: respect `x-ratelimit-*` headers, implement exponential backoff on 429 errors

## Patterns

```ts
// Streaming completion
const stream = await openai.chat.completions.create({
  model: "gpt-4o",
  messages,
  stream: true,
});

for await (const chunk of stream) {
  const content = chunk.choices[0]?.delta?.content || "";
  process.stdout.write(content);
}
```

```ts
// Function calling
const response = await openai.chat.completions.create({
  model: "gpt-4o",
  messages,
  tools: [{ type: "function", function: { name: "get_weather", parameters: schema } }],
});
```

## Avoid

- Hardcoding API keys — always use environment variables
- Ignoring token limits — count tokens and trim messages proactively
- Using `gpt-4o` for trivial tasks — use `gpt-4o-mini` to save cost
- Missing error handling on API calls — handle 429, 500, timeout errors gracefully