AgentSpec

An AgentSpec is a JSON document that fully defines an AI agent — its persona, policy, and model. The builder assembles this spec from your form inputs and sends it to the ADK runtime on every message.

Top-level fields

Field	Type	Description
name	string	Display name for the agent. Used as the ADK agent identifier.
description	string	Short description (informational only).
tags	string[]	Arbitrary labels for categorisation.
prompt	string	The system prompt. This is the core instruction that shapes all agent behaviour.
policy	PolicyToggles	Behavioural flags appended as instructions to the system prompt.
model_choice	string	Model identifier. Passed for audit; runtime always uses the configured default model.

PolicyToggles

Field	Type	Description
ask_clarifying_questions	boolean	Appends: "Ask up to 2 clarifying questions before answering if the request is ambiguous."
refuse_to_guess	boolean	Appends: "If unsure, say so explicitly and ask for the required information."
output_format	"plain" \| "bullets" \| "json"	plain: prose. bullets: appends bullet-point instruction. json: appends "output valid JSON only".
temperature	number (0–2)	Sampling temperature passed to LiteLLM. Lower = more deterministic.
max_output_tokens	number (1–8192)	Token limit passed to LiteLLM.

Full example

{
  "name": "Pitch Coach",
  "description": "Crafts compelling pitches and slide outlines.",
  "tags": ["pitch", "startup", "writing"],
  "prompt": "You are a brutally effective pitch coach. Enforce structure, challenge vague ideas, and produce concise slide outlines and hook statements. Keep responses tight and actionable.",
  "policy": {
    "ask_clarifying_questions": true,
    "refuse_to_guess": false,
    "output_format": "bullets",
    "temperature": 0.7,
    "max_output_tokens": 512
  },
  "model_choice": "openai/qwen/qwen-2.5-7b-instruct"
}

How policy enforcement works

Policy flags are prompt-level — they append short instruction sentences to the system prompt before the agent runs. The model is not hard-constrained, but a well-written base prompt combined with these flags reliably shapes the output.

ask_clarifying_questions: true

Appends: "Ask up to 2 clarifying questions before answering if the request is ambiguous or under-specified."

refuse_to_guess: true

Appends: "If you are unsure or lack sufficient information, say so explicitly and ask for the required information."

output_format: "json"

Appends: "Output valid JSON only. Do not include any text outside the JSON."

output_format: "bullets"

Appends: "Use bullet points for your response."

API routes

POST/api/run

Forwards the RunRequest to the Python ADK service and returns the agent response.

// Request
{ "spec": AgentSpec, "message": string, "session_id"?: string }

// Response
{ "answer": string, "session_id": string }

// Error
{ "error": string, "detail": string }

Open Builder Browse Examples