# How to Create Agents on DigitalOcean Gradient™ AI Platform

DigitalOcean Gradient™ AI Platform lets you build fully-managed AI agents with knowledge bases for retrieval-augmented generation, multi-agent routing, guardrails, and more, or use serverless inference to make direct requests to popular foundation models.

You can create agents using the DigitalOcean [API or CLI](#create-an-agent-using-automation), [control panel](#create-an-agent-using-the-control-panel), or [Agent Development Kit](https://docs.digitalocean.com/products/gradient-ai-platform/how-to/build-agents-using-adk/index.html.md).

## Create an Agent Using Automation

To create an agent with the DigitalOcean API or CLI, provide a name, a [foundation model](https://docs.digitalocean.com/products/gradient-ai-platform/details/models/index.html.md#foundation-models), [instructions](https://docs.digitalocean.com/products/gradient-ai-platform/concepts/agent-instructions/index.html.md), the project identifier, and the datacenter region. We strongly recommend adding a [knowledge base](https://docs.digitalocean.com/products/gradient-ai-platform/how-to/create-manage-agent-knowledge-bases/index.html.md) so your agent can ground its responses in your own domain data, reducing hallucinations and improving accuracy.

You can use the API or CLI to get available options for these parameters:

- To list available models and their identifiers, use the [`/v2/gen-ai/models` endpoint](https://docs.digitalocean.com/reference/api/reference/gradientai-platform/index.html.md#genai_list_models) or the [`doctl gradient list-models`](https://docs.digitalocean.com/reference/doctl/reference/gradient/list-models/index.html.md) command.

  The first time you use a model from a provider, you must accept the provider’s terms in the [DigitalOcean Control Panel](#create-an-agent-using-the-control-panel).
- To view available datacenters, use the [`/v2/gen-ai/regions` endpoint](https://docs.digitalocean.com/reference/api/reference/gradientai-platform/index.html.md#genai_list_regions) or the [`doctl gradient list-regions`](https://docs.digitalocean.com/reference/doctl/reference/gradient/list-regions/index.html.md) command.
- To list (or create) knowledge bases, use the [`/v2/gen-ai/knowledge_bases` endpoint](https://docs.digitalocean.com/reference/api/reference/gradientai-platform/index.html.md#genai_list_knowledge_base) or the [`doctl gradient knowledge-base create`](https://docs.digitalocean.com/reference/doctl/reference/gradient/knowledge-base/create/index.html.md) command.

## How to Create an Agent Using the DigitalOcean CLI

1. [Install `doctl`](https://docs.digitalocean.com/reference/doctl/how-to/install/index.html.md), the official DigitalOcean CLI.
2. [Create a personal access token](https://docs.digitalocean.com/reference/api/create-personal-access-token/index.html.md) and save it for use with `doctl`.
3. Use the token to grant `doctl` access to your DigitalOcean account.

   ```shell
   doctl auth init
   ```
4. Finally, run `doctl gradient agent create`. Basic usage looks like this, but you can [read the usage docs](https://docs.digitalocean.com/reference/doctl/reference/gradient/agent/create/index.html.md) for more details:

   ```shell
   doctl gradient agent create <agent-name>... [flags]
   ```

   The following example creates an agent:

   ```shell
   doctl gradient agent create --name "My Agent" --project-id "12345678-1234-1234-1234-123456789012" --model-id "12345678-1234-1234-1234-123456789013" --region "tor1" --instruction "You are an agent who thinks deeply about the world"
   ```

## How to Create an Agent Using the DigitalOcean API

1. [Create a personal access token](https://docs.digitalocean.com/reference/api/create-personal-access-token/index.html.md) and save it for use with the API.
2. Send a POST request to [`https://api.digitalocean.com/v2/gen-ai/agents`](https://docs.digitalocean.com/reference/api/reference/gradientai-platform/index.html.md#genai_create_agent).

### cURL

Using cURL:

```shell
curl -X POST \
    -H "Content-Type: application/json"  \
    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
    "https://api.digitalocean.com/v2/gen-ai/agents" \
    -d '{
      "name": "api-create",
      "model_uuid": "95ea6652-75ed-11ef-bf8f-4e013e2ddde4",
      "instruction": "be a weather reporter",
      "description": "weather-agent",
      "project_id": "37455431-84bd-4fa2-94cf-e8486f8f8c5e",
      "tags": [
        "tag1"
      ],
      "region": "tor1",
      "knowledge_base_uuid": [
        "9758a232-b351-11ef-bf8f-4e013e2ddde4"
      ]
    }'
```

## Create an Agent Using the Control Panel

You can create an agent with a custom configuration by defining the agent’s objective, model, and settings. You can add also a knowledge base.

To create an agent from the [DigitalOcean Control Panel](https://cloud.digitalocean.com), in the left menu, click **Agent Platform** to go to the **Agent Workspaces** tab. Click the workspace where you want to create an agent. In the **Agents** tab, click **Create Agent** to open the **Create an agent** page, where you can choose a custom configuration.

### Give Your Agent a Name

Choose a descriptive name in the **Agent name** field that reflects the agent’s role or expertise.

### Define Agent Instructions

Provide clear instructions that define your agent’s identity, objectives, expertise, and boundaries. These instructions help the agent understand what role it plays, what tasks it should prioritize, and which resources it can use.

> You are a travel agent. You help find airline tickets and car rentals, compare prices, schedules, and find the best deals.
> You also suggest hotel, resort, or vacation rentals that cost less than $5,000 for a week.
> Make sure that the recommendations you make are clear, actionable, and customized to the financial situation.

See [Write Effective Agent Instructions](https://docs.digitalocean.com/products/gradient-ai-platform/concepts/agent-instructions/index.html.md) for best practices. You can also use the [agent instruction templates](https://docs.digitalocean.com/products/gradient-ai-platform/concepts/agent-instructions/index.html.md#copyable-templates) as-is or adapt them to your needs.

### Select a Model

Agents use foundation models to interpret prompts and generate responses.

Choose a model provider from the **Select a model provider** drop-down list, and then from the **Select model** drop-down list, select the [foundation model](https://docs.digitalocean.com/products/gradient-ai-platform/details/models/index.html.md#foundation-models) you want to use. To test models before choosing, [use the Model Playground](https://docs.digitalocean.com/products/gradient-ai-platform/how-to/configure-models/index.html.md) by clicking **Model Playground**.

![Select model section showing a select a model provider sub-section, a drop-down menu for selecting a model from the provider with token pricing information and a link to add or use an API key.](https://docs.digitalocean.com/screenshots/gradient-ai-platform/select-model.8be46774648e5fe87f06ac80fc73a5fd677297f46a10e9028d02084911990f9b.png)

OpenAI GPT-5 is the model selected by default. You can also choose models from other providers such as Anthropic Claude, Mistral Nemo, or Meta Llama, and [change the foundation model at any time after creating the agent](https://docs.digitalocean.com/products/gradient-ai-platform/how-to/use-agents/index.html.md#use-after-model-update).

## Bring Your Own Model Provider API Key

For commercial models like [OpenAI](https://platform.openai.com/docs/models) or [Anthropic Claude](https://www.anthropic.com/claude) models, you can bring your own API key. We bill usage [directly to your model account](https://docs.digitalocean.com/products/gradient-ai-platform/details/pricing/index.html.md#foundation-model-usage).

Click **Add or use own key** above the model dropdown to open the **Use or Add API Key** window. If your team already has keys, choose one from the **Select key or add new key** dropdown menu and click **Verify and Save**.

![Use or Add OpenAI API Key window showing a drop-down menu with multiple saved API keys and an option to add a new key.](https://docs.digitalocean.com/screenshots/gradient-ai-platform/use-or-add-own-key.4d09cc588854047a6ee78dd39a6df406d3f7a92f5bd68e80166f41df4281ce06.png)

If you need to add a new key, select **Add a new key**. In the **API key** field, paste the key you copied from your OpenAI or Anthropic account. In **Key name** field, type a unique name without using the key itself. Names can include lowercase letters, numbers, hyphens, and periods. Then, click **Verify and Save** to validate the API key. After verification, we automatically select the API key in the dropdown.

![Select or add a new key section showing a selected API key, and a select model sub-section with a model selected.](https://docs.digitalocean.com/screenshots/gradient-ai-platform/new-own-key-added.87e8ebfc91e59711139ef911390ea8dd8cfeddb617bb928681cc319c7e6e80fb.png)

In the **Model Keys** page, you [can view, add, edit, or delete model keys](https://docs.digitalocean.com/products/gradient-ai-platform/how-to/manage-model-provider-keys/index.html.md).

### Choose a Workspace

Workspaces group related agents together under a single space to help you organize your AI agents, share them across your team, and run evaluations to test and compare their performance in a structured way. Every agent you create exists in a workspace. By default, you have one workspace called **My Agent Workspace (Created by Default)**.

In the **Where should your agent live?** section, choose a [workspace](https://docs.digitalocean.com/products/gradient-ai-platform/how-to/manage-workspaces/index.html.md) for your agent. You can select an existing workspace by clicking **Use Existing** and choosing one from the drop-down list, or create a new workspace by clicking **Create New** and providing the new workspace a name and description.

### Add Knowledge Bases

A knowledge base is a mixture of unstructured text files in Spaces buckets and web pages. Knowledge bases provide context to the prompt for your agent’s foundation model. Your agent uses knowledge bases to augment prompts to the foundation model, answer questions, and analyze documents. Examples of knowledge bases include product documentation, pricing, and product catalogs.

We strongly recommend adding one or more [knowledge bases](https://docs.digitalocean.com/products/gradient-ai-platform/how-to/create-manage-agent-knowledge-bases/index.html.md) when creating your agent to ground its responses in your data and improve accuracy, either by selecting an existing one from the **Knowledge Bases** drop-down list or creating a new one.

To keep your knowledge base up to date automatically, you can also [enable auto-indexing](https://docs.digitalocean.com/products/gradient-ai-platform/how-to/create-manage-agent-knowledge-bases/index.html.md#auto-index-data-source-control-panel).

### Finalize and Create

By default, the new agent belongs to your default project. You can choose a different project from the **Select a project** drop-down list.

Optionally, you can tags your agents. Tags organize related resources. Tags must be single words with letters, numbers, colons, dashes, or underscores.

At the bottom of this section, review the chosen agent resources and [model token rate](https://docs.digitalocean.com/products/gradient-ai-platform/details/pricing/index.html.md#foundation-model-usage).

Click **Create Agent** to complete creating the agent. Your agent appears in the **Projects** section of the control panel’s main menu.

## Next Steps

After creating your agent, you can:

- [Route tasks across multiple agents](https://docs.digitalocean.com/products/gradient-ai-platform/how-to/route-agents/index.html.md).
- [Call functions in your agent](https://docs.digitalocean.com/products/gradient-ai-platform/how-to/route-agent-functions/index.html.md).
- [Test the agent in the Agent Playground](https://docs.digitalocean.com/products/gradient-ai-platform/how-to/test-agents/index.html.md).
- [Use the agent](https://docs.digitalocean.com/products/gradient-ai-platform/how-to/use-agents/index.html.md) in a chatbot or application.