amodal.json

Every Amodal agent repo has an amodal.json file at the repo root. It names the agent, declares package content, and enables optional runtime features such as custom apps, MCP servers, web tools, memory, and per-user scope isolation.

Keep secrets out of this file. Reference them with env:NAME and configure the values in Amodal, your deployment environment, or local .env files.

Minimal Config

{
  "name": "investor-relations",
  "version": "0.1.0"
}

You don't set a model in amodal.json. The agent's model and any provider credentials are Amodal/platform settings, not fields in this file. When you don't choose a model, the agent runs on the platform default model, currently Gemini 3.5 Flash (google / gemini-3.5-flash). A minimal amodal.json like the one above is enough to deploy and run. Select a specific model in Amodal or through the Platform API only when you want to override that default.

Typical Config

{
  "name": "investor-relations",
  "version": "0.1.0",
  "description": "Investor relations assistant for public-company research",
  "runtimeApp": {
    "custom": true,
    "build": "npm run build",
    "dist": "dist"
  },
  "packages": [
    "@amodalai/connection-gmail",
    {
      "package": "@amodalai/connection-s3",
      "use": ["connections.s3"]
    }
  ],
  "webTools": {
    "provider": "google",
    "apiKey": "env:GOOGLE_GENERATIVE_AI_API_KEY"
  },
  "memory": {
    "enabled": true,
    "editableBy": "any",
    "maxEntries": 100,
    "maxTotalChars": 16000
  },
  "scope": {
    "requireScope": true
  }
}

Required Fields

Common Optional Fields

Do not put store backend configuration in amodal.json. Store schemas live in amodal/stores/*.json; the cloud runtime supplies the backing database from the deployment environment.

Schema Version

schemaVersion and version are different things:

• version is your agent version — a free-form string you control (use semantic versions). It identifies a release of your agent.
• schemaVersion is the format version of the amodal.json manifest itself — an integer the platform owns. It only changes when the manifest format changes in a way that needs migration.

{
  "name": "investor-relations",
  "version": "0.1.0",
  "schemaVersion": 1
}

You normally don't write schemaVersion. When it's omitted, the manifest is treated as version 1 (the current format), so existing repos keep working without changes. Declare it explicitly only when a future format version asks you to.

If a manifest declares a schemaVersion newer than the runtime it's being deployed to understands, the deploy fails with a clear error rather than silently misreading the file — upgrade the runtime to deploy that config.

Packages

Use packages for reusable agent content:

{
  "packages": [
    "@amodalai/connection-example",
    {
      "package": "@amodalai/support-package",
      "use": ["skills.triage", "knowledge.support-policy"]
    }
  ]
}

Standard npm dependencies for a custom runtime app or tool code belong in package.json, not in amodal.json.

Runtime App

runtimeApp.custom tells the build server to build and publish a repo-provided SPA:

{
  "runtimeApp": {
    "custom": true,
    "build": "npm run build",
    "dist": "dist"
  }
}

When omitted, the platform uses the default runtime chat app. See Runtime Apps for the build and serving contract.

Scoping a Session to an Agent

One deployed agent can expose different modes. Each mode is an agent under amodal/agents/, and a session is rooted in one by passing its name:

// amodal/agents/research/agent.json
{
  "name": "Research",
  "skills": ["research"],
  "tools": ["propose_revision"],
  "connections": ["sec", "gmail"],
  "stores": {
    "company-profiles": "read",
    "research-notes": "rw"
  }
}

The prompt lives in the sibling AGENT.md. Start a session on it with the agent field:

POST /chat
{ "message": "Summarize the latest filing", "agent": "research" }

Omit agent and the session is the default chat, which loads everything in the bundle. Name one and the session sees only what that agent declares — its prompt becomes the operating prompt, and its skills / tools / connections / stores / mcp / subagents scope the surface.

Files under amodal/skills/, amodal/connections/, amodal/stores/, and amodal/tools/ are loaded as repo content, but a scoped agent only exposes the names it lists. If chat says a connection or store does not exist even though the files are present, check that agent's config first.

Skill names are the loaded skill names, not always the folder names. An amodal/skills/craft-greeting/SKILL.md file with # Skill: Craft Greeting is referenced as "Craft Greeting", unless the loader metadata declares a different name.

See Agents for the full config.

Environment Variables

Any string value in amodal.json can reference an environment variable:

{
  "webTools": {
    "apiKey": "env:GOOGLE_GENERATIVE_AI_API_KEY"
  }
}

Use env: for API keys, tokens, database URLs, internal service URLs, and values that differ between dev, staging, and prod. Hardcode non-sensitive values such as model names, package names, and agent descriptions.

Memory

{
  "memory": {
    "enabled": true,
    "maxEntries": 50,
    "maxTotalChars": 8000,
    "editableBy": "any",
    "nudgeInterval": 10,
    "sessionSearch": true
  }
}

When enabled, the agent gets a memory tool with add, remove, list, and search actions. Memory is stored by agent and can be partitioned by scope_id.

Scope

For embedded products, scope_id isolates sessions, memory, and non-shared store data by end user, tenant, workspace, or another stable identifier:

{
  "scope": {
    "requireScope": true
  }
}

With requireScope: true, chat requests without a scope are rejected. Connection specs can also use contextInjection to forward scope context into API requests; see Connections.

Advanced Fields

sandbox, hooks, and detailed subagent controls are advanced runtime features. Keep them out of starter repos unless you have a concrete need and have verified the behavior locally.