Guide to Creating Agents for the Live Agent Studio

Overview

This guide provides instructions for you to create AI agents that integrate seamlessly with our Live Agent Studio! By following the specific input/output formats and conversation history protocols, your agent can be easily added to our system and interact smoothly with the studio. This is what we mean when we say the Live Agent Studio is a community driven platform!

Introduction
Agent Requirements
Sample Agents
Input Parameters
Output Parameters
Data Output Format
Storing Messages in the Database
Required Fields
Message Field Structure
Hosting and Deployment
Information to Provide
Handling Extra Data
Building an Agent with n8n
Building an Agent with Custom Code
Testing Your Agent
Best Practices
Credit and Attribution
Frequently Asked Questions

Introduction

The Live Agent Studio allows users to interact with community-created AI agents through a unified system. As a developer, you can create an agent that can be plugged into this platform, enabling users to easily try your agent without you having to manage authentication, handle rate limiting, or build a frontend.

The key to integration is ensuring your agent communicates using the expected input/output formats and manages conversation history as specified.

Agent Requirements

To ensure compatibility with the Live Agent Studio, your agent must:

Accept specific input parameters in a POST request.
Produce output JSON in the required format.
Manage conversation history by storing messages in a SQL database (preferably Supabase).

Sample Agents

To help you get started, we have provided two sample agent implementations:

Sample n8n Agent - A barebones example of implementing an n8n agent compatible with the Live Agent Studio.
Sample Python Agent - A basic implementation example using Python with FastAPI.

Input Parameters

When the Live Agent Studio invokes your agent, it will send a POST request to your agent's webhook URL with the following JSON payload:

{
  "query": "User's input text",
  "user_id": "Unique user identifier",
  "request_id": "Unique request identifier",
  "session_id": "Conversation session identifier"
}

Parameter Details

query: (String) The user's input or question. It is sanitized and limited to 1000 characters.
user_id: (String) A unique identifier for the authenticated user.
request_id: (String) A unique ID for the request to prevent duplicate processing.
session_id: (String) A unique ID representing the conversation session.

Output Parameters

Your agent must respond with a JSON object indicating the success or failure of processing the user's query:

{
  "success": true
}

Response Details

success: (Boolean) Indicates whether the agent successfully processed the request. Use true for success and false for failure.

Note: Since all the AI messages and data are stored directly in the database, you do not need to return any additional data in the response.

Data Output Format

While the response JSON is simplified, your agent can still include additional data in the messages stored in the database. This data can be utilized by the frontend to enhance the user experience.

Storing Messages in the Database

Your agent is responsible for storing the conversation history by inserting messages into the messages table in the database. While any PostgreSQL-compatible database can be used, using Supabase directly is preferred due to its seamless integration with our platform.

Required Fields

When inserting a message into the messages table, the following fields are required:

session_id: The conversation session ID provided in the input parameters.
message: A JSON (jsonb) object containing the message details.

Message Field Structure

The message field must be a JSON object with the following structure (compatible with the AI agent node in n8n):

For User Messages

{
  "type": "human",
  "content": "User's input text"
}

For Agent Responses

{
  "type": "ai",
  "content": "Agent's response text",
  "data": {
    "...additional info for the frontend..."
  }
}

Field Descriptions

type: (String) Indicates the message source. Use "human" for user messages and "ai" for agent responses.
content: (String) The text content of the message.
data: (Object) Optional. Additional data for the frontend, matching the data field in your processing.

Inserting into Supabase

To insert a message into the messages table:

Use the session_id from the input parameters.
Create the message JSON object as per the structure above.
Insert a new record with the session_id and message fields.

Example SQL-like pseudocode:

INSERT INTO messages (session_id, message)
VALUES ('<session_id>', '<message_json_object>');

Note: If you are using a different PostgreSQL database, ensure that the table structure and insertion methods are compatible.

Hosting and Deployment

To ensure that your agent fully integrates with the Live Agent Studio's features, we offer to host and run your agent on our infrastructure. The biggest benefit to you is you don’t have to pay for the LLM usage! On top of that, this provides:

Consistency: By hosting the agent, we can ensure it adheres to all platform requirements, including security, scalability, and performance.
Feature Integration: Hosting the agent allows us to handle features like authentication, rate limiting, and logging without additional effort on your part.
Maintenance: Our team will manage the operational aspects, so you can focus on developing and improving your agent's capabilities.

How It Works

Code Submission:
- Provide us with your agent's codebase or the workflow JSON if it’s an n8n agent, ensuring it follows the guidelines outlined in this document.
Deployment:
- Our team will deploy the agent within our infrastructure, configuring it to work seamlessly with the Live Agent Studio.
Testing:
- We'll perform comprehensive testing to ensure your agent functions correctly and efficiently.
Monitoring and Updates:
- We'll monitor the agent's performance and work with you on any necessary updates or improvements.

Information to Provide

To integrate your agent into Live Agent Studio, please provide the following information:

Your Name: Your full name or your organization's name.
Your Email: Contact email address for communication.
Agent Name: A unique and descriptive name for your agent.
Agent Description: A brief description of your agent's functionality and purpose.
Agent Code/Workflow JSON: Everything we need to run the agent for you.
Handling Extra Data: Details on how the data field in your agent's response should be used by the frontend (if applicable). Include any specific frontend components or rendering instructions.
Credit URL: A URL that users can visit to learn more about your agent or your work. This can be a website, a GitHub repository, or any relevant link.

Submit Your Agent

