From 9bab39729f5ad125a99d85b00816e3cde3d35eb7 Mon Sep 17 00:00:00 2001 From: jshah Date: Tue, 17 Mar 2026 14:53:47 -0500 Subject: [PATCH 1/2] Add ADK template schema design document Initial schema specification for a parameterized template system that will allow CLI, Console, and Genie to create ADK agents from a single schema definition. Includes parameter types, secrets handling, and an example Knowledge Base RAG template manifest. AAPP-929 Made-with: Cursor --- .../cli/templates/template-schema-design.md | 151 ++++++++++++++++++ 1 file changed, 151 insertions(+) create mode 100644 gradient_adk/cli/templates/template-schema-design.md diff --git a/gradient_adk/cli/templates/template-schema-design.md b/gradient_adk/cli/templates/template-schema-design.md new file mode 100644 index 0000000..62dfb16 --- /dev/null +++ b/gradient_adk/cli/templates/template-schema-design.md @@ -0,0 +1,151 @@ +# ADK Template Schema Design + +## Problem + +The current [gradient-adk-templates](https://github.com/digitalocean/gradient-adk-templates) repository contains example agents, not true reusable templates. Users must clone folders and manually modify code or config values to create agents. + +## Goal + +Define a schema-driven template system that allows users to create ADK agents without writing code, consumed consistently by: + +- **ADK CLI** — `gradient agent create --template ` prompts for parameters in the terminal +- **Console UI** — renders the schema as a web form +- **Genie / MCP** — exposes templates as tool parameters + +The schema is a single source of truth: one definition, three surfaces. + +## Schema Location + +The canonical home for template schemas is the **public API schema** (Jenni API). Template definitions and user-provided values will be stored in the database, served via API endpoints. The ADK CLI and Console will consume templates through these endpoints. + +## Template Schema Specification + +### Top-Level Fields + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `schema_version` | string | yes | Schema format version (e.g. `v1`) | +| `template_id` | string | yes | Unique identifier for the template | +| `name` | string | yes | Human-readable template name | +| `description` | string | yes | What this template does | +| `category` | string | yes | Template category (e.g. `rag`, `function-calling`, `multi-agent`) | +| `parameters` | array | yes | User-configurable inputs | +| `secrets` | array | no | Required credentials and environment variables | +| `agent_config` | object | yes | Agent configuration with `${parameter}` substitution | +| `metadata` | object | no | Tags, ownership, and other metadata | + +### Parameter Fields + +Each entry in `parameters` describes one user-facing input: + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `name` | string | yes | Parameter identifier (used in `${...}` substitution) | +| `label` | string | yes | Display label for CLI prompt or form field | +| `type` | string | yes | Input type (see supported types below) | +| `required` | boolean | yes | Whether the user must provide a value | +| `default` | any | no | Default value if user doesn't provide one | +| `description` | string | no | Help text shown to the user | +| `source` | string | no | Dynamic data source (e.g. `serverless_inference_models`) | +| `resource_type` | string | no | For `resource_select` — the DO resource type to list | +| `options` | array | no | For `select` — static list of allowed values | + +### Supported Parameter Types + +| Type | Description | Rendered as | +|------|-------------|-------------| +| `string` | Single-line text input | Text field | +| `textarea` | Multi-line text input | Text area | +| `select` | Pick one from a list | Dropdown | +| `resource_select` | Pick a DigitalOcean resource from the user's account | Resource picker | +| `tool_select` | Select function tools for the agent | Tool picker (TBD — pending clarification on UX) | + +### Secrets + +Templates require credentials that are handled separately from regular parameters — they are masked, stored securely, and never displayed back to the user. + +Each entry in `secrets` declares a required environment variable: + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `env` | string | yes | Environment variable name | +| `label` | string | yes | Display label for the user | +| `description` | string | no | Help text explaining what the secret is for | +| `required` | boolean | yes | Whether the secret must be provided | + +### `agent_config` + +A normalized representation of the agent's configuration, independent of the underlying framework or code. Parameters are injected via `${parameter_name}` substitution. + +Consumers (CLI, Console, renderer) interpret this config to produce the appropriate code and deployment artifacts. The rendering layer is a separate design step. + +## Example: Knowledge Base RAG Template + +```yaml +schema_version: v1 +template_id: knowledge-base-rag +name: Knowledge Base RAG Agent +description: Answer questions using a selected knowledge base. +category: rag + +parameters: + - name: model + label: Model + type: select + required: true + source: serverless_inference_models + description: Model used for inference through Serverless Inference. + + - name: knowledge_base_id + label: Knowledge Base + type: resource_select + resource_type: knowledge_base + required: true + description: The knowledge base this agent will query. + + - name: system_prompt + label: System Prompt + type: textarea + required: false + default: You are a helpful assistant. + description: System instructions for the agent. + + - name: tools + label: Function Tools + type: tool_select + required: false + description: Tools the agent can call during execution. + +secrets: + - env: GRADIENT_MODEL_ACCESS_KEY + label: Gradient Model Access Key + required: true + description: API key for Serverless Inference model access. + - env: DIGITALOCEAN_API_TOKEN + label: DigitalOcean API Token + required: true + description: API token for accessing DigitalOcean resources (e.g. Knowledge Bases). + +agent_config: + model: ${model} + prompt: + system: ${system_prompt} + retrieval: + knowledge_base_id: ${knowledge_base_id} + tools: ${tools} + +metadata: + owner: adk + tags: + - rag + - knowledge-base +``` + +## Open Questions + +- **`tool_select` UX**: Should users select from existing tools on the platform, or define new tools inline (URL, name, description, parameters)? Pending clarification. +- **Validation rules**: Parameters like agent names need constraints (e.g. `^[a-zA-Z0-9_-]+$`, max length). A `validation` field on parameters could support this. +- **Agent-to-Agent (A2A) routing**: Deferred to phase 2. Data gathering on console agent-to-agent usage is in progress to determine if this capability needs to be carried forward. + + + From d85bfc38405ef601fec3e9f3b2d3fcfd762d4a1a Mon Sep 17 00:00:00 2001 From: jshah Date: Tue, 17 Mar 2026 21:54:37 -0500 Subject: [PATCH 2/2] =?UTF-8?q?Schema:=20explicit=20cardinality=20?= =?UTF-8?q?=E2=80=94=20multi-value=20KBs=20and=20tools=20(multiple:=20true?= =?UTF-8?q?)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Made-with: Cursor --- .../cli/templates/template-schema-design.md | 20 ++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/gradient_adk/cli/templates/template-schema-design.md b/gradient_adk/cli/templates/template-schema-design.md index 62dfb16..346947b 100644 --- a/gradient_adk/cli/templates/template-schema-design.md +++ b/gradient_adk/cli/templates/template-schema-design.md @@ -44,6 +44,7 @@ Each entry in `parameters` describes one user-facing input: | `label` | string | yes | Display label for CLI prompt or form field | | `type` | string | yes | Input type (see supported types below) | | `required` | boolean | yes | Whether the user must provide a value | +| `multiple` | boolean | no | If true, the parameter accepts zero, one, or many values (e.g. multiple KBs, multiple tools). Default false. | | `default` | any | no | Default value if user doesn't provide one | | `description` | string | no | Help text shown to the user | | `source` | string | no | Dynamic data source (e.g. `serverless_inference_models`) | @@ -81,11 +82,13 @@ Consumers (CLI, Console, renderer) interpret this config to produce the appropri ## Example: Knowledge Base RAG Template + + ```yaml schema_version: v1 template_id: knowledge-base-rag name: Knowledge Base RAG Agent -description: Answer questions using a selected knowledge base. +description: Answer questions using selected knowledge bases. category: rag parameters: @@ -96,12 +99,13 @@ parameters: source: serverless_inference_models description: Model used for inference through Serverless Inference. - - name: knowledge_base_id - label: Knowledge Base + - name: knowledge_base_ids + label: Knowledge Bases type: resource_select resource_type: knowledge_base - required: true - description: The knowledge base this agent will query. + multiple: true + required: false + description: Knowledge bases this agent can query. - name: system_prompt label: System Prompt @@ -113,6 +117,7 @@ parameters: - name: tools label: Function Tools type: tool_select + multiple: true required: false description: Tools the agent can call during execution. @@ -121,17 +126,18 @@ secrets: label: Gradient Model Access Key required: true description: API key for Serverless Inference model access. + - env: DIGITALOCEAN_API_TOKEN label: DigitalOcean API Token required: true - description: API token for accessing DigitalOcean resources (e.g. Knowledge Bases). + description: API token for accessing DigitalOcean resources. agent_config: model: ${model} prompt: system: ${system_prompt} retrieval: - knowledge_base_id: ${knowledge_base_id} + knowledge_base_ids: ${knowledge_base_ids} tools: ${tools} metadata: