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 2.5 Flash (google / gemini-2.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
  },
  "session_types": {
    "ask-agent": {
      "prompt": "Answer questions using the approved investor-relations workflow.",
      "skills": ["ask-agent"],
      "stores": {
        "company-profiles": "read"
      }
    }
  }
}

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.

Session Types

Session types let one deployed agent expose different modes:

{
  "session_types": {
    "research": {
      "prompt": "Use the research workflow.",
      "skills": ["research"],
      "intents": ["summarize-filing"],
      "stores": {
        "company-profiles": "read",
        "research-notes": "rw"
      },
      "connections": ["sec", "gmail"],
      "tools": ["propose_revision"]
    }
  }
}

Use session types when the same deployed agent needs different prompts, tools, or access boundaries for different entry points.

For a starter repo, define a default session type and wire every capability the normal chat experience should use:

{
  "session_types": {
    "default": {
      "prompt": "You are the support agent. Use the available tools when they help.",
      "skills": ["Support Triage"],
      "connections": ["zendesk"],
      "stores": {
        "customers": "read",
        "notes": "rw"
      },
      "tools": ["propose_reply"]
    }
  }
}

Files under amodal/skills/, amodal/connections/, amodal/stores/, and amodal/tools/ are loaded as repo content, but a narrowed session type only exposes the names listed on that profile. If chat says a connection or store does not exist even though the files are present, check session_types.default 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" in session_types, unless the loader metadata declares a different name.

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.