Savine Documentation

Quickstart ​

Get from zero to a running agent API endpoint in under 5 minutes. No infrastructure to provision, no complex Python frameworks to learn.

Prerequisites

Before starting, you need:

  1. A Savine account
  2. The Savine CLI installed: npm i -g @agentcloud/cli
  3. An API key from a supported LLM provider (e.g., OpenAI, Google, Anthropic)

Step 1: Create your agent.json ​

Create a new directory and create an agent.json file. This file is the entire definition of your agent.

json
{
  "name": "my-first-agent",
  // A simple description for your dashboard
  "description": "A simple research agent",
  "llm": {
    // The provider to use
    "provider": "google",
    // The specific model version
    "model": "gemini-2.0-flash",
    // Tell Savine to look for this environment variable for your key
    "key_ref": "GOOGLE_API_KEY"
  },
  // The tools this agent is allowed to use
  "tools": ["web_search"],
  "config": {
    // Failsafe limit for execution loops
    "max_steps": 10,
    // Failsafe time limit
    "timeout_seconds": 120,
    // The core instructions defining the agent's behaviour
    "system_prompt": "You are a helpful research assistant."
  }
}

Step 2: Set your API key ​

You don't put your API key in agent.json. Instead, securely add it via the CLI so it is stored encrypted on the platform.

bash
savine config set GOOGLE_API_KEY="AIzaSyYourKeyHere..."
powershell
savine config set GOOGLE_API_KEY="AIzaSyYourKeyHere..."

Step 3: Deploy ​

Deploy your agent to the Savine cloud:

bash
$ savine deploy

🚀 Deploying my-first-agent to Savine...
✓ Validating agent.json
✓ Creating agent version 1
✓ Provisioning sandbox
✓ Agent is READY

Live Endpoint: https://api.savine.dev/v1/systems/my-first-agent/run

Step 4: Run your first task ​

Your agent is now live and waiting for tasks. Call its API endpoint to give it a job.

bash
curl -X POST https://api.savine.dev/v1/systems/my-first-agent/run \
  -H "Authorization: Bearer YOUR_SAVINE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Summarise the latest news about solid state batteries."
  }'

The system will execute asynchronously. When you query the task status, you'll receive a response like this:

json
{
  "id": "tsk_29j4k2x98y",
  "status": "COMPLETED",
  "agent_id": "my-first-agent",
  "output": "Based on my research, the latest news on solid-state batteries...",
  "duration_ms": 4200,
  "metrics": {
    "total_tokens": 1450,
    "cost_usd": 0.0004
  }
}

Step 5: View the execution trace ​

Log into your dashboard at savine.in, go to Observability > Traces, and click on your task.

You will see the exact steps your agent took:

  1. THINK: Decided to search the web for "solid state batteries 2024 news".
  2. ACT: Called web_search.
  3. OBSERVE: Read the search results.
  4. THINK: Synthesized the information into a summary.

What just happened? ​

When you ran savine deploy:

  • We parsed and validated your configuration.
  • We packaged an isolated gVisor container for your agent.
  • We provisioned routing and rate-limiting rules.
  • We set up observability pipelines for logs, tokens, and traces.

Your agent is now a fully managed cloud primitive.

Next Steps ​