The agent.json Specification

The agent.json file is the complete blueprint for your agent. You bookmark this page and return to it constantly.

Complete Example

Here is a fully loaded agent.json with every possible field included, set to sensible defaults:

{
  "name": "data-analyst",
  "description": "Analyses CSV files and generates visual insights.",
  "llm": {
    "provider": "openai",
    "model": "gpt-4o",
    "key_ref": "OPENAI_API_KEY",
    "temperature": 0.2,
    "max_tokens": 4096,
    "top_p": 0.95
  },
  "tools": ["python_exec", "file_read", "web_search"],
  "config": {
    "max_steps": 15,
    "timeout_seconds": 300,
    "system_prompt": "You are an expert data analyst. Use Python to read and plot data. Return markdown summaries.",
    "memory_type": "ephemeral",
    "retry_limit": 3,
    "security_level": "medium"
  },
  "env": {
    "TARGET_DB": "reporting_db",
    "API_URL": "https://api.internal.corp"
  }
}

Try the JSON Schema Validator
In the dashboard, pasting your agent JSON triggers a live validation engine. Here in the docs, ensure your JSON adheres strictly to the tables below.

Top-level Fields

Field	Type	Required	Default	Description	Example
name	string	Yes	-	URL-safe identifier. Max 64 chars, lowercase, hyphens allowed. Becomes your API slug.	"customer-support"
description	string	No	""	A human-readable description shown in the dashboard. Max 500 chars.	"Answers FAQ using search."
llm	object	Yes	-	Configuration for the AI model behind this agent.	(See llm section below)
tools	array	No	[]	List of built-in or custom tool names the agent can invoke.	["web_search"]
config	object	Yes	-	Runtime execution boundaries for the state machine.	(See config section below)
env	object	No	{}	Static environment variables exposed to the agent sandbox.	{"DEBUG": "true"}

---

The llm Object

Field	Type	Required	Default	Description	Example
provider	string	Yes	-	The AI provider. Must be openai, google, anthropic, groq, nvidia, mistral, or ollama.	"anthropic"
model	string	Yes	-	The specific model version for the provider.	"claude-sonnet-4-20250514"
key_ref	string	No	-	The name of the environment variable containing your BYOK API Key.	"ANTHROPIC_API_KEY"
temperature	number	No	0.6	Controls randomness (0.0 to 1.0). Lower is more deterministic.	0.1
max_tokens	number	No	16384	Maximum number of output tokens.	8192
top_p	number	No	0.95	Nucleus sampling probability.	0.9

---

The tools Array

An array of strings where each string is the exact name of a tool mounted to the platform's Tool Gateway.

Example Built-in Tools:

• web_search (Medium security)
• python_exec (High/Critical depending on network settings)
• http_request (High security)
• sql_query (Custom connection required)

For the complete list, read the Built-in Tools Reference.

---

The config Object

Field	Type	Required	Default	Description
system_prompt	string	Yes	-	The persona and core instructions for the agent. This fundamentally shapes behaviour.
max_steps	number	No	8	Maximum loops (THINK-ACT-OBSERVE) permitted before circuit breaker triggers. (Max 50)
timeout_seconds	number	No	300	Absolute wall-clock time limit for the entire task.
security_level	string	No	"medium"	Defines sandbox rigour. low, medium, high, or critical.
memory_type	string	No	"ephemeral"	ephemeral for stateless runs, persistent retains memory across sessions.
retry_limit	number	No	3	Attempts to retry failed tool calls or structured output parsing before failing task.

---

Migration Guide

If deploying files crafted for Savine v1 on the v2 endpoints:

• engine_version is deprecated. The runtime automatically uses the V2 AgentGraphEngine.
• LLM keys must now be stored via savine config set and referenced via key_ref. Embedding keys directly in JSON is explicitly blocked by the platform validator.