GPT

GPT function calling and outputs

GPT Integration Patterns

Practical guide for using AIWG with OpenAI's GPT and Codex models. Covers function calling, structured output, the Codex CLI, and how AIWG's model mapping translates Claude shorthand into OpenAI identifiers.

When to Use This Guide

Use this guide if you are:

Running AIWG with `--provider codex` or `--provider openai`
Working in the OpenAI Codex CLI terminal environment
Building custom integrations against the OpenAI-compatible API endpoint
Troubleshooting model mapping or deployment issues on the Codex provider

Quick Start

# Deploy AIWG to the Codex provider
aiwg use sdlc --provider codex

# Deploy with specific model overrides
aiwg use sdlc --provider codex \
  --reasoning-model gpt-5.3-codex \
  --coding-model codex-mini-latest \
  --efficiency-model gpt-5-codex-mini

# Preview deployment without writing files
aiwg use sdlc --provider codex --dry-run

# Deploy only commands to ~/.codex/prompts/
aiwg use sdlc --provider codex --commands-only

Model Reference

AIWG's Codex provider maps the three standard tiers to OpenAI model identifiers in `tools/agents/providers/codex.mjs`.

AIWG Tier	OpenAI Model	Pricing	Best For
`opus` (reasoning)	gpt-5.3-codex	Premium	Complex analysis, architecture
`sonnet` (coding)	codex-mini-latest	$1.50/$6 per 1M tokens	Code gen, debugging, CLI default
`haiku` (efficiency)	gpt-5-codex-mini	4x more usage quota	Quick tasks, summaries

Model Mapping Logic

When AIWG deploys agents to Codex, it replaces the `model:` field in each agent's frontmatter:

// From tools/agents/providers/codex.mjs
const gptModels = {
  'opus':   'gpt-5.3-codex',
  'sonnet': 'codex-mini-latest',
  'haiku':  'gpt-5-codex-mini'
};

An agent defined with `model: opus` in source becomes `model: gpt-5.3-codex` when deployed to `.codex/agents/`.

Switching Models in Codex CLI

# Mid-session model switch
/model gpt-5.3-codex

# Set default in config.toml
# ~/.codex/config.toml
[model]
default = "codex-mini-latest"

Deployment Paths

Codex uses a split deployment model that differs from other AIWG providers:

Artifact	Location	Scope
Agents	`.codex/agents/`	Project-local
Rules	`.codex/rules/`	Project-local
Commands	`~/.codex/prompts/`	User-level (all projects)
Skills	`~/.codex/skills/`	User-level (all projects)

Commands and skills deploy to the home directory so they are available across all projects without re-deploying. Agents and rules are project-specific.

# Verify deployment locations after install
ls .codex/agents/
ls ~/.codex/prompts/
ls ~/.codex/skills/

Function Calling vs. Claude Tool Use

The OpenAI function calling API and Claude's tool use API differ in structure. AIWG abstracts most of this, but it matters when writing custom integrations.

OpenAI Function Calling Structure

{
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "read_file",
        "description": "Read the contents of a file at the given path",
        "parameters": {
          "type": "object",
          "properties": {
            "path": {
              "type": "string",
              "description": "Absolute path to the file"
            }
          },
          "required": ["path"]
        }
      }
    }
  ],
  "tool_choice": "auto"
}

Key Differences from Claude Tool Use

Aspect	OpenAI	Claude
Schema format	JSON Schema in `function.parameters`	JSON Schema in `input_schema`
Tool call result	`role: "tool"` message	`role: "user"` with `tool_result` block
Forcing tool use	`"tool_choice": {"type": "function", "function": {"name": "..."}}`	`"tool_choice": {"type": "tool", "name": "..."}`
Multiple tools	Parallel supported	Parallel supported
Tool name format	snake_case recommended	snake_case recommended

Codex CLI Built-in Tools

The Codex CLI provides these tools automatically, similar to Claude Code:

Tool	Description
`shell`	Execute shell commands
`read_file`	Read file contents
`write_file`	Write file contents
`list_dir`	List directory contents
`search_files`	Search file contents

Design AIWG agent prompts for Codex to use these tool names when giving explicit tool instructions.

Structured Output and JSON Mode

GPT models support two mechanisms for structured output. Use these to ensure AIWG agents return parseable results.

JSON Mode

Ensures the model returns valid JSON. Requires the word "JSON" in the system or user prompt.

response = client.chat.completions.create(
    model="codex-mini-latest",
    response_format={"type": "json_object"},
    messages=[
        {
            "role": "system",
            "content": "You are an AIWG agent. Return your analysis as JSON."
        },
        {
            "role": "user",
            "content": f"Analyze this code and return a JSON report:\
\
{code}"
        }
    ]
)

Structured Output (Preferred)

Guarantees schema adherence via constrained decoding. More reliable than JSON mode for complex schemas.

from pydantic import BaseModel
from typing import List

class Finding(BaseModel):
    severity: str
    location: str
    description: str
    remediation: str

class SecurityReport(BaseModel):
    findings: List[Finding]
    risk_score: int
    summary: str

response = client.beta.chat.completions.parse(
    model="gpt-5.3-codex",
    messages=[...],
    response_format=SecurityReport
)

report = response.choices[0].message.parsed

When to Use Each

Method	Use When
JSON mode	Simple output, flexible schema
Structured output	Complex schema, downstream parsing required
Neither	Free-form text output (docs, explanations)

