digitalocean/gradient-adk

digitalocean/gradient-adk

Description: The Gradient AI Platform Agent Development Kit and CLI.

Language: Python

License: Apache-2.0

Stars: 12

Forks: 6

Open issues: 5

Created: 2025-10-13T19:35:56Z

Pushed: 2026-06-01T16:40:17Z

Default branch: main

Fork: no

Archived: no

README:

DigitalOcean Agent Development Kit (ADK)

The DigitalOcean Agent Development Kit (ADK) is a Python toolkit designed to help you build, deploy, and operate production-grade AI agents with zero infrastructure overhead.

Building AI agents is challenging enough without worrying about observability, evaluations, and deployment infrastructure. We built the ADK with one simple aim: bring your agent code, and we handle the rest—bringing the simplicity you love about DigitalOcean to AI agents.

Why Use DigitalOcean ADK?

• Framework Agnostic: Bring your existing agent code—whether built with LangGraph, LangChain, CrewAI, PydanticAI, or any Python framework. No rewrites, no lock-in.

• Pay Per Use: Only pay for what you use with serverless agent hosting. Currently provided at no compute cost during Public Preview!

• Any LLM Provider: Use OpenAI, Anthropic, Google, or DigitalOcean's serverless inference—your choice, your keys.

• Built-in Observability: Get automatic traces, evaluations, and insights out of the box. No OpenTelemetry setup, no third-party integrations required.

• Production Ready from Day One: Deploy with a single command to DigitalOcean's managed infrastructure. Focus on building your agent, not managing servers.

• Seamless DigitalOcean Integration: Connect effortlessly to the DigitalOcean ecosystem—Knowledge Bases for RAG, Serverless Inference for LLMs, built-in Evaluations, and more.

Features

🛠️ CLI (Command Line Interface)

• Local Development: Run and test your agents locally with hot-reload support
• Seamless Deployment: Deploy agents to DigitalOcean with a single command
• Evaluation Framework: Run comprehensive evaluations with custom metrics and datasets
• Observability: View traces and runtime logs directly from the CLI

🚀 Runtime Environment

• Framework Agnostic: Works with any Python framework for building AI agents
• Automatic LangGraph Integration: Built-in trace capture for LangGraph nodes and state transitions
• Custom Decorators: Capture traces from any framework using @trace decorators
• Streaming Support: Full support for streaming responses with trace capture
• Production Ready: Designed for seamless deployment to DigitalOcean infrastructure

Installation

pip install gradient-adk

Quick Start

> 🎥 Watch the [Getting Started Video](https://www.youtube.com/watch?v=23xiqgrGciE) for a complete walkthrough

1. Initialize a New Agent Project

gradient agent init

This creates a new agent project with:

• main.py - Agent entrypoint with example code
• agents/ - Directory for agent implementations
• tools/ - Directory for custom tools
• config.yaml - Agent configuration
• requirements.txt - Python dependencies

2. Run Locally

gradient agent run

Your agent will be available at http://localhost:8080 with automatic trace capture enabled.

3. Deploy to DigitalOcean

export DIGITALOCEAN_API_TOKEN=your_token_here
gradient agent deploy

4. Evaluate Your Agent

gradient agent evaluate \
--test-case-name "my-evaluation" \
--dataset-file evaluation_dataset.csv \
--categories correctness,context_quality

Usage Examples

Using LangGraph (Automatic Trace Capture)

LangGraph agents automatically capture traces for all nodes and state transitions:

from gradient_adk import entrypoint, RequestContext
from langgraph.graph import StateGraph
from typing import TypedDict

class State(TypedDict):
input: str
output: str

async def llm_call(state: State) -> State:
# This node execution is automatically traced
response = await llm.ainvoke(state["input"])
state["output"] = response
return state

@entrypoint
async def main(input: dict, context: RequestContext):
graph = StateGraph(State)
graph.add_node("llm_call", llm_call)
graph.set_entry_point("llm_call")

graph = graph.compile()
result = await graph.ainvoke({"input": input.get("query")})
return result["output"]

Using Custom Decorators (Any Framework)

For frameworks beyond LangGraph, use trace decorators to capture custom spans:

from gradient_adk import entrypoint, trace_llm, trace_tool, trace_retriever, RequestContext

@trace_retriever("vector_search")
async def search_knowledge_base(query: str):
# Retriever spans capture search/lookup operations
results = await vector_db.search(query)
return results

@trace_llm("generate_response")
async def generate_response(prompt: str):
# LLM spans capture model calls with token usage
response = await llm.generate(prompt)
return response

@trace_tool("calculate")
async def calculate(x: int, y: int):
# Tool spans capture function execution
return x + y

@entrypoint
async def main(input: dict, context: RequestContext):
docs = await search_knowledge_base(input["query"])
result = await calculate(5, 10)
response = await generate_response(f"Context: {docs}")
return response

Streaming Responses

The runtime supports streaming responses with automatic trace capture:

from gradient_adk import entrypoint, RequestContext

@entrypoint
async def main(input: dict, context: RequestContext):
# Stream text chunks
async def generate_chunks():
async for chunk in llm.stream(input["query"]):
yield chunk

CLI Commands

Agent Management

# Initialize new project
gradient agent init

# Configure existing project
gradient agent configure

# Run locally with hot-reload
gradient agent run --dev

# Deploy to DigitalOcean
gradient agent deploy

# View runtime logs
gradient agent logs

# Open traces UI
gradient agent traces

Evaluation

You can evaluate your deployed agent with a number of useful evaluation metrics. See the DigitalOcean docs for details on what belongs in a dataset.

# Run evaluation (interactive)
gradient agent evaluate

# Run evaluation (non-interactive)
gradient agent evaluate \
--test-case-name "my-test" \
--dataset-file data.csv \
--categories correctness,safety_and_security \…