# Step 1: Open the AI Admin Panel
Navigate to the **AI Admin Panel** in your Avon AI dashboard.

# Step 2: Add a New Agent
Click the **Add Agent** button to start creating a new agent.

# Step 3: Choose Agent Type
Select **External Agent** from the available options.
This type is used when your agent is managed outside the platform (e.g., OpenAI, Gemini, Anthropic, etc.).

# Step 4: Define Agent Details
Fill in the following fields:

- **Agent Name** – The internal name for your agent in the platform (unique identifier).  
- **Display Title** – The visible name that appears in the platform UI and reports.  
- **Department** – The business or functional area this agent belongs to (e.g., Support, Sales, HR).  
- **Manager** – The owner or point of contact responsible for the agent’s configuration and performance.  
- **Description** – A short summary explaining the agent’s purpose or main function.

# Step 5: Continue to Configuration
Click **Next** to proceed to the configuration stage, where you’ll define the agent’s model, endpoints, and additional settings.

# Step 6: Configure Your External Agent

Under **Agent Service URL**, enter the full endpoint URL of your external agent, followed by `/chat`.

Example:
https://example.com/api/chat

---

## Request Timeout
Set the **Request Timeout**, which defines the maximum time (in seconds) that the platform will wait for a response from your external service.
If the agent does not respond within this time, the request will fail and trigger the fallback message.

---

## HTTP Headers
You can optionally add custom **HTTP Headers** to your requests.
These headers are key-value pairs sent with each API request, often used to include authentication tokens, content types, or other metadata required by your external service.

Example:
- Authorization: Bearer [your-token]
- Content-Type: application/json

---

## Fallback Message
The **Fallback Message** is the default response shown to the user if the external agent fails to respond or returns an error.
This ensures the user receives a meaningful message even when the service is unavailable.

Example:
“Sorry, I’m having trouble connecting to the agent right now. Please try again later.”

---

# External Agent Requirements

To integrate successfully, your external agent must meet the following requirements:

- **Endpoint:** Must have an endpoint that accepts `POST` requests  
- **Request format (JSON):**
  ```json
  {
    "conversationId": "...",
    "messages": [...],
    "agentId": "...",
    "userId": "..."
  }
// External Agent – Integration Requirements 
// ---------------------------------------------------------------

/*
1) Endpoint
- Your external agent must expose an HTTP endpoint that accepts POST requests.
- Provide the full URL (e.g., https://example.com/api/chat).
*/

// Example URL format (no real code executed)
// const ENDPOINT_URL = "https://example.com/api/chat";

/*
2) Request Format (JSON)
- The platform will POST a JSON payload with the following fields:
  {
    "conversationId": "...",
    "messages": [...],
    "agentId": "...",
    "userId": "..."
  }
- `messages` is an array representing the conversation so far.
*/

/*
3) Response Format (JSON)
- Your agent must return JSON with:
  {
    "role": "assistant",
    "content": "...",
    "timestamp": "..."
  }
- `role` is typically "assistant".
- `content` is the agent's reply text.
- `timestamp` is an ISO 8601 string (e.g., "2025-11-17T10:05:00Z").
*/

/*
4) HTTP Status
- On success, return HTTP 200 along with the valid JSON response above.
- Any other status code (e.g., 400/401/500) will be treated as an error.
*/

/*
5) Error Handling & Fallback
- If the endpoint times out, is unreachable, or returns an invalid structure,
  the platform will trigger your configured Fallback Message automatically.
- Set a sensible Request Timeout in the configuration to control how long
  the platform waits for a reply before falling back.
*/

/*
6) Optional: HTTP Headers
- You may configure extra headers in the platform (e.g., authentication).
- Common examples:
    Authorization: Bearer <your-token>
    Content-Type: application/json
*/

{"success":true}

Step 1- AI Admin Panel

How to access the relevant area in the platform to configure an External Agent

Step 2- Agent Configuration

The fields that must be filled in to configure your agent.