System Message Best Practices

OpenAI's `system` role message is the primary place for persistent instructions. Unlike Claude, where system prompts have strong behavioral weight, GPT models sometimes underweight long system messages. Compensate with these patterns.

Keep System Messages Focused

# Less effective: long, multi-topic system message
You are a helpful assistant that can do many things including reviewing
code, writing documentation, answering questions, helping with
architecture, [... 500 more words ...]

# More effective: precise, single-role definition
You are an AIWG Code Reviewer. You review code diffs for logic errors,
security issues, and style violations. You output structured reports
using the format specified in the user message.

Repeat Critical Instructions

For important constraints, reinforce in both the system and user messages:

messages = [
    {
        "role": "system",
        "content": "You are an AIWG agent. Never include file paths outside the project root."
    },
    {
        "role": "user",
        "content": "Review these files. Important: only reference paths within /project/. Files: ..."
    }
]

Use Numbered Steps for Procedures

GPT models follow numbered step sequences reliably:

System: You are an AIWG Test Engineer.

When given a specification, follow these steps:
1. Identify all acceptance criteria
2. For each criterion, write at least one test case
3. Identify edge cases not covered by the criteria
4. Write tests for the top 3 edge cases
5. Output tests in the format specified below

Token Optimization

Prompt Caching

`codex-mini-latest` supports prompt caching with a 75% discount on cached tokens. To maximize cache hits:

Keep system messages identical across requests
Place variable content (user input, artifacts) at the end of the prompt
Use consistent agent definitions — do not modify system prompts between calls

# Cache-friendly pattern: stable system + variable user
messages = [
    {"role": "system", "content": STABLE_SYSTEM_PROMPT},  # Cached after first call
    {"role": "user", "content": f"Review this:\
\
{variable_content}"}  # Variable
]

Token Budget by Model

Model	Input Cost	Recommended Max Input
gpt-5.3-codex	Premium	50K tokens (reserve budget for complex tasks)
codex-mini-latest	$1.50/1M	100K tokens (cost-effective for large inputs)
gpt-5-codex-mini	Budget	100K tokens (high volume tasks)

Reducing Repetition

For batch operations, extract common context to the system message:

# Inefficient: repeat context in every user message
for file in files:
    messages = [
        {"role": "system", "content": "You review Python code."},
        {"role": "user", "content": f"Project context: {large_context}\
\
Review: {file}"}
    ]

# Efficient: context in system message, cached
SYSTEM = f"You review Python code.\
\
Project context:\
{large_context}"
for file in files:
    messages = [
        {"role": "system", "content": SYSTEM},  # Cached
        {"role": "user", "content": f"Review: {file}"}
    ]

OpenAI-Compatible API Configuration

AIWG can target any OpenAI-compatible endpoint by setting the base URL. This is the entry point for local models and third-party providers using the same API format.

{
  "openai": {
    "reasoning": {
      "model": "gpt-5.3-codex",
      "description": "Most capable reasoning"
    },
    "coding": {
      "model": "codex-mini-latest",
      "description": "Balanced coding tasks"
    },
    "efficiency": {
      "model": "gpt-5-codex-mini",
      "description": "Fast, high-volume tasks"
    }
  }
}

For custom endpoints, set the base URL in your environment:

export OPENAI_BASE_URL="https://your-endpoint.example.com/v1"
export OPENAI_API_KEY="your-api-key"

Codex CLI Configuration

After deploying AIWG artifacts, configure the Codex CLI to use them:

# ~/.codex/config.toml

[model]
default = "codex-mini-latest"
reasoning = "gpt-5.3-codex"

[context]
# AIWG agents load from .codex/agents/ automatically

[prompts]
# AIWG commands available at ~/.codex/prompts/

Loading AIWG Context in Codex

# Start a Codex session with AIWG context
codex --context .codex/agents/architecture-designer.md

# Run an AIWG skill
/sdlc-status

# Use a deployed AIWG command
/mention-wire

AIWG-Specific Configuration

Customizing Codex Model Assignments

Override the default model mapping in `models.json`:

{
  "openai": {
    "reasoning": {
      "model": "gpt-5.3-codex"
    },
    "coding": {
      "model": "codex-mini-latest"
    },
    "efficiency": {
      "model": "gpt-5-codex-mini"
    }
  }
}

Place this at the project root or `~/.config/aiwg/models.json`.

Verifying Deployed Models

After running `aiwg use sdlc --provider codex`, check that model replacement worked:

# Check a deployed agent's model field
head -5 .codex/agents/architecture-designer.md
# Should show: model: gpt-5.3-codex (not model: opus)

head -5 .codex/agents/software-implementer.md
# Should show: model: codex-mini-latest (not model: sonnet)

Troubleshooting

Issue	Cause	Fix
Agent still shows `model: opus` after deploy	Deployment did not run transformation	Re-run `aiwg use sdlc --provider codex --force`
Commands not available in Codex CLI	Deploy wrote to project, not home dir	Run `aiwg use sdlc --provider codex --commands-only` — writes to `~/.codex/prompts/`
JSON mode error: "must include JSON in prompt"	`response_format: json_object` requires JSON mention	Add "Return your response as JSON" to system prompt
High token costs on batch operations	Repeating large context per request	Move shared context to system message for caching
Structured output parse failure	Schema mismatch	Use `model.model_dump()` to debug schema vs response

GPT