GPT Architecture Helper

Your agent for designing and building applications that integrate with OpenAI's GPT APIs — covering prompt engineering, API integration, token management, and AI-powered feature design.

When to Use This Agent

Choose GPT Architecture Helper when:

• Integrating OpenAI GPT APIs into your application
• Designing prompt templates and prompt engineering strategies
• Implementing chat completions, function calling, or streaming responses
• Managing tokens, rate limits, and cost optimization for GPT APIs
• Building AI-powered features (chatbots, content generation, code analysis)

Consider alternatives when:

• You need Claude/Anthropic API integration — use the Claude developer platform skill
• You need general architecture without AI focus — use an architect agent
• You need ML model training — use a machine learning agent

Quick Start

Copy
# .claude/agents/gpt-architect.yml
name: GPT Architecture Helper
model: claude-sonnet
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
description: GPT API integration architect for prompt engineering, API design, token management, and AI feature development

Example invocation:

claude "Design the architecture for a customer support chatbot that uses GPT-4 with function calling to look up order status, process returns, and escalate to human agents"

Core Concepts

GPT Integration Architecture

┌─────────────────────────────────────────┐
│              Application                 │
│  ┌────────────────────────────────────┐  │
│  │         Prompt Templates           │  │
│  │  System │ Few-shot │ Dynamic       │  │
│  ├────────────────────────────────────┤  │
│  │         API Client Layer           │  │
│  │  Rate Limiting │ Retry │ Fallback  │  │
│  ├────────────────────────────────────┤  │
│  │       Response Processing          │  │
│  │  Parsing │ Validation │ Caching    │  │
│  ├────────────────────────────────────┤  │
│  │       Token Management             │  │
│  │  Counting │ Truncation │ Cost      │  │
│  └────────────────────────────────────┘  │
└─────────────────────────────────────────┘

API Integration Patterns

Pattern	Use Case	Implementation
Chat Completions	Conversational AI	Messages array with system/user/assistant roles
Function Calling	Tool use, data lookup	Define functions, handle tool_calls responses
Streaming	Real-time output	SSE stream, process chunks incrementally
Embeddings	Semantic search, RAG	Generate vectors, store in vector database
Batch	Bulk processing	Async batch API for large workloads

Configuration

Parameter	Description	Default
model	GPT model (gpt-4, gpt-4-turbo, gpt-3.5-turbo)	gpt-4-turbo
max_tokens	Maximum response tokens	4096
temperature	Response randomness (0-2)	0.7
rate_limit_strategy	Rate limiting approach (queue, throttle, circuit-breaker)	queue
fallback_model	Backup model if primary fails	gpt-3.5-turbo

Best Practices

1. Use structured system prompts with clear role definitions. Define the AI's persona, capabilities, limitations, and output format in the system message. "You are a customer support agent. You can look up orders and process returns. You cannot modify billing information. Always respond in a friendly, professional tone."

2. Implement token counting before API calls. Use tiktoken to count tokens in your prompt before sending. If the conversation exceeds the context window, truncate older messages or summarize the conversation. Surprise token overflows cause API errors and wasted costs.

3. Add retry logic with exponential backoff for rate limits. OpenAI APIs return 429 (rate limit) and 500 (server error) responses. Implement retry with exponential backoff (1s, 2s, 4s, 8s) and a maximum retry count. Don't retry 400-series errors (except 429) — those indicate client issues.

4. Cache responses for deterministic prompts. When the same input always produces the same useful output (documentation lookups, code formatting), cache the response. Set temperature to 0 for deterministic output and use the prompt hash as the cache key.

5. Validate and sanitize both inputs and outputs. User inputs may contain prompt injection attempts. Model outputs may contain hallucinated data or unsafe content. Validate inputs before including them in prompts, and validate outputs before displaying them to users or executing them as code.

Common Issues

Model hallucinates function parameters or API responses. GPT may generate function calls with invalid parameters or fabricate data. Always validate function call arguments against your schema, and verify that any data the model claims to have "found" actually exists in your systems.

Token costs escalate unexpectedly in production. Long conversation histories consume tokens on every request (the full history is re-sent each time). Implement conversation summarization after N turns, truncate older messages, or use a sliding window to keep costs predictable.

Streaming responses are hard to parse for structured data. When streaming, you receive partial JSON or text chunks. For structured output (JSON mode), buffer the complete response before parsing. For plain text, process chunks as they arrive but handle partial sentences at chunk boundaries.