Create a Custom Conversational Agent by Sitemap – A Step-by-Step Guide Using the CustomGPT API

In this guide, you will learn how to build a custom chatbot (agent) from a sitemap using the CustomGPT API. We will walk through the process—from setting up your environment and creating a new agent to verifying its active status and starting a conversation for real-time Q&A. Make sure you’ve read our “Getting Started with CustomGPT.ai for New Developers” post for a full overview of the platform.

Make sure you have read our Getting Started with CustomGPT.ai for New Developers blog to get an overview of the entire platform..

1. Prerequisites

Before you start, ensure you have the following:

• CustomGPT.ai Account: Sign up at CustomGPT.ai if you haven’t already.
• API Key: Retrieve your API token from your dashboard and keep it secure.
• Google Colab or Local Environment: You can run Python code with libraries like requests and sseclient-py.
• Basic Python Knowledge: Familiarity with Python syntax and REST APIs is recommended.

Note: In this guide, when we mention “project,” we mean “agent.”

2. Setting Up Your Environment

Open the Notebook

Upload the Create_Bot_By_Sitemap.ipynb notebook to Google Colab or open it in your favorite Python IDE.

Install Required Libraries

Most libraries, such as requests and json, come with Python. For streaming responses, install the SSE client:

!pip install sseclient-py

Configure Your API Key

At the top of the notebook, you’ll see the API endpoint and token setup:

api_endpoint = 'https://app.customgpt.ai/api/v1/'

api_token = 'ADD_YOUR_API_TOKEN_HERE'

headers = {

    'Content-Type': 'application/json',

    'Authorization': 'Bearer ' + api_token

}

Replace ‘ADD_YOUR_API_TOKEN_HERE‘ with your actual API token. Keep this token private for security.

Get Your API Key

To get your API key, there are two ways:

Method 1 – Via Agent

1. Agent > All Agents.
2. Select your agent and go to deploy, click on the API key section and create an API. 

Method 2 – Via Profile section.

1. Go to profile (top right corner of your screen)
2. Click on My Profile
3. You will see the screen something like this (below screenshot). Here you can click on “Create API key”, give it a name and copy the key.

Please save this secret key somewhere safe and accessible. For security reasons, You won’t be able to view it again through your CustomGPT.ai account. If you lose this secret key, you’ll need to generate a new one.

With your environment ready and your API key in place, we now move on to the code walkthrough.

3. Code Walkthrough

This section explains each part of the code, making it easy to follow along.

3.1 Create a New Agent from a Sitemap

We start by creating a new agent using a sitemap. This step seeds your agent with content.

api_endpoint = 'https://app.customgpt.ai/api/v1/'

api_token = 'ADD_YOUR_API_TOKEN_HERE'

headers = {

    'Content-Type': 'application/json',

    'Authorization': 'Bearer ' + api_token

}

project_name = 'Example ChatBot using Sitemap'

sitemap_path = 'https://adorosario.github.io/small-sitemap.xml'

payload = json.dumps({

    "project_name": project_name,

    "sitemap_path": sitemap_path

})

url = api_endpoint + 'projects'

create_project = requests.request('POST', url, headers=headers, data=payload)

print(create_project.text)

What’s Happening Here:

• API Endpoint & Token Setup: api_endpoint defines the base URL for the API calls. The api_token is used for authentication.
• Project Creation Payload: project_name gives your agent a descriptive name, while sitemap_path provides the URL to the sitemap that seeds your agent’s knowledge.
• Sending the Request: A POST request is sent to <api_endpoint>/projects to create a new agent. The response contains details like a unique project (agent) ID.

Once the agent is created, we extract its ID and verify that it’s active.

3.2 Extract the Agent ID and Check If Chatbot Is Active

Now, let’s extract the agent ID and check if the chatbot is active.

data = json.loads(create_project.text)["data"]

project_id = data["id"]

url = api_endpoint + 'projects/' + str(project_id)

get_project = requests.request('GET', url, headers=headers)

project_data = json.loads(get_project.text)["data"]

is_chat_active = project_data["is_chat_active"]

print(is_chat_active)

Explanation:

