)
The DigitalOcean Gradient™ 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 Gradient™ ADK with one simple aim: bring your agent code, and we handle the rest—bringing the simplicity you love about DigitalOcean to AI agents.
-
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 own Gradient™ AI 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.
- 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
- 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
@tracedecorators - Streaming Support: Full support for streaming responses with trace capture
- Production Ready: Designed for seamless deployment to DigitalOcean infrastructure
pip install gradient-adk🎥 Watch the Getting Started Video for a complete walkthrough
gradient agent initThis creates a new agent project with:
main.py- Agent entrypoint with example codeagents/- Directory for agent implementationstools/- Directory for custom toolsconfig.yaml- Agent configurationrequirements.txt- Python dependencies
gradient agent runYour agent will be available at http://localhost:8080 with automatic trace capture enabled.
export DIGITALOCEAN_API_TOKEN=your_token_here
gradient agent deploygradient agent evaluate \
--test-case-name "my-evaluation" \
--dataset-file evaluation_dataset.csv \
--categories correctness,context_qualityLangGraph 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"]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 responseThe 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# 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 tracesYou 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 \
--star-metric-name "Correctness (general hallucinations)" \
--success-threshold 80.0The ADK provides comprehensive tracing capabilities to capture and analyze your agent's execution. You can use decorators for wrapping functions or programmatic functions for manual span creation.
- LangGraph Nodes: All node executions, state transitions, and edges (including LLM calls, tool calls, and DigitalOcean Knowledge Base calls)
- HTTP Requests: Request/response payloads for LLM API calls
- Errors: Full exception details and stack traces
- Streaming Responses: Individual chunks and aggregated outputs
Use decorators to automatically trace function executions:
from gradient_adk import entrypoint, trace_llm, trace_tool, trace_retriever, RequestContext
@trace_llm("model_call")
async def call_model(prompt: str):
"""LLM spans capture model calls with token usage."""
response = await llm.generate(prompt)
return response
@trace_tool("calculator")
async def calculate(x: int, y: int):
"""Tool spans capture function/tool execution."""
return x + y
@trace_retriever("vector_search")
async def search_docs(query: str):
"""Retriever spans capture search/lookup operations."""
results = await vector_db.search(query)
return results
@entrypoint
async def main(input: dict, context: RequestContext):
docs = await search_docs(input["query"])
result = await calculate(5, 10)
response = await call_model(f"Context: {docs}")
return responseFor more control over span creation, use the programmatic functions. These are useful when you can't use decorators or need to add spans for code you don't control:
from gradient_adk import entrypoint, add_llm_span, add_tool_span, add_agent_span, RequestContext
@entrypoint
async def main(input: dict, context: RequestContext):
# Add an LLM span with detailed metadata
response = await external_llm_call(input["query"])
add_llm_span(
name="external_llm_call",
input={"messages": [{"role": "user", "content": input["query"]}]},
output={"response": response},
model="gpt-4",
num_input_tokens=100,
num_output_tokens=50,
temperature=0.7,
)
# Add a tool span
tool_result = await run_tool(input["data"])
add_tool_span(
name="data_processor",
input={"data": input["data"]},
output={"result": tool_result},
tool_call_id="call_abc123",
metadata={"tool_version": "1.0"},
)
# Add an agent span for sub-agent calls
agent_result = await call_sub_agent(input["task"])
add_agent_span(
name="research_agent",
input={"task": input["task"]},
output={"result": agent_result},
metadata={"agent_type": "research"},
tags=["sub-agent", "research"],
)
return {"response": response, "tool_result": tool_result, "agent_result": agent_result}| Function | Description | Key Optional Fields |
|---|---|---|
add_llm_span() |
Record LLM/model calls | model, temperature, num_input_tokens, num_output_tokens, total_tokens, tools, time_to_first_token_ns |
add_tool_span() |
Record tool/function executions | tool_call_id |
add_agent_span() |
Record agent/sub-agent executions | — |
Common optional fields for all span functions: duration_ns, metadata, tags, status_code
Traces are:
- Automatically sent to DigitalOcean's Gradient Platform
- Available in real-time through the web console
- Accessible via
gradient agent tracescommand
# Required for deployment and evaluations
export DIGITALOCEAN_API_TOKEN=your_do_api_token
# Required for Gradient serverless inference (if using)
export GRADIENT_MODEL_ACCESS_KEY=your_gradient_key
# Optional: Enable verbose trace logging
export GRADIENT_VERBOSE=1
# Optional: A2A protocol — base URL for AgentCard discovery
export A2A_BASE_URL=https://your-app.ondigitalocean.appmy-agent/
├── main.py # Agent entrypoint with @entrypoint decorator
├── .gradient/
│ ├── agent.yml # Agent configuration (auto-generated)
│ └── .gradientignore # Controls which files are excluded from deployment
├── requirements.txt # Python dependencies
├── .env # Environment variables (not committed)
├── agents/ # Agent implementations
│ └── my_agent.py
└── tools/ # Custom tools
└── my_tool.py
When you deploy with gradient agent deploy, the CLI zips your project directory and uploads it. The file .gradient/.gradientignore controls which files and directories are excluded from that zip. It is created automatically with sensible defaults when you run gradient agent init.
The syntax is one pattern per line:
# Comments start with #
dir_name/ # Exclude directories with this name anywhere in the tree
*.ext # Exclude files matching this extension
exact_name # Exclude exact file or directory name matches
The default .gradientignore excludes virtual environments (env/, venv/, .venv/), Python caches (__pycache__/, *.pyc), version control (.git/), build artifacts (dist/, build/, *.egg-info), test caches (.pytest_cache/, .mypy_cache/), and zip files (*.zip).
To customize, edit .gradient/.gradientignore directly. For example, to also exclude a local test data directory:
# ... existing patterns ...
test_data/
scripts/
This is intentionally separate from .gitignore because that files you track in git (like setup scripts or test fixtures) may not be needed in your deployed agent.
The Gradient ADK is designed to work with any Python-based AI agent framework:
- ✅ LangGraph - Automatic trace capture (zero configuration)
- ✅ LangChain - Use trace decorators (
@trace_llm,@trace_tool,@trace_retriever) for custom spans - ✅ CrewAI - Use trace decorators for agent and task execution
- ✅ Custom Frameworks - Use trace decorators for any function
The Gradient ADK supports the Agent-to-Agent (A2A) protocol v0.3.0, enabling any @entrypoint agent to communicate with A2A-compatible clients. Install with pip install gradient-adk[a2a].
Any @entrypoint agent can be exposed as an A2A server with no code changes:
from gradient_adk import entrypoint
from gradient_adk.a2a import create_a2a_server
@entrypoint
async def my_agent(data: dict, context) -> dict:
return {"output": f"You said: {data.get('prompt', '')}"}
app = create_a2a_server(my_agent)Run with uvicorn my_module:app --host 0.0.0.0 --port 8000. The agent is discoverable at /.well-known/agent-card.json and accepts JSON-RPC calls (message/send, tasks/get, tasks/cancel).
A2A uses a discover-then-call pattern over JSON-RPC. Here is the full client-server flow:
-
Discover — The client fetches the AgentCard at
GET /.well-known/agent-card.json. This returns the agent's name, transport URL, supported capabilities, and input/output modes. The client uses this to decide whether it can talk to this agent. -
Send — The client sends a message via
POST /with JSON-RPC methodmessage/send. The server validates the message (text-only in MVP), creates a task, executes the agent, and returns aTaskobject with ataskIdand current status. -
Poll — The client checks task progress via
tasks/getwith thetaskId. Once the task reaches a terminal state (completed,failed, orcanceled), the response includes the agent's output in the task artifacts. ThehistoryLengthparameter controls how much conversation history is returned. -
Cancel (optional) — The client can request cancellation via
tasks/cancel. This is best-effort and idempotent — if the agent already finished, the cancel is a no-op.
Client Server
│ │
├── GET /.well-known/agent-card.json ──► AgentCard (capabilities, URL)
│ │
├── POST / message/send ──────────────► Create task → Execute agent
│◄─────────────────── Task {id, status} │
│ │
├── POST / tasks/get ─────────────────► Return task state + artifacts
│◄──────────── Task {id, status, result} │
│ │
└── POST / tasks/cancel ──────────────► Best-effort cancellation
When you deploy to App Platform, the public URL is assigned after deployment. The A2A server needs this URL for the AgentCard so that clients know where to send requests. The workflow is:
- Deploy your agent to App Platform as usual with
gradient agent deploy - Get your app's public URL from the App Platform dashboard (e.g.,
https://your-agent-abc123.ondigitalocean.app) - Set the environment variable in your app's settings:
A2A_BASE_URL=https://your-agent-abc123.ondigitalocean.app
- Redeploy — the agent restarts and the AgentCard now advertises the correct public URL
For local development, no configuration is needed — it defaults to http://localhost:8000.
Once deployed, any A2A-compatible agent or client can call your agent:
import httpx
# Discover the remote agent
card = httpx.get("https://your-agent.ondigitalocean.app/.well-known/agent-card.json").json()
rpc_url = card["url"]
# Send a message
response = httpx.post(rpc_url, json={
"jsonrpc": "2.0", "id": "1",
"method": "message/send",
"params": {
"message": {
"role": "user",
"parts": [{"kind": "text", "text": "Hello from another agent!"}],
"message_id": "msg-1",
"kind": "message",
}
},
})
task = response.json()["result"]
# Poll until done
result = httpx.post(rpc_url, json={
"jsonrpc": "2.0", "id": "2",
"method": "tasks/get",
"params": {"id": task["id"]},
}).json()["result"]See examples/a2a/client.py for a complete async client with discovery, send, poll, and cancel.
message/send: Send a message to the agent, creates or continues a tasktasks/get: Poll task state and retrieve results (supportshistoryLength)tasks/cancel: Best-effort task cancellation (idempotent)- Agent Discovery:
GET /.well-known/agent-card.jsonfor capabilities and transport URL
Text-only input/output (text/plain) in the current release. Streaming, push notifications, and authenticated extended cards are explicitly disabled via AgentCard capability flags.
- Templates/Examples: https://github.com/digitalocean/gradient-adk-templates
- Gradient™ AI Platform: https://www.digitalocean.com/products/gradient/platform
- Documentation: https://docs.digitalocean.com/products/gradient-ai-platform/how-to/build-agents-using-adk/
- API Reference: https://docs.digitalocean.com/reference/api
- Community: DigitalOcean Community Forums
Licensed under the Apache License 2.0. See LICENSE