> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentflow.live/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAI GPT Integration

> Connect OpenAI GPT-4 models to your AgentFlow platform

## Overview

Integrate OpenAI's GPT-4 models for advanced conversational AI capabilities. This guide covers setting up the AI connection, configuring via YAML, and using it in conversations.

***

## Step 1: Create the AI Connection

### Get Your OpenAI API Key

1. Visit [OpenAI Platform](https://platform.openai.com/api-keys)
2. Sign in or create an account
3. Navigate to **API Keys**
4. Click **Create new secret key**
5. Copy and save your API key securely

<Warning>
  Keep your API key secure. Never commit it to version control or share it publicly.
</Warning>

### Add Connection in AgentFlow

1. Go to **Admin Dashboard** → **AI Models**

2. Click **Add Model**

3. Fill in the basic information:
   * **Name**: `OpenAI GPT-4.1`
   * **Model ID**: `openai-gpt-4.1`
   * **Description**: `Direct integration with OpenAI GPT-4.1 for advanced conversational AI`

4. Configure the API settings:
   * **Endpoint**: `https://api.openai.com/v1/chat/completions`
   * **Method**: `POST`

5. Add headers:
   ```json theme={null}
   {
     "Authorization": "Bearer {{openai_api_key}}",
     "Content-Type": "application/json"
   }
   ```

6. Configure request schema:
   ```json theme={null}
   {
     "model": "gpt-4.1-turbo",
     "messages": [
       {
         "role": "system",
         "content": "{{system_prompt}}"
       },
       {
         "role": "user",
         "content": "{{user_message}}"
       }
     ],
     "temperature": 0.7,
     "max_tokens": 4000,
     "top_p": 1,
     "frequency_penalty": 0,
     "presence_penalty": 0
   }
   ```

7. Set response path: `choices[0].message.content`

8. Click **Save** to create the connection

***

## Step 2: Import Configuration via YAML

### Manual YAML Configuration

Create a file named `openai-gpt-config.yaml`:

```yaml theme={null}
name: "OpenAI GPT-4.1 Chat Completion"
model_id: "openai-gpt-4.1"
description: "Direct integration with OpenAI GPT-4.1 for advanced conversational AI capabilities"
endpoint: "https://api.openai.com/v1/chat/completions"
method: "POST"

headers:
  Authorization: "Bearer {{openai_api_key}}"
  Content-Type: "application/json"

request_schema:
  model: "gpt-4.1-turbo"
  messages:
    - role: "system"
      content: "{{system_prompt}}"
    - role: "user"
      content: "{{user_message}}"
  temperature: 0.7
  max_tokens: 4000
  top_p: 1
  frequency_penalty: 0
  presence_penalty: 0
  stream: false
  user: "{{user_id}}"

response_path: "choices[0].message.content"

message_format:
  preset: "openai_chat"
  mapping:
    role:
      source: "role"
      target: "messages[{{message_index}}].role"
      transform: "openai_role"
    content:
      source: "content"
      target: "messages[{{message_index}}].content"
      transform: "none"
    timestamp:
      source: "timestamp"
      target: "metadata.timestamp"
      transform: "iso8601"
  customFields:
    - name: "model_configuration"
      value:
        platform: "openai"
        model: "gpt-4.1-turbo"
        version: "latest"
        capabilities: ["text_generation", "reasoning", "code_generation"]
      type: "object"
    - name: "generation_settings"
      value:
        temperature: 0.7
        max_tokens: 4000
        top_p: 1
        frequency_penalty: 0
        presence_penalty: 0
      type: "object"

suggestion_prompts:
  - "Generate creative marketing copy for a new product launch"
  - "Analyze complex data and provide strategic recommendations"
  - "Write technical documentation for API endpoints"
  - "Create personalized email templates for different customer segments"
  - "Generate code solutions for specific programming challenges"
```

### Import the YAML Configuration

1. Go to **Admin Dashboard** → **AI Models**
2. Click **Import Model**
3. Upload your `openai-gpt-config.yaml` file
4. Review the configuration
5. Enter your OpenAI API key in the secure field
6. Click **Import**

<Tip>
  YAML imports automatically configure message formatting and presets, saving you time!
</Tip>

***

## Step 3: Assign to a Group

1. Go to **Admin Dashboard** → **Groups**
2. Select or create a group (e.g., "Marketing Team")
3. Click **Manage Models**
4. Select your OpenAI GPT-4.1 model
5. Click **Save**

Now all users in this group can access the model!

***

## Step 4: Use in Chat

### Start a Conversation

1. Navigate to the **Chat** interface
2. Click **New Conversation**
3. Select **OpenAI GPT-4.1** from the model dropdown
4. Start chatting!

### Example Prompts

<CodeGroup>
  ```text Marketing theme={null}
  Generate a compelling product description for a new AI-powered analytics tool that helps businesses make data-driven decisions.
  ```

  ```text Technical theme={null}
  Write a Python function that implements a binary search algorithm with error handling and type hints.
  ```

  ```text Analysis theme={null}
  Analyze the pros and cons of microservices vs monolithic architecture for a startup with 10 engineers.
  ```
</CodeGroup>

***

## Advanced Configuration

### Streaming Responses

To enable streaming for real-time responses:

```yaml theme={null}
request_schema:
  stream: true
```

Then handle streaming in your application using Server-Sent Events (SSE).

### Custom System Prompts

Override the default system prompt per conversation:

```json theme={null}
{
  "system_prompt": "You are a helpful marketing assistant specializing in B2B SaaS companies."
}
```

### Temperature Control

Adjust creativity vs consistency:

* **0.0-0.3**: Focused, deterministic responses
* **0.4-0.7**: Balanced creativity
* **0.8-1.0**: Maximum creativity

***

## Troubleshooting

### Authentication Errors

<AccordionGroup>
  <Accordion title="Invalid API Key">
    Verify your API key is correct and has not expired. Generate a new key if needed.
  </Accordion>

  <Accordion title="Rate Limit Exceeded">
    Check your OpenAI usage limits and upgrade your plan if necessary.
  </Accordion>

  <Accordion title="Insufficient Quota">
    Add credits to your OpenAI account or check billing settings.
  </Accordion>
</AccordionGroup>

### Response Issues

* **Empty responses**: Check your max\_tokens setting
* **Timeout errors**: Increase timeout value in advanced settings
* **Formatting issues**: Verify response\_path is correct

***

## Cost Optimization

### Token Management

Monitor and optimize token usage:

1. Set appropriate `max_tokens` limits
2. Use shorter system prompts when possible
3. Implement conversation history trimming
4. Track usage in **Analytics Dashboard**

### Model Selection

Choose the right model for your use case:

* **GPT-4.1 Turbo**: Best for complex reasoning
* **GPT-4.1**: Balanced performance
* **GPT-3.5 Turbo**: Cost-effective for simple tasks

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Anthropic Claude" icon="brain" href="/examples/anthropic-claude">
    Add Claude for advanced reasoning
  </Card>

  <Card title="Agent Builder" icon="robot" href="/examples/openai-agent-builder">
    Build OpenAI Assistants
  </Card>

  <Card title="Analytics" icon="chart-line" href="/analytics/usage-metrics">
    Track model usage
  </Card>

  <Card title="Groups" icon="users" href="/organization/roles-and-permissions">
    Manage access control
  </Card>
</CardGroup>