> ## 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.

# Connecting Your First AI Endpoint

> Step-by-step guide to connecting your first AI endpoint

# Connecting Your First AI Endpoint

**Connect your AI service, workflow, or custom endpoint to AgentFlow.**

AgentFlow works with ANY AI endpoint that can receive webhooks and return responses—including OpenAI, Anthropic, custom AI services, N8N workflows, Make.com automations, and more.

## Prerequisites

Before you start, you'll need:

* ✅ AgentFlow organization created
* ✅ An AI endpoint URL (OpenAI API, custom webhook, etc.)
* ✅ Authentication credentials (API key, bearer token, etc.)
* ✅ Admin access to your organization

***

## Step 1: Access the Admin Panel

<PLACEHOLDER_SCREENSHOT>
  Screenshot showing the organization dropdown menu with "Admin Panel" option highlighted
</PLACEHOLDER_SCREENSHOT>

After creating your organization, navigate to the admin panel:

1. Click your organization name in the top navigation
2. Select **"Admin Panel"** from the dropdown
3. You'll see tabs for Analytics, Models, Groups, and Users

<PLACEHOLDER_SCREENSHOT>
  Screenshot of the Admin Panel showing the tabs: Analytics, Models, Groups, and Users
</PLACEHOLDER_SCREENSHOT>

***

## Step 2: Start Connection Configuration

<PLACEHOLDER_SCREENSHOT>
  Screenshot of the Models tab showing the list of configured connections (if any) with the "+" (Add) button visible in the top right
</PLACEHOLDER_SCREENSHOT>

<Steps>
  <Step title="Go to Models Tab">
    Click the **"Models"** tab in the admin panel (this configures your AI connections)
  </Step>

  <Step title="Click Add Model">
    Click the **"+"** (plus) button to start adding a new connection
  </Step>
</Steps>

<Note>
  The "Models" tab is where you configure all AI connections—whether they're AI model APIs, workflows, or custom endpoints.
</Note>

***

## Step 3: Basic Information

<PLACEHOLDER_VIDEO>
  Screen recording showing the "Add Model/Connection" form being filled out: entering a name (e.g., "GPT-4 Assistant"), endpoint URL, adding request headers with Authorization bearer token, and adding suggestion prompts
</PLACEHOLDER_VIDEO>

Fill in the essential details for your AI connection:

### Required Fields

**Name** \*

```
Example: "GPT-4 Assistant"
A descriptive name shown in the model selection interface
```

**Endpoint** \*

```
Example: "https://api.openai.com/v1/chat/completions"
The complete URL where POST requests will be sent
Must include protocol (https://)
```

### Optional Fields

**Model ID**

```
Example: "gpt-4-assistant"
Auto-generated from name if left empty
Used for API calls and internal references
```

**Schema**

```
Example: "v1.0"
Optional version identifier for tracking API versions
```

**Description**

```
Example: "GPT-4 model for complex reasoning and analysis"
Brief explanation of what this model does
```

### Request Headers

Add authentication headers required by your endpoint:

<CardGroup cols={2}>
  <Card title="OpenAI Example" icon="key">
    **Key:** `Authorization`
    **Value:** `Bearer sk-...your-api-key...`
  </Card>

  <Card title="Custom API Example" icon="lock">
    **Key:** `X-API-Key`
    **Value:** `your-custom-token`
  </Card>
</CardGroup>

<Note>
  Headers containing sensitive data (authorization, api-key, secret) are automatically masked for security.
</Note>

**To add headers:**

1. Click **"Add Header"**
2. Enter the header key (e.g., "Authorization")
3. Enter the header value (will be masked if sensitive)
4. Repeat for additional headers
5. Click **"×"** to remove unwanted headers

### Suggestion Prompts

Add up to 3 suggested prompts to help users understand what your model can do:

**Examples:**

```
1. "Analyze the sentiment of this customer review"
2. "Summarize this document in 3 bullet points"
3. "Generate creative product name ideas"
```

These appear in the chat interface to guide users.

***

## Step 4: Field Mapping

<PLACEHOLDER_SCREENSHOT>
  Screenshot showing the field mapping interface where users map request/response fields for their endpoint
</PLACEHOLDER_SCREENSHOT>

<Note>
  **Important:** AgentFlow works with **ANY** endpoint that can respond to webhooks—not just pre-configured AI models.
</Note>

### What You Can Connect

