Skip to main content

​
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
  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
Keep your API key secure. Never commit it to version control or share it publicly.

​
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: 
    {
  "Authorization": "Bearer {{openai_api_key}}",
  "Content-Type": "application/json"
}
  6. Configure 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
}
  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: 
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
YAML imports automatically configure message formatting and presets, saving you time!

​
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

Generate a compelling product description for a new AI-powered analytics tool that helps businesses make data-driven decisions.

​
Advanced Configuration

​
Streaming Responses

To enable streaming for real-time responses: 
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: 
{
  "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

Verify your API key is correct and has not expired. Generate a new key if needed.
Check your OpenAI usage limits and upgrade your plan if necessary.
Add credits to your OpenAI account or check billing settings.

​
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

Anthropic Claude

Add Claude for advanced reasoning

Agent Builder

Build OpenAI Assistants

Analytics

Track model usage

Groups

Manage access control
⌘I