GenAI Platform Quickstartpublic

GenAI agents allow you to build and manage production-ready AI agent that interact with users. You can attach guardrails, knowledge bases, functions, and other agents to make your agents more powerful and effective.

This quickstart guide shows you how to:

• Create a knowledge base (optional)
• Create an agent and attach a knowledge base to it
• Create an access key for the agent’s endpoint
• Access the agent’s endpoint and interact with it
• Access the agent’s chatbot interface

This workflow uses the DigitalOcean Control Panel, but if you want to use the DigitalOcean API to get started with GenAI, see the API quickstart section for a list of API calls that perform that same workflow.

You can do follow these steps in any order, but we recommend setting up your knowledge base first, which can help inform your agent’s design.

Add Knowledge Base (Optional)

Knowledge bases are collections of data that contain information relevant to a specific topic or domain. They provide additional context and information to the agent’s model during the generation process. For example, you can add your company’s internal documentation to a knowledge base and then add the knowledge base to an agent.

To add a knowledge base to an agent using the DigitalOcean Control Panel, click the Create button, and select Knowledge Bases.

On the knowledge base creation page, name the knowledge base, and then click the Select data source button.

In the Select data source page, you can select from the following data sources:

• Spaces bucket: Select this option if you want to upload files from a DigitalOcean Spaces bucket.
• File upload: Select this option if you want to upload files from your local machine.
• URL for web crawling: Select this option if you want to crawl a website and extract information from it.

After selecting a data source, select whether to store the knowledge base’s data in a new or existing DigitalOcean Managed OpenSearch cluster.

Next, select an embedding model. Embedding models index the data and convert it into a numerical representation that models can use to create responses. Which embedding model you choose depends on the type of data you want to store in the knowledge base and the number of tokens you want to spend indexing the data.

Finally, select the project you want to add the knowledge base to and optionally, add tags to organize and relate resources for your knowledge base. Then, review your knowledge base configurations and the estimated cost of your knowledge base indexing job, then click Create Knowledge Base.

Once the knowledge base is created, you can attach to new or existing agents.

For more explicit instructions on how to create and attach a knowledge base, see How to Create a Knowledge Base.

Create an Agent

Agents are the core resource of the GenAI Platform and you can integrate their interfaces into your applications or website.

To create an agent using the control panel, click GenAI Platform in the left menu, then click Create Agent to open the Create an Agent page.

Name your agent something that explicitly defines its purpose. This is helpful if you plan to route other agents to this one as other agents can use this context to effectively route requests.

Specify your agent instructions. Agent instructions tell your agent what you want it to do and how it should do it. You can adjust these instructions in the agent playground after creation.

Choose a model. We offer several foundation models pre-trained on large datasets and adaptable to various tasks.

If needed, you can test and compare models in the model playground before creating your agent. This environment allows you to evaluate performance and adjust settings like max tokens, temperature, and top-p.

Optionally, add a knowledge base to enable retrieval augmented generation (RAG) for your agent. Models using RAG incorporate information from a knowledge base in addition to the original training data to produce more accurate, contextually relevant responses.

Select the project you want your agent to belong to and optionally, add tags to organize and relate resources for your agent. Then, review your agent configurations and the estimated cost of your agent, then click Create Agent.

After creating your agent, test its performance.

For more explicit instructions on how to create an agent, see How to Create Agents.

Create Access Key

Access keys authenticate requests to an agent’s endpoint, similar to an API key. Any request from outside of DigitalOcean to an agent’s endpoint must include an access key.

To add access keys to an agent, go to the DigitalOcean Control Panel, select the agent you want to add access keys to, and then click the Settings tab. In the Endpoint Access Keys section, click the Create Key button.

In the Create Agent Access Key window, name the access key, and then click Create. The access key is created and displayed in the Endpoint Access Keys section. Copy the access key and save it in a secure location.

For more explicit instructions on how to create an access key, see How to Add, Edit, or Delete Model Keys.

Use Agent Endpoint

Once you have created an agent, you can use the agent’s endpoint to generate responses to user queries. The following cURL request and Python OpenAI examples show how to use the agent’s endpoint to generate responses to user queries. They use environment variables to store the agent’s endpoint ($AGENT_ENDPOINT) and access key ($AGENT_ACCESS_KEY).

If you want the request to return retrieval information about how the response was generated, such as the KB data, guardrails, and functions used, set the include_retrieval_info, include_guardrails_info, and the include_functions_info parameters to true.

cURL Example

curl -i \
  -X POST \
  $AGENT_ENDPOINT/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AGENT_ACCESS_KEY" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What is the capital of France?"
      }
    ],
    "stream": false,
    "include_functions_info": false,
    "include_retrieval_info": false,
    "include_guardrails_info": false
  }'

Python OpenAI Example

# Install OS, JSON, and OpenAI libraries.
import os
import json
from openai import OpenAI

# Set your agent endpoint and access key as environment variables in your OS.
agent_endpoint = os.getenv("agent_endpoint") + "/api/v1/" 
agent_access_key = os.getenv("agent_access_key")

if __name__ == "__main__":
    client = OpenAI(
        base_url = agent_endpoint,
        api_key = agent_access_key,
    )

    response = client.chat.completions.create(
        model = "n/a",
        messages = [{"role": "user", "content": "Can you provide the name of France's capital in JSON format."}],
        extra_body = {"include_retrieval_info": True}
    )

# Prints response's content and retrieval object.
    for choice in response.choices:
        print(choice.message.content)
    
    response_dict = response.to_dict()

    print("\nFull retrieval object:")
    print(json.dumps(response_dict["retrieval"], indent=2))

For more explicit instructions on how to use an agent’s endpoint, see How to Use Agents in Your Applications.

Embed a Chatbot

Embedded chatbots allows users to interact with your agent through a basic chat interface.

To embed a chatbot in your application or website, you first need to set your agent’s endpoint to be publicly accessible. To do this, go to your agent’s Overview page, scroll down to the Endpoint section, then click Edit. In the Set endpoint availability to public window, select Public, then click Save. This opens the CHATBOT embed code below the ENDPOINT section.

The chatbot embed code is an HTML <script> element that you can copy and past into your application or website. It looks like this:

<script async
  src="https://<agent-indentifier>.ondigitalocean.app/static/chatbot/widget.js"
  data-agent-id="<agent-data-indentifier>"
  data-chatbot-id="<agent-chatbot-indentifier>"
  data-name="My Chatbot"
  data-primary-color="#031B4E"
  data-secondary-color="#E5E8ED"
  data-button-background-color="#0061EB"
  data-starting-message="Hello! I am an AI agent. How can I help you today?"
  data-logo="https://example.com/your-logo.svg">
</script>

For more explicit instructions on how to use an agent’s chatbot embed, see How to Use Agents in Your Applications.

Use the DigitalOcean API to Create an Agent

To create an agent using the DigitalOcean API, use the following calls to create a knowledge base, agent, access key, and then retrieve the agent’s endpoint and details.

• Create a knowledge base (Optional)
• Create an agent and add a knowledge base to the agent
• Create an agent access key
• Retrieve the agent’s endpoint and details

Next Steps

Once you’ve set up an agent, you can fine tune it using the following features:

• Agent Playground: Allows you to test your agent’s responses to user queries, and then adjust the model’s parameters and configuration settings.
• Guardrails: Allows you to set rules and constraints for the agent’s responses to ensure that the agent’s responses are safe.