<CardGroup cols={2}>
  <Card title="AI APIs" icon="brain">
    * OpenAI (GPT-4, GPT-3.5)
    * Anthropic (Claude)
    * Google (Gemini)
    * Custom AI services
  </Card>

  <Card title="Automation Tools" icon="wand-magic-sparkles">
    * N8N workflows
    * Make.com scenarios
    * Zapier webhooks
    * Custom integrations
  </Card>

  <Card title="Agent Builders" icon="robot">
    * ChatGPT Agent Builder
    * Custom agent endpoints
    * LangChain applications
    * AutoGPT instances
  </Card>

  <Card title="Any Webhook" icon="webhook">
    * HTTP endpoints
    * Serverless functions
    * Microservices
    * Custom APIs
  </Card>
</CardGroup>

Map your request and response fields to match your endpoint's expected format. This step varies by endpoint type—refer to your endpoint's documentation.

***

## Step 5: Request Template

Configure how messages are sent to your endpoint.

### Input Configuration

Define the request body structure:

**For OpenAI-style APIs:**

```json theme={null}
{
  "messages": [
    {"role": "user", "content": "{{user_message}}"}
  ],
  "model": "gpt-4"
}
```

**For custom endpoints:**

```json theme={null}
{
  "input": "{{user_message}}",
  "parameters": {
    "temperature": 0.7,
    "max_tokens": 2000
  }
}
```

### AJV Schema Validation

Add JSON Schema validation for your request/response format.