• Parsing the Response: The agent’s unique ID is extracted from the JSON response.
• Check Chatbot Status: A GET request to <api_endpoint>/projects/<project_id> retrieves agent details. The is_chat_active flag tells you if the chatbot is ready to handle queries.

With your agent verified as active, we now create a conversation.

3.3 Create a Conversation

Create a conversation session under your agent to start interacting with it.

url = api_endpoint + 'projects/' + str(project_id) + '/conversations'

payload = json.dumps({

    "name": "My First Conversation"

})

create_conversation = requests.request("POST", url, headers=headers, data=payload)

print(create_conversation.text)

Key Points:

• Endpoint for Conversations:
  Conversations are created at <api_endpoint>/projects/<project_id>/conversations.
• Naming Your Conversation:
  A unique name is provided to help you identify the conversation later.
• Response Details:
  The response contains metadata, including a session_id, which is needed to track the conversation.

After setting up the conversation, we prepare to handle streaming responses.

3.4 Install SSEClient for Streaming Responses

For real-time streaming responses, install and import the SSE client:

!pip install sseclient-py

Then, in your Python code:

from sseclient import SSEClient

Why Use SSEClient?
SSE (Server-Sent Events) allows you to stream real-time data over HTTP. This is useful for getting immediate responses from your chatbot.

Next, we use SSEClient to send a streaming message.

3.5 Send a Streaming Message

Now, send a message to your chatbot and receive a streaming response.

conversation_data = json.loads(create_conversation.text)["data"]

session_id = conversation_data["session_id"]

prompt = "Who is Tom Brady"

stream = 1

url = api_endpoint + 'projects/' + str(project_id) + '/conversations/' + str(session_id) + '/messages'

payload = json.dumps({

    "prompt": prompt,

    "stream": stream

})

headers["Accept"] = "text/event-stream"

stream_response = requests.post(url, stream=True, headers=headers, data=payload)

client = SSEClient(stream_response)

for event in client.events():

    print(event.data)

Step-by-Step Breakdown:

• Obtain the session_id: This keeps track of your conversation’s context.
• Prepare the Prompt: The prompt is the question you want the chatbot to answer.
• Enabling Streaming: Setting stream = 1 tells the API to return a streaming response. The header Accept: text/event-stream ensures the API returns SSE data.
• Processing the Stream: SSEClient listens for incoming events and prints each event as it arrives.

With the streaming message in place, you can now run and verify the entire notebook.

4. Running and Verifying the Notebook

Step-by-Step Execution:

1. Run Cells Sequentially:
   Execute each cell in your Colab notebook (or local environment) in order.
2. Check the Outputs:
   • Confirm that the agent is created successfully.
   • Verify that is_chat_active returns a true or active indicator.
   • Observe the streaming messages to see real-time responses from the chatbot.

Log in to CustomGPT.ai:
Visit your CustomGPT.ai dashboard to see your newly created agent, check the conversation details, and review usage statistics.

After confirming that everything works, you’re ready to explore further customizations.

5. Troubleshooting Common Issues

If you run into any problems, consider the following tips:

• Invalid API Token: Ensure that you’ve replaced ‘ADD_YOUR_API_TOKEN_HERE‘ with your actual API token.
• Agent Creation Errors: Verify that the sitemap URL is valid and accessible.
• Chatbot Inactive: If is_chat_active is false, wait a few seconds or poll the details again.
• Streaming Errors: Make sure you have installed sseclient-py and check your internet connection if you encounter SSL or connection issues.

For further assistance, consult the official CustomGPT.ai documentation or join our community forums.

6. Conclusion

Congratulations! You’ve successfully created a custom chatbot (agent) from a sitemap using the CustomGPT API. In this guide, you learned how to:

• Set up your environment and configure your API token.
• Create a new agent and check its active status.
• Start a conversation and send a streaming message for real-time interaction.

You can build on this foundation by customizing prompts, integrating additional data sources, or exploring other features to fully manage your chatbot’s lifecycle. If you have any questions or need additional support, visit CustomGPT.ai for documentation or community help.

Happy coding, and enjoy building your chatbot with CustomGPT.ai!