Advanced (JSON) Mode

The agent editor has two modes, toggled by a pair of icon-only buttons in the top-right of the editor header:

• Basic mode (form icon, left button) — the structured form with Basic Info, Tool Integration, and Knowledge Base Integration sections.
• Advanced mode (code icon, right button) — a JSON editor showing the agent's configuration.

Both modes edit the same agent. You can switch freely at any time.

---

When to use Advanced mode

Advanced mode is useful for:

• Pasting a configuration from another agent or environment.
• Bulk editing fields that would take many clicks in Basic.
• Copying a configuration for version control, sharing, or duplicating an agent.

The Knowledge Base configuration has smart defaults that work well out of the box. The UI itself notes:

"Knowledge Base configuration uses optimized defaults automatically. Advanced customization via KnowledgeBaseIntegrationAndRetrieval is available but rarely needed."

---

The Advanced editor

When you switch to Advanced mode, the section heading changes to Agent configuration. The toolbar above the editor has:

• Copy JSON (labeled) — copies the entire configuration to your clipboard.
• Format JSON (icon-only) — pretty-prints the current JSON. Disabled when there is a syntax error.

Default JSON on a new agent

When you open Advanced mode on a brand-new (unsaved) agent, the editor pre-fills with:

{
  "name": "",
  "textModelId": "global.amazon.nova-2-lite-v1:0"
}

When pasting a copied configuration, select all (⌘/Ctrl+A) first to replace this entirely.

---

JSON schema

The JSON is a single object. Editable top-level keys:

Key	Type	Required	What it does
name	string	yes	Agent name.
textModelId	string	no	The text/chat model. Format: provider:model-id (e.g., anthropic:claude-sonnet-4-6).
speechModelId	string	no	The voice model. Omit or leave empty for text-only agents. Format: model ID string (e.g., amazon.nova-sonic-v1:0).
systemPrompt	string	no	The agent's instructions.
tools	array	no	Tool declarations. See tool entry shape below.
KnowledgeBaseIntegrationAndRetrieval	object	no	KB overrides (rarely needed). See KB overrides below.

备注

A few agent settings live outside this JSON — they are sent alongside it in the API call but don't appear in the editor:

• Thinking budget (thinkingBudget) — set in Basic mode.
• Streaming (streamingEnabled) — on by default.

---

Example

{
  "name": "Aria",
  "textModelId": "anthropic:claude-sonnet-4-6",
  "speechModelId": "amazon.nova-sonic-v1:0",
  "systemPrompt": "You are Aria, a friendly support assistant...",
  "tools": [
    {
      "type": "remote_fetch",
      "name": "support_kb",
      "url": "https://mcp.example.com/server",
      "timeout": 30,
      "connector": {
        "authType": "oauth",
        "oauth": { "oauthType": "dynamic", "clientId": "" }
      }
    }
  ]
}

---

Tool entry shape

Each entry in the tools array is one of:

// Remote (MCP) tool
{
  "type": "remote_fetch",
  "name": "my_tool",
  "url": "https://mcp.example.com/server",
  "timeout": 30,
  "connector": {
    "authType": "oauth",
    "oauth": { "oauthType": "dynamic", "clientId": "..." }
  }
}

// Static OAuth (pre-registered client)
{
  "type": "remote_fetch",
  "name": "my_tool",
  "url": "https://mcp.example.com/server",
  "connector": {
    "authType": "oauth",
    "oauth": { "oauthType": "static", "clientId": "...", "clientSecret": "..." }
  }
}

// Local (device-side) tool — usually not authored by hand
{
  "type": "local",
  "name": "set_volume",
  "description": "Set the device volume",
  "inputSchema": { "json": { "type": "object", "properties": { ... }, "required": [...] } }
}

cloud tools (Knowledge Bases) are not authored here — they are managed via the KB form and appear as read-only entries.

---

Knowledge Base overrides

Most admins should leave KB settings on their smart defaults. To override, add a KnowledgeBaseIntegrationAndRetrieval block:

{
  "KnowledgeBaseIntegrationAndRetrieval": {
    "knowledgeBase": {
      "embeddingModelName": "Amazon Titan Text Embeddings V2"
    },
    "dataSource": {
      "files": {
        "chunkingStrategy": "HIERARCHICAL",
        "hierarchicalChunkingConfiguration": {
          "levelConfigurations": [{ "maxTokens": 1500 }, { "maxTokens": 300 }],
          "overlapTokens": 60
        }
      },
      "web": {
        "chunkingStrategy": "HIERARCHICAL",
        "hierarchicalChunkingConfiguration": {
          "levelConfigurations": [{ "maxTokens": 1500 }, { "maxTokens": 300 }],
          "overlapTokens": 60
        },
        "crawlerRateLimit": 300,
        "crawlerScope": "HOST_ONLY",
        "inclusionFilters": [".*docs\\.example\\.com.*"],
        "exclusionFilters": [".*\\/login.*"]
      }
    },
    "retrieval": {
      "useReranking": false,
      "numberOfResults": 5,
      "numberOfRerankedResults": 3
    }
  }
}

You don't need to specify every field — omitted fields fall back to the smart defaults.

Chunking strategies

chunkingStrategy accepts:

• HIERARCHICAL (default) — parent and child chunks; best for long structured documents.
• FIXED_SIZE — uniform chunks; uses fixedSizeChunkingConfiguration.
• SEMANTIC — semantically aware splits; uses semanticChunkingConfiguration.
• NONE — no chunking; one chunk per document.

Retrieval settings

• numberOfResults — chunks to retrieve per query (default 5; range 1–100).
• useReranking — when true, results are reranked before being passed to the LLM.
• numberOfRerankedResults — how many reranked chunks to keep (only used when useReranking is true).

---

Switching between modes

From → To	What happens
Basic → Advanced	The form contents are serialised into JSON. Always succeeds.
Advanced → Basic	The JSON is parsed back into form fields. Only succeeds if the JSON is valid.

If the JSON is invalid, you cannot switch back to Basic — fix the syntax first. The editor highlights errors, and any syntax issues are shown above the editor.

---

Common patterns

Copy an agent

1. Open the source agent → switch to Advanced → Copy JSON.
2. Click + (new agent) → Create from Scratch → switch to Advanced.
3. Select all (⌘/Ctrl+A) in the editor and paste.
4. Update the "name" field.
5. Click Create Agent.

See Copy an agent for the full walkthrough.

Bulk-update tools across agents

1. Build the tool list on one agent.
2. Copy the tools array.
3. Open another agent → Advanced → replace its tools array.
4. Save.

Version-control your agents

Copy the JSON to a file in your repo. When you want to roll back, paste it back in.

---

Tips

• The JSON editor is strict. No trailing commas, no comments, no single quotes — these all cause parse errors.
• Don't embed secrets. Anything in the JSON is visible to any admin who views the agent.
• When in doubt, use Basic. Basic enforces field-by-field validation, making errors easier to spot.