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.

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

Model selection and provider credentials are platform settings, not amodal.json fields. Select a model in Amodal or through the Platform API.

The schema drops unknown fields without an error, so a misspelled field has no effect.

Fields

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

Packages

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

A bare string loads everything the package ships. The object form loads only the use entries, each written as <kind>.<name>. Kinds are connections, skills, knowledge, stores, tools, hooks, and channels. Local repo content wins when names collide.

Install the packages with your package manager. npm dependencies for a runtime app or tool code belong in package.json, not in amodal.json.

Environment Variables

Write a string value as env:NAME to read it from the environment instead of committing it:

{
  "webTools": {
    "provider": "google",
    "apiKey": "env:GOOGLE_GENERATIVE_AI_API_KEY"
  }
}

amodal dev resolves every env: value in amodal.json when it loads the file. An unset variable fails the load with ENV_NOT_SET.

The hosted runtime loads amodal.json without resolving env: values. Connection specs and webTools.apiKey resolve their own env: references from agent secrets; see Connections.

"webTools": true is shorthand for the example above.

Memory

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

With enabled: true and a memory backend, the runtime registers a memory tool with add, remove, list, and search actions. A named agent must also list memory in its tools. editableBy defaults to "any"; "admin" and "none" both disable the tool, and saved memory still appears in the prompt. maxEntries defaults to 50 and maxTotalChars to 8000.

Memory is stored per agent and partitioned by scope_id. The schema also accepts nudgeInterval and sessionSearch, which have no runtime effect.

Scope

scope_id partitions sessions, memory, and non-shared store data by end user, tenant, or workspace. Your backend sets it in the runtime tokens it mints; see Embedding & Multi-tenancy.

The hosted runtime does not enforce scope.requireScope. amodal dev runs every request in scope local, or in the value of --scope, and ignores a scope_id in the request body. Enforce scope in your backend instead of relying on this flag.

CI Rules

The platform reads ci from amodal.json at the pushed commit. ci.deploy applies to connected GitHub and GitLab repositories. ci.evals applies to GitHub only.

{
  "ci": {
    "deploy": {
      "branches": ["main", "release/*"],
      "paths": ["package.json", "pnpm-lock.yaml"]
    },
    "evals": { "runOn": "production" }
  }
}

A push that touches neither the agent's root directory nor a listed path skips the build. An unreadable amodal.json falls back to the defaults.

Pushes build only when autoDeploy is on in the agent's deploy settings. It is off by default. See Deploy Settings.