> ## 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. # Update Agent > Update an existing agent's configuration. ## Authentication Requires JWT token or Platform API key via `Authorization: Bearer ` header. Agent UUID New agent name (1-100 characters) New description (max 500 characters) New persistent volume size (e.g., "2Gi", "10Gi") New system prompt How to apply the system prompt: `replace` or `append` Set agent output token balance directly Session lifecycle mode: `ephemeral` or `persistent` Idle grace period (ms) before pod scales to zero. Min: 300000 (5 min). `null` = never scale down. Discord bot token (max 200 chars). Set to `null` to clear. Slack credentials: `{ bot_token, signing_secret, app_token }`. Set to `null` to clear. Telegram bot token (max 200 chars). Set to `null` to clear. Configuration updates (partial update supported) File operations to perform on the agent workspace ## Configuration Object All configuration fields are optional. Only provided fields will be updated. | Field | Type | Description | | ----------------------------- | ------ | -------------------------------------------------------------------- | | `timeout_seconds` | number | New task timeout in seconds | | `model` | string | New model name to use | | `mcp_servers` | object | Updated MCP server configurations | | `compaction` | object | Updated compaction configuration | | `custom_env` | object | Updated custom environment variables (max 20 entries) | | `unread_reminder_interval_ms` | number | How often (ms) to remind agent about unread messages (10000-3600000) | | `hook_messages` | object | Updated lifecycle prompt templates | ### Compaction Updates | Field | Type | Description | | ------------------- | ------- | ----------------------------------------- | | `enabled` | boolean | Enable/disable context compaction | | `threshold_trigger` | number | Input token threshold (50000-180000) | | `model` | string | Model for summarization | | `instructions` | string | Custom compaction prompt (max 2000 chars) | ### Hook Messages Updates Each hook can be updated independently: | Hook | Description | | -------------------------- | --------------------------------------------- | | `channel_message_received` | Prompt when new messages arrive | | `unread_message_reminder` | Periodic reminder for unread messages | | `interrupt` | Prompt when messages interrupt active session | | `session_restart` | Message injected when agent pod restarts | | `compaction_summarize` | Instructions for compaction summarization | | `compaction_continuation` | Prompt after compaction to continue work | | `session_resume_fallback` | Fallback when resuming without user input | ## File Operations The `files` object allows you to add, update, or delete files in the agent workspace within a single request. | Field | Type | Description | | -------- | ----- | ---------------------------------------------------------------------- | | `add` | array | Files to add (each with `path`, `content`, and optional `encoding`) | | `update` | array | Files to update (each with `path`, `content`, and optional `encoding`) | | `delete` | array | File paths to delete (array of strings) | ### File Object | 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` | ## Example: Update Configuration ```bash theme={null} curl -X POST https://api.app.shinzo.ai/v1/agent/update/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "description": "Updated agent for thorough code reviews", "session_mode": "persistent", "configuration": { "timeout_seconds": 3600, "unread_reminder_interval_ms": 300000, "compaction": { "enabled": true, "threshold_trigger": 150000 } } }' ``` ## Example: Update Files and Configuration ```bash theme={null} curl -X POST https://api.app.shinzo.ai/v1/agent/update/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "configuration": { "custom_env": { "REVIEW_STYLE": "detailed", "MAX_FILE_SIZE": "200000" } }, "files": { "add": [ { "path": "templates/review.md", "content": "# Review Template\n\n## Summary\n..." } ], "update": [ { "path": "config.json", "content": "{\"review_style\": \"detailed\"}" } ], "delete": ["old-config.json", "deprecated/old-template.md"] } }' ``` ## Example: Configure Bot Tokens ```bash theme={null} curl -X POST https://api.app.shinzo.ai/v1/agent/update/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "telegram_bot_token": "1234567890:ABCdefGHIjklMNOpqrsTUVwxyz", "slack_bot_token": { "bot_token": "xoxb-1234567890-abcdefghijk", "signing_secret": "abc123def456", "app_token": "xapp-1-A01234BCDEF-567890" } }' ``` ## Example Response ```json theme={null} { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "code-review-agent", "description": "Updated agent for thorough code reviews", "status": "active", "session_mode": "persistent", "output_token_balance": 4850000, "created_at": "2026-03-01T10:00:00Z", "updated_at": "2026-03-09T14:30:00Z", "configuration": { "timeout_seconds": 3600, "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": 150000 } }, "system_prompt": "You are a senior code reviewer.", "system_prompt_type": "append", "mcp_servers": [], "filesystem_summary": { "total_files": 16, "total_size_mb": 2.5, "last_modified": "2026-03-09T14:30:00Z" } } ``` ## Status Codes | Code | Description | | ----- | ------------------------------------------------ | | `200` | Agent updated successfully | | `400` | Invalid request (validation error) | | `401` | Unauthorized - invalid or missing authentication | | `403` | AI Agents feature not enabled for your account | | `404` | Agent not found | ## Notes * **Partial updates**: Only provide the fields you want to change * **Bot tokens**: Setting a bot token to `null` clears the configuration but doesn't unlink existing channel bindings * **PVC size**: Can only be increased, not decreased * **Configuration merging**: Configuration updates are merged with existing settings (not replaced entirely) * **File operations**: All file operations in a single request are applied atomically