<Tip>
  **What is AJV?** AJV (Another JSON Validator) ensures your requests and responses match the expected format, catching errors before they cause issues.

  Learn more: [AJV Documentation](https://ajv.js.org/)
</Tip>

**Example AJV Schema:**

```json theme={null}
{
  "type": "object",
  "properties": {
    "messages": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "role": {"type": "string"},
          "content": {"type": "string"}
        },
        "required": ["role", "content"]
      }
    },
    "model": {"type": "string"}
  },
  "required": ["messages", "model"]
}
```

### Test Variables

Provide sample data to test your configuration:

**Sample Payload:**

```json theme={null}
{
  "messages": [
    {"role": "user", "content": "Hello, how are you?"}
  ],
  "model": "gpt-4"
}
```

**Validate:** Click **"Validate"** to ensure your configuration is correct.

***

## Step 6: Test Endpoint

<PLACEHOLDER_VIDEO>
  Screen recording showing: clicking the "Run Test" button, watching the loading state, seeing a successful 200 response with the actual AI response displayed, showing what a failed test looks like (401 error), then showing successful retry
</PLACEHOLDER_VIDEO>

**Critical:** AgentFlow requires your endpoint to work before saving the configuration.

<Steps>
  <Step title="Run Test">
    Click **"Run Test"** to send a request to your endpoint
  </Step>

  <Step title="Check Response">
    You should see a **200 (Success)** response
  </Step>

  <Step title="Fix if Needed">
    If you get any other status code, review and fix your configuration
  </Step>

  <Step title="Retry">
    Keep testing until you get a successful response
  </Step>
</Steps>

<Warning>
  **AgentFlow will NOT allow you to save a connection that doesn't work.** This ensures users can always rely on functional AI endpoints.
</Warning>

**Response Status Codes:**

| Code | Meaning        | Action                               |
| ---- | -------------- | ------------------------------------ |
| 200  | ✅ Success      | Proceed to next step                 |
| 401  | ❌ Unauthorized | Check your API key/auth headers      |
| 404  | ❌ Not Found    | Verify endpoint URL is correct       |
| 500  | ❌ Server Error | Check endpoint is online and working |

***

## Step 7: Define Output

<PLACEHOLDER_SCREENSHOT>
  Screenshot of the output configuration step showing the nested JSON path field (e.g., "choices\[0].message.content") with a sample response preview
</PLACEHOLDER_SCREENSHOT>

Parse the response from your endpoint to extract the agent's message.

### Nested JSON Route

Specify the path to the message content in the response:

**OpenAI Response Example:**

```json theme={null}
{
  "choices": [
    {
      "message": {
        "content": "Hello! I'm doing great, thanks for asking!"
      }
    }
  ]
}
```

**JSON Path:**

```
choices[0].message.content
```

**Custom Endpoint Example:**

```json theme={null}
{
  "output": {
    "response": "Your message here"
  }
}
```

**JSON Path:**

```
output.response
```

<Tip>
  The JSON path tells AgentFlow where to find the agent's response text in your endpoint's response.
</Tip>

***

## Step 8: Create Group & Assign Access

<PLACEHOLDER_VIDEO>
  Screen recording showing the complete group creation flow: navigating to Groups tab, clicking "Create Group", filling in group name and description, selecting the AI connection checkbox to add it to the group, adding user(s) to the group
</PLACEHOLDER_VIDEO>

Before you can use your AI connection, you must create a group and assign permissions:

<Steps>
  <Step title="Go to Groups Tab">
    Click the **"Groups"** tab in the admin panel
  </Step>

  <Step title="Create New Group">
    Click **"Create Group"** button

    * **Name:** e.g., "GPT-4 Users"
    * **Description:** Who should have access
  </Step>

  <Step title="Add Connection to Group">
    * Find your newly created AI connection
    * Check the box to add it to this group
  </Step>

  <Step title="Add Yourself to Group">
    * Find your user in the members list
    * Add yourself to the group
  </Step>
</Steps>

<Note>
  **Why groups?** Groups control access to AI connections. Only users in a group can see and use the connections assigned to that group.
</Note>

***

## Step 9: Start Conversing

<PLACEHOLDER_VIDEO>
  Screen recording showing: navigating to the Chat page, clicking "New Conversation", selecting the newly created AI connection from the model dropdown, typing a test message, and receiving a response
</PLACEHOLDER_VIDEO>

Now you're ready to use your AI connection!

1. Go to the **Chat** page
2. Click **"New Conversation"**
3. Select your AI connection from the dropdown
4. Start chatting!

<Card title="Next: Start Your First Conversation" href="/getting-started/your-first-conversation">
  Learn how to use your newly connected AI endpoint
</Card>

***

## Configuration Examples

### OpenAI GPT-4

```yaml theme={null}
Name: GPT-4 Assistant
Endpoint: https://api.openai.com/v1/chat/completions
Headers:
  - Authorization: Bearer sk-...
  - Content-Type: application/json

Request Template:
  {
    "model": "gpt-4",
    "messages": [{"role": "user", "content": "{{message}}"}]
  }

Output Path: choices[0].message.content
```

### Anthropic Claude

```yaml theme={null}
Name: Claude Sonnet
Endpoint: https://api.anthropic.com/v1/messages
Headers:
  - x-api-key: sk-ant-...
  - anthropic-version: 2023-06-01
  - Content-Type: application/json

Request Template:
  {
    "model": "claude-3-sonnet-20240229",
    "messages": [{"role": "user", "content": "{{message}}"}],
    "max_tokens": 4096
  }

Output Path: content[0].text
```

### Custom N8N Workflow

```yaml theme={null}
Name: Custom Support Agent
Endpoint: https://n8n.yourcompany.com/webhook/support-agent
Headers:
  - X-API-Key: your-webhook-secret

Request Template:
  {
    "input": "{{message}}",
    "context": "customer_support"
  }

Output Path: response
```

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Test returns 401 Unauthorized" icon="lock">
    **Problem:** Authentication failed

    **Solutions:**

    * Verify API key is correct
    * Check header key name (e.g., "Authorization" vs "X-API-Key")
    * Ensure "Bearer " prefix for OpenAI
    * Check if API key has expired
  </Accordion>

  <Accordion title="Test returns 404 Not Found" icon="map-pin">
    **Problem:** Endpoint URL is incorrect

    **Solutions:**

    * Double-check the endpoint URL
    * Ensure it includes https\://
    * Verify the path is correct (/v1/chat/completions)
    * Test the URL in Postman or curl first
  </Accordion>

  <Accordion title="Test returns 500 Server Error" icon="server">
    **Problem:** Endpoint or service is having issues

    **Solutions:**

    * Check if the service is online
    * Verify your request format matches their API
    * Test with their official documentation examples
    * Contact the service provider's support
  </Accordion>

  <Accordion title="Can't see connection in chat" icon="eye-slash">
    **Problem:** Missing group assignment

    **Solutions:**

    * Go to Groups tab
    * Create a group if you haven't
    * Add the AI connection to the group
    * Add yourself as a member of that group
  </Accordion>

  <Accordion title="Response parsing fails" icon="code">
    **Problem:** Wrong output path

    **Solutions:**

    * Check the actual response structure from test
    * Use browser console to inspect response
    * Verify JSON path syntax (e.g., choices\[0].message.content)
    * Test the path with a JSON path validator
  </Accordion>
</AccordionGroup>

***

## What's Next?

<CardGroup cols={2}>
  <Card title="Choose AI Connections" icon="brain" href="/agents/choosing-ai-models">
    Understand which connection types work best
  </Card>

  <Card title="Advanced Configuration" icon="sliders" href="/agents/configuring-agents">
    Fine-tune your connection with advanced settings
  </Card>

  <Card title="Test Your Connection" icon="vial" href="/agents/testing-agents">
    Best practices for testing before deployment
  </Card>

  <Card title="Start Conversations" icon="messages" href="/conversations/starting-conversations">
    Begin using your AI connections
  </Card>
</CardGroup>

***

<Card title="Need Help?" icon="life-ring" href="/support/getting-help">
  Contact [support@agentflow.live](mailto:support@agentflow.live) for assistance with connecting AI endpoints
</Card>