How to Use Agents in Your Applicationspublic

You can access your agent through two different interfaces: an endpoint or a chatbot.

• Endpoint: Endpoints are URLs automatically generated upon agent creation and you can integrate them into your app to send requests to and receive JSON responses from. Similar to a chatbot interface, you can send the agent a string of text that the agent processes and responds to. Using an endpoint also allows you to configure additional request parameters, such as maximum tokens to generate and retrieval information settings.

• Chatbot: Chatbots allow users to interact with your agent through a chatbot interface that you embed into your site using a snippet of HTML code. You can only use the chatbot interface if the agent’s endpoint is set to public.

Using either an endpoint or chatbot depends on your use case. If you want to integrate your agent into a customized user interface or use it to produce content for your website, an endpoint is a good option. If you want to create a basic technical support chatbot for your company’s website, an embedded chatbot is a better option.

Set Your Agent’s Endpoint Availability

Before using your agent, we recommend setting the endpoint’s availability to determine who can access it and what interfaces are available. You can set the agent’s endpoint to either private or public.

• Private: Agent endpoints are set to private by default. This means only other resources in your account, such as other agents or functions, or requests authenticated with an access key can access the agent.

• Public: Public endpoints allow you to access and use the chatbot embed feature. You do not need to set up an access key to use an embedded chatbot, however, like private endpoints, requests sent directly to an agent’s endpoint still require an access key.

To change endpoint’s availability in the DigitalOcean Control Panel, click on your agent’s name. In the Overview tab, scroll down to the ENDPOINT section and click the Edit button. In the Set endpoint availability to private window, select the availability you want and click Save.

If you set your agent’s endpoint to public, the chatbot embed code becomes available in the CHATBOT section below the ENDPOINT section.

Using Automation

Changing an agent endpoint from private to public requires the unique identifier for the agent. To obtain a list of agents with their unique identifiers, use the /v2/gen-ai/agents endpoint.

curl -X PUT \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $PREVIEW_API_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/agents/1b418231-b7d6-11ef-bf8f-4e013e2ddde4/deployment_visibility" \
  -d '{
    "uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4",
    "visibility": "VISIBILITY_PUBLIC"
  }'

To use the public endpoint in your app, copy the URL from the url field returned in the response.

Setting the endpoint public displays a Chatbot section with a JavaScript code snippet in the Overview tab in the control panel. Copy and paste the code snippet directly into your application, such as WordPress, to use the chatbot. To learn more, see the community articles on adding chatbots.

Create an Access Key for an Endpoint

To access an agent’s endpoint from an external source outside of DigitalOcean, you need create an access key. Access keys are used to authenticate requests to the agent’s endpoint.

To create the access key from the DigitalOcean Control Panel, on the left side menu, click GenAI Platform, then select the agent you want to make a key for. On the agent’s page, click the Settings tab. In the Endpoint Access Keys section, click Create Key to open the Create Agent Access Key window. Provide a name for the key in the Key name field and then click Create to see your newly created key.

Then, copy the secret key and securely store it. We do not show it again for security reasons.

Once you have the key, you can integrate it into your app to authenticate requests.

Using Automation

Creating an agent endpoint API key using the DigitalOcean API requires the unique identifier of the agent and a name for the key. To obtain a list of agents with their unique identifiers, use the /v2/gen-ai/agents endpoint.

curl -X POST \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $PREVIEW_API_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/agents/1b418231-b7d6-11ef-bf8f-4e013e2ddde4/api_keys" \
  -d '{
    "agent_uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4",
    "name": "test-key"
  }'

You can list all agent API keys, regenerate a key, or update a key after creation.

Use Agent’s Endpoints

In the [DigitalOcean Control Panel(https://cloud.digitalocean.com/gen-ai/agents), endpoints are located in the agent’s Overview tab under the ENDPOINT section.

You can send requests to the endpoint’s API by appending /api/v1/chat/completions to the end of the URL and sending a JSON request body, like in this example cURL request:

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
  }'

This cURL example sends a request to the agent’s endpoint to generate a response to the user’s question What is the capital of France?. It uses an AGENT_ENDPOINT and AGENT_ACCESS_KEY environment variables to authenticate the request.

Each endpoint has its own API documentation that you can access by appending /docs to the end of the URL, like this: https://<agent-indentifier>.ondigitalocean.app/docs. The documentation contains a rendered OpenAPI specification of all available request body parameters and response schemas.

The following example shows how to use the OpenAI Python library to send a request to an agent’s endpoint.

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

This script sends a request to an agent’s endpoint and asks it to return the name of France’s capital in JSON format in the console and its retrieval information. You do not need to append /chat/completions to the end of the endpoint URL when using the openai library.

Use Chatbot Interface

To embed the chatbot widget on public sites, set your agent’s endpoint to public. Setting the endpoint public displays a CHATBOT section with an HTML <script> element snippet. Copy and paste the code snippet directly into your application, such as a WordPress or static HTML website, to use the chatbot.

The embed code 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>

The embed code contains several parameters that you can customize to fit the look and feel of your application. To set a logo for the chatbot, upload an image to your website and then set the data-logo parameter to the URL of the image. You do not need to treat the data-agent-id and data-chatbot-id fields as secrets.