Overview Agents on the Shinzo Platform run in isolated Kubernetes environments with persistent storage, MCP server connectivity, and webhook support. Each agent operates as an independent deployment with its own filesystem, message queue, and configurable toolset.
You can create agents with minimal configuration and progressively add capabilities as your use case evolves.
Prerequisites Before creating an agent, make sure you have:
A Shinzo Platform account with the AI Agents feature enabled
An authentication token (passed via Authorization: Bearer <token> header)
An Anthropic API key (either stored in your account settings or provided per-agent)
Quick Start Create a basic agent with a single API call:
curl -X POST https://api.app.shinzo.ai/v1/agent/create \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "my-first-agent", "configuration": {} }'
This creates an agent with default settings: 1 GiB of persistent storage, a 1-hour task timeout, and hierarchical memory. The agent uses your stored Anthropic API key if you do not provide one explicitly.
Configuration Reference Top-Level Parameters Parameter Type Required Default Description namestring ✅ — Agent name, 1-100 characters descriptionstring ❌ — Purpose description, max 500 characters pvc_sizestring ❌ "1Gi"Persistent volume size for agent workspace anthropic_api_keystring ❌ — Anthropic API key. If omitted, your stored account key is used system_promptstring ❌ — Custom system prompt for the agent system_prompt_typeenum ❌ "append""replace" overwrites the default prompt; "append" adds to itconfigurationobject ✅ — Agent configuration object (see below) initial_filesarray ❌ — Files to create in the agent workspace on startup
Configuration Object The configuration object controls runtime behavior, tooling, memory, and notifications.
Parameter Type Default Description timeout_secondsnumber 3600Maximum time in seconds for a single task modelstring — Model name to use for the agent. Supported models: claude-3-7-sonnet-latest, claude-haiku-4-5, claude-opus-4-0, claude-opus-4-1, claude-opus-4-5, claude-opus-4-6, claude-sonnet-4-0, claude-sonnet-4-5, claude-sonnet-4-6 mcp_serversobject — MCP server configurations keyed by server name memory_configobject — Memory type, size, and persistence settings webhooksobject — URLs for event notifications compactionobject — Context compaction settings custom_envobject — Key-value pairs injected as environment variables
Memory Configuration Parameter Type Default Description typeenum "hierarchical""hierarchical" or "flat" memory structuremax_size_mbnumber 1024Maximum memory size in megabytes persistenceenum "persistent""persistent" retains memory across restarts; "ephemeral" clears on restart
Webhooks Parameter Type Description message_completestring URL called when the agent finishes processing a message message_failedstring URL called when message processing fails agent_errorstring URL called when the agent encounters an error
Compaction Compaction automatically summarizes long conversation histories to keep context within model limits.
Parameter Type Default Description enabledboolean trueEnable or disable automatic compaction modelstring "claude-haiku-4-5-20251001"Model used for summarization threshold_triggernumber 120000Input token count that triggers compaction
Initial Files You can pre-populate the agent workspace with files at creation time. Each file entry accepts:
Parameter Type Required Description pathstring ✅ File path in the agent workspace contentstring ✅ File content encodingenum ❌ "utf-8" (default) or "base64" for binary content
Example Configurations Development Agent A lightweight agent for testing and iteration:
{ "name" : "dev-assistant" , "description" : "Development and testing agent" , "pvc_size" : "1Gi" , "system_prompt" : "You are a development assistant. Be concise." , "system_prompt_type" : "append" , "configuration" : { "timeout_seconds" : 1800 , "memory_config" : { "type" : "flat" , "max_size_mb" : 256 , "persistence" : "ephemeral" } } }
Production Agent A fully configured agent with webhooks, MCP servers, and persistent memory:
{ "name" : "production-agent" , "description" : "Customer-facing production agent" , "pvc_size" : "5Gi" , "configuration" : { "timeout_seconds" : 3600 , "memory_config" : { "type" : "hierarchical" , "max_size_mb" : 1024 , "persistence" : "persistent" }, "webhooks" : { "message_complete" : "https://your-app.com/webhooks/complete" , "message_failed" : "https://your-app.com/webhooks/failed" , "agent_error" : "https://your-app.com/webhooks/error" }, "compaction" : { "enabled" : true , "threshold_trigger" : 100000 }, "custom_env" : { "APP_ENV" : "production" , "LOG_LEVEL" : "info" } }, "initial_files" : [ { "path" : "config/settings.json" , "content" : "{ \" mode \" : \" production \" }" } ] }
Deployment Patterns Async Processing Create agents that process tasks in the background and notify your application via webhooks when complete. Use the message_complete webhook to receive results without polling.
Interactive Use the API or Discord channel to have real-time conversations with your agent. The collect queue mode batches incoming messages while the agent is busy, so nothing is lost.
Integration Connect agents to external services through MCP servers. Register tools like GitHub, databases, or custom APIs, then grant your agent access to use them autonomously.
Agent States Agents transition through the following states during their lifecycle:
State Description activeAgent is running and processing messages pausedAgent is temporarily suspended; messages queue but are not processed stoppedAgent is fully stopped and not accepting messages errorAgent encountered a fatal error and requires attention
State Transitions From To How activepausedCall POST /v1/agent/pause/:id pausedactiveCall POST /v1/agent/resume/:id activestoppedDelete the agent activeerrorAutomatic on fatal error erroractiveResolve the issue and resume
Updating Agents Update an existing agent’s configuration, metadata, or files with POST /v1/agent/update/:id:
curl -X POST https://api.app.shinzo.ai/v1/agent/update/AGENT_ID \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "updated-agent-name", "description": "Updated description", "system_prompt": "New instructions for the agent.", "configuration": { "timeout_seconds": 7200 }, "files": { "add": [ { "path": "new-file.txt", "content": "Hello" } ], "update": [ { "path": "config/settings.json", "content": "{\"mode\": \"debug\"}" } ], "delete": ["old-file.txt"] } }'
You can update any combination of fields. Only the fields you include in the request body are modified.
Deleting Agents Delete an agent and all associated data with POST /v1/agent/delete/:id:
curl -X POST https://api.app.shinzo.ai/v1/agent/delete/AGENT_ID \ -H "Authorization: Bearer YOUR_TOKEN"
Deleting an agent permanently removes its workspace, message history, and all associated data. This action cannot be undone.
Best Practices
Start small. Begin with minimal configuration and add capabilities as you understand your agent’s needs.Use ephemeral memory for development. Switch to persistent memory only when you need state across restarts.Set appropriate timeouts. Avoid excessively long timeouts that could waste resources on stuck tasks.Configure webhooks for production. Webhooks let you react to agent events without polling.Store API keys at the account level. This avoids embedding keys in every agent creation request.Use system_prompt_type: "append" unless you have a specific reason to replace the default prompt entirely.Pre-populate workspaces with initial_files to give agents the context they need from the start.
Next Steps
Agent Messaging Send messages to your agents and manage conversations.
MCP Server Management Connect external tools and services to your agents.
Filesystem Management Manage files in agent workspaces programmatically.