Handling Extra Data

If your agent includes additional data in the data field of the messages stored in the database, please provide instructions on how this data should be presented in the frontend. This may involve:

Specifying the structure of the data object.
Providing details on how each field should be used or displayed.
Indicating any custom frontend components required to render the data.

Example:

If your data field includes a list of suggestions:

"data": {
  "suggestions": ["Suggestion 1", "Suggestion 2"]
}

You might instruct the frontend to display these suggestions as clickable buttons beneath the agent's response.

Building an Agent with n8n

If you choose to build your agent using n8n, follow these steps:

Create a Webhook Node:
- Set the method to POST and secure it using an authorization token (we will replace this with our own when we deploy your agent).
Process Input Parameters:
- Use a Set node to extract and assign query, user_id, request_id, and session_id.
Store User Message:
- Use the Supabase node to insert the user's message into the messages table using the provided structures.
Generate Agent Response:
- Implement your logic using AI models or other services to process the query.
Store Agent Response:
- Insert the agent's response into the messages table. You can also insert more than one agent message, and the frontend will display the messages as they come into the database!
Prepare the Response:
- Use a Set node to create the response object with { "success": true } or { "success": false }.
Respond to Live Agent Studio:
- Use the Respond to Webhook node to send back the response.

Note: You can use the AI Agent node from n8n, and as long as you change the table to messages from the default n8n_chat_history, you don’t have to worry about creating the user or agent messages in the database!

Building an Agent with Custom Code

To build your agent using custom code:

Set Up the API Endpoint:
- Create a POST endpoint using your preferred programming language and framework.
Implement Authentication:
- Validate the Authorization header against an authorization token (we will replace this with our own when we deploy your agent).
Handle Input Parameters:
- Parse the incoming JSON payload to extract query, user_id, request_id, and session_id.
Store User Message:
- Insert the user's message into the messages table in the database.
Process the Query:
- Use AI models or your custom logic to generate a response.
Store Agent Response:
- Insert the agent's response into the messages table. You can also insert more than one agent message, and the frontend will display the messages as they come into the database!
Prepare the Response:
- Create a JSON object containing { "success": true } or { "success": false }.
Respond to Live Agent Studio:
- Send the JSON response back to Live Agent Studio.

Note: Ensure your endpoint is robust, handles exceptions, and returns appropriate HTTP status codes.

Testing Your Agent

Before integrating your agent into the production environment:

Local Testing:

Use tools like Postman or cURL to simulate requests from Live Agent Studio.
Verify that your agent handles input parameters correctly and produces the expected output.
Ensure messages are correctly stored in the database.
Test how your agent handles invalid inputs, missing parameters, or unauthorized access.
Ensure that appropriate error messages and HTTP status codes are returned.
Make sure your agent responds within the acceptable time frame (ideally under 60 seconds) to prevent timeouts.
Test your agent under different load conditions to ensure scalability.

Best Practices

Security:

Always validate input parameters to prevent injection attacks.
Secure your webhook endpoint using an authorization token you define yourself (we will replace this with our own when we deploy your agent).

Performance:

Optimize your agent to respond quickly to avoid timeouts.

Scalability:

Design your agent to handle multiple concurrent requests efficiently.

Error Handling:

Return meaningful error messages and appropriate HTTP status codes.

Logging:

Implement logging for monitoring and debugging purposes.

Documentation:

Keep your code well-documented to facilitate maintenance and updates.

Credit and Attribution

We value the contributions of developers and want to ensure proper credit is given. By providing a Credit URL, users can learn more about you or your organization.

Display:

The frontend will display a link or attribution note associated with your agent’s responses.

Purpose:

This enhances transparency and allows users to explore your work further.

Frequently Asked Questions

Will Live Agent Studio handle hosting and running my agent?

Yes, we offer to host and run your agent on our infrastructure. This ensures full integration with Live Agent Studio’s features and offloads the operational aspects from you. Additionally, you won’t have to pay for LLM usage. Please provide your agent’s codebase, and we’ll handle the rest.

How should I handle the data field in the messages?

The data field is optional and can include any additional information you want to pass to the frontend. Ensure it’s a valid JSON object and provide instructions on how it should be used.

What if my agent doesn’t need to store any extra data?

If you don’t have additional data to provide, you can omit the data field or include it as an empty object:

"data": {}

How do I secure my agent’s webhook endpoint?

Use an authorization token to authenticate requests. Validate the Authorization header in incoming requests against this token (we will replace this with our own when we deploy your agent).

Can I use a different database instead of Supabase?

Yes, you can use any PostgreSQL-compatible database. However, using Supabase is preferred due to its seamless integration with our platform.

How can I ensure my agent is added to the platform?

Provide all the required information listed in the Information to Provide section. Our team will handle the integration process.

What happens if my agent takes longer than 60 seconds to respond?

Live Agent Studio may time out and return an error to the user. To prevent this, ensure your agent responds promptly, ideally within 60 seconds.

Can I include additional endpoints or functionalities in my agent?

Yes, but the primary interaction with Live Agent Studio should be through the specified webhook endpoint and data formats. Additional functionalities should not interfere with this integration.

Who should I contact if I have questions or need assistance?

Please reach out to Cole Medin at colemedin@ottomator.ai for any questions or assistance during development.

By following this guide, you can create an AI agent that integrates smoothly with the Live Agent Studio. Your agent will be able to process user queries, manage conversation history, and enhance the user experience on our platform.

Last Updated: 2024-11-27

Live Agent Studio