> ## Documentation Index > Fetch the complete documentation index at: https://docs.shinzo.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create Agent > Deploy a new AI agent on the Shinzo Platform. ## Authentication Requires JWT token or Platform API key via `Authorization: Bearer ` header. Agent name (1-100 characters) Agent description (max 500 characters) Persistent volume size (e.g., "1Gi", "5Gi") Anthropic API key for the agent. If omitted, your stored key is used Initial output token balance (default: 1M tokens ≈ \$15 at Sonnet pricing) Custom system prompt for the agent How to apply the system prompt: `replace` or `append` Session lifecycle mode: `ephemeral` (fresh session per trigger) or `persistent` (continuous context) Idle grace period (ms) before pod scales to zero. Min: 300000 (5 min). `null` = never scale down. Discord bot token for per-agent Discord integration (max 200 chars) Slack credentials: `{ bot_token, signing_secret, app_token }` Telegram bot token for per-agent Telegram integration (max 200 chars) Agent configuration options (see below) Files to create in the agent workspace on deploy ## Configuration Object | Field | Type | Default | Description | | ----------------------------- | ------ | -------- | ------------------------------------------------------------------------------ | | `timeout_seconds` | number | `3600` | Task timeout in seconds | | `model` | string | - | Model name to use (overrides default) | | `mcp_servers` | object | `{}` | MCP server configurations | | `memory_config` | object | - | Memory configuration | | `compaction` | object | - | Context compaction configuration | | `custom_env` | object | - | Custom environment variables (max 20 entries, string values only) | | `unread_reminder_interval_ms` | number | `120000` | How often (ms) to remind agent about unread messages. Min: 10000, Max: 3600000 | | `hook_messages` | object | - | Custom lifecycle prompt templates | ### Memory Configuration | Field | Type | Default | Description | | ------------- | ------ | -------------- | ------------------------------------------------ | | `type` | string | `hierarchical` | Memory type (`hierarchical` or `flat`) | | `max_size_mb` | number | `1024` | Maximum memory size in MB | | `persistence` | string | `persistent` | Memory persistence (`ephemeral` or `persistent`) | ### Compaction | Field | Type | Default | Description | | ------------------- | ------- | --------------------------- | ---------------------------------------------------------- | | `enabled` | boolean | `true` | Enable context compaction | | `threshold_trigger` | number | `120000` | Input token threshold to trigger compaction (50000-180000) | | `model` | string | `claude-haiku-4-5-20251001` | Model used for summarization | | `instructions` | string | - | Custom compaction prompt (max 2000 chars) | ### Hook Messages Custom prompts for agent lifecycle events. Each hook supports template variables and has a 5000 character limit. | Hook | Description | Template Variables | | -------------------------- | --------------------------------------------- | -------------------------------------------------------------- | | `channel_message_received` | Prompt when new messages arrive | `{{message_count}}`, `{{channel_sections}}`, `{{message_ids}}` | | `unread_message_reminder` | Periodic reminder for unread messages | `{{message_count}}` | | `interrupt` | Prompt when messages interrupt active session | `{{message_count}}`, `{{channel_sections}}` | | `session_restart` | Message injected when agent pod restarts | - | | `compaction_summarize` | Instructions for compaction summarization | `{{transcript}}` | | `compaction_continuation` | Prompt after compaction to continue work | `{{summary}}` | | `session_resume_fallback` | Fallback when resuming without user input | - | ### Custom Environment Variables * Max 20 key-value pairs * Keys and values must be strings * Key max length: 100 chars * Value max length: 10000 chars * Cannot override reserved env vars: `AGENT_UUID`, `DATABASE_URL`, `HOME`, `WORKSPACE_PATH`, `ANTHROPIC_BASE_URL`, `ANTHROPIC_CUSTOM_HEADERS`, `ANTHROPIC_API_KEY`, `SHINZO_API_URL`, `SHINZO_INTERNAL_API_URL`, `SHINZO_API_KEY` ### Slack Bot Token Required fields when providing Slack credentials: | Field | Description | | ---------------- | ------------------------------------------------ | | `bot_token` | Slack bot token (xoxb-...) | | `signing_secret` | Slack signing secret for webhook verification | | `app_token` | Slack app-level token (xapp-...) for Socket Mode | ### Initial Files | Field | Type | Required | Description | | ---------- | ------ | -------- | ----------------------------------------------- | | `path` | string | ✅ | File path in the agent workspace | | `content` | string | ✅ | File content | | `encoding` | string | ❌ | Content encoding: `utf-8` (default) or `base64` | ## Session Mode Controls how an agent handles new triggers with respect to the current session: | Mode | Behavior | | --------------------- | ------------------------------------------------------------------------------------------------ | | `ephemeral` (default) | Each trigger starts a fresh session. Gives clean per-run analytics and discrete session history. | | `persistent` | New messages append to the current session, maintaining continuous context across interactions. | **Notes:** * Compaction and crash recovery ALWAYS resume the existing session regardless of mode * Only new triggers (messages, schedules, webhooks) respect this setting * In `ephemeral` mode with `interrupt` queue mode: immediately ends current session * In `ephemeral` mode with `collect` queue mode: waits for current turn to end, then starts new session ## Example Request ```bash theme={null} curl -X POST https://api.app.shinzo.ai/v1/agent/create \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "name": "code-review-agent", "description": "Agent for automated code reviews", "pvc_size": "5Gi", "system_prompt": "You are a senior code reviewer. Be thorough and constructive.", "system_prompt_type": "append", "session_mode": "ephemeral", "output_token_balance": 5000000, "configuration": { "timeout_seconds": 1800, "unread_reminder_interval_ms": 300000, "compaction": { "enabled": true, "threshold_trigger": 100000, "instructions": "Focus on preserving code context and reviewer comments." }, "custom_env": { "REVIEW_STYLE": "thorough", "MAX_FILE_SIZE": "100000" } }, "initial_files": [ { "path": "config.json", "content": "{\"review_style\": \"thorough\"}" } ] }' ``` ## Example Response ```json theme={null} { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "code-review-agent", "description": "Agent for automated code reviews", "status": "active", "session_mode": "ephemeral", "output_token_balance": 5000000, "created_at": "2026-03-09T10:00:00Z", "updated_at": "2026-03-09T10:00:00Z", "configuration": { "timeout_seconds": 1800, "unread_reminder_interval_ms": 300000, "memory_config": { "type": "hierarchical", "max_size_mb": 1024, "persistence": "persistent" }, "compaction": { "enabled": true, "model": "claude-haiku-4-5-20251001", "threshold_trigger": 100000, "instructions": "Focus on preserving code context and reviewer comments." } }, "system_prompt": "You are a senior code reviewer. Be thorough and constructive.", "system_prompt_type": "append", "mcp_servers": [], "filesystem_summary": { "total_files": 1, "total_size_mb": 0.01, "last_modified": "2026-03-09T10:00:00Z" } } ``` ## Status Codes | Code | Description | | ----- | ------------------------------------------------ | | `201` | Agent created successfully | | `400` | Invalid request (validation error) | | `401` | Unauthorized - invalid or missing authentication | | `403` | AI Agents feature not enabled for your account |