Use Agent Development Kit to Build, Test, and Deploy Agentspublic

The Agent Development Kit (ADK) is an SDK to build, test, and deploy agent workflows from within your development environments. You can opt in the public preview from the Feature Preview page.

Prerequisites

You must have the following prerequisites to use the ADK:

• Python version 3.10 or higher. Run python --version or python3 --version to check your Python version.

  If your version is not 3.10 or higher, you can install it using one of these methods:

  • Download from python.org.

  • Run one of the following commands in your command line terminal:

    • pyenv install 3.13.0 && pyenv local 3.13.0
    • conda create -n gradient python=3.13 && conda activate gradient

• ADK Feature Preview enabled. You can opt in from the Feature Preview page. If you can’t see the option, contact your team owner to enable it for you.

• API Access Keys. You need the following keys to use the ADK:

  • Model access key to authenticate access to open-source and commercial models for serverless inference on the Gradient AI Platform.

    Go to the Serverless Inference tab in the control panel and scroll down to the Model Access Keys section. Click Create Access Key or copy an existing one.

    Add the model access key as the GRADIENT_MODEL_ACCESS_KEY environment variable to the .env file.

    For running or testing your agent locally, you must also export the key so that it is accessible to the application. To do this, run the following command:

    export GRADIENT_MODEL_ACCESS_KEY="<your_model_key>"

  • Your account’s personal access token to allow deploying agents to your DigitalOcean account.

    Go to the API Tokens page in the control panel and click Generate New Token. Configure the following CRUD scopes:

    • Create, read, update, delete scopes for genai
    • Read scope for project

    Provide a descriptive name for your token such as Gradient ADK - Production.

    Add the API key as the DIGITALOCEAN_API_TOKEN environment variable to the .env file.

• An .env file with environment variables to use in agent deployment. Use the following command to create the .env file and add the model access key, GRADIENT_MODEL_ACCESS_KEY, and your account’s personal access token, DIGITALOCEAN_API_TOKEN, environment variables to enable agent deployment to your DigitalOcean account:

  cat > .env << EOF
  GRADIENT_MODEL_ACCESS_KEY=<your_model_key>
  DIGITALOCEAN_API_TOKEN=<your_api_token>
  EOF

  Warning

  Do not commit the `.env` file to Git. Make sure to add it to your `.gitignore` file.
  

• A requirements.txt file at the root of the folder or repo to deploy, listing your dependencies.

Build New Agent

To build and deploy a new agent using the ADK, follow these steps:

1. Initialize a new agent project using the following command:

   gradient agent init

   When prompted, specify an agent workspace name and an agent deployment name. For example, my-first-agent and development.

   When you run this command, the following directory structure is created:

   my-agent/
   ├── main.py              # Your entrypoint (modify this!)
   ├── .gradient/
   │   └── agent.yml        # Config (don't edit manually)
   ├── requirements.txt     # Python packages (add dependencies here)
   ├── .env                 # API keys (YOU create this)
   ├── agents/              # Your agent code (optional)
   └── tools/               # Custom tools (optional)

   To provide an easy way for you to create an agent, the command also:

   • Creates a base template (main.py) for a simple LangGraph example agent that calls a openai-gpt-oss-120b model using serverless inference
   • Creates a configuration file (agents.yml) required to run or deploy your agent
   • Installs all necessary dependencies for agent development

2. Run and test the example agent locally using the following command:

   gradient agent run

   The output looks like this:

   Entrypoint: main.py
   Server: http://0.0.0.0:8080
   Agent: my-first-agent
   Entrypoint endpoint: http://0.0.0.0:8080/run

   You can then access the agent and interact with it at the http://0.0.0.0:8080/run endpoint.

   To interact with the agent, send a POST request to this endpoint with a prompt in the request body. For example, your request body can be '{"prompt": "How are you?"}':

   curl -X POST http://localhost:8080/run \
     -H "Content-Type: application/json" \
     -d '{"prompt": "Hello! How are you?"}'

   Your agent processes the request and returns a response:

   {
     "response": "Hello! I'm doing well, thank you for asking. How can I help you today?"
   }

   To view more verbose logs, use:

   gradient agent run --verbose

3. Once you verify that your agent is working correctly locally, deploy it to your DigitalOcean account using the following commands:

   export DIGITALOCEAN_API_TOKEN="<your_api-token>"
   gradient agent deploy

   The deployment takes between 1 to 5 minutes. After the deployment succeeds, you see a Deployment completed successfully message and the deployment URL that the agent is running on in your terminal.

   ✅ Deployment completed successfully! [01:23]
   Agent deployed successfully! (my-first-agent/development)
   Deployment URL:
   https://agents.do-ai.run/v1/abc123-xxxx-xxxx/development/run

4. Test the deployed agent by sending a POST request with a prompt in the request body to the deployment endpoint URL. For example, the request body can be '{"prompt": "hello"}:

   curl -X POST \
     -H "Authorization: Bearer $DIGITALOCEAN_API_TOKEN" \
     -H "Content-Type: application/json" \
     "https://agents.do-ai.run/v1/abc123-xxxx-xxxx/development/run" \
     -d '{"prompt": "Hello deployed agent!"}'

   Your agent deployment processes the request and returns a response:

   {
     "response": "Hello! How can I assist you today?"
   }

For more detailed information on building, testing, and deploying agents using the ADK, see Build Agents Using Agent Development Kit.