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 scope requirements.

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"
}

Model selection and provider credentials are platform settings. A minimal manifest uses the deployment's default model. Select a model in Amodal or through the Platform API to override it.

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 identifies your agent source release. You control this string.
• schemaVersion identifies the manifest format. The platform defines this integer.

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

Omitting schemaVersion uses format 1.

A manifest format newer than the runtime supports fails validation. Deploy it to a runtime that supports that format.

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 agents/ at the repo root (a sibling of amodal/, not inside it), and a session is rooted in one by passing its name:

// 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" }

If agent is omitted, the chat route selects agents/default/ when present. Its resource declarations still apply. Without an authored default, chat uses the unscoped bundle and main operating prompt.

A named root agent supplies the operating prompt and selects resources through skills, tools, connections, stores, mcp, and subagents.

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 a connection or store is unavailable, check the active agent's resource declarations.

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", because the # Skill: heading takes precedence over frontmatter.

See Agents for the full config.

Environment Variables

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

{
  "webTools": {
    "provider": "google",
    "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. Use literal values for package names and agent descriptions.

Memory

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

With an available memory backend and editableBy: "any" (the default), the runtime can register a memory tool with add, remove, list, and search actions. A named agent must also declare memory in its tools. Both editableBy: "none" and "admin" disable the tool. Existing memory can still be included in the prompt.

Memory is stored by agent and partitioned by scope_id when supplied.

Scope

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

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

With requireScope: true, static-bundle chat routes reject an empty resolved scope. A verified token's scope satisfies this check even without scope_id in the body. The hosted runtime resolves bundles dynamically and does not apply this guard. Your backend must require an authorized scope and include it in every runtime token it mints. Connection specs can also use contextInjection to forward scope context into API requests; see Connections.

A runtime token's scope does not restrict access to session history or resumed sessions. Your backend must authorize each scope, session, and operation and retain all runtime credentials. See Embedding & Multi-tenancy.

Advanced Fields

See Agents for resource selection and delegation, Hooks for lifecycle rules, and Agent Workflows for composition and durable execution.