Project Structure

An Amodal agent is a Git repo with amodal.json at the root. The repo may contain only agent definition files, or it may also contain a full frontend app that Amodal builds and serves for the deployed agent.

Put agent definition files under the amodal/ content directory, with hooks, subagents, and evals in their reserved top-level directories:

my-agent/
├── amodal.json
├── package.json                 # optional, required for custom SPA or custom code deps
├── src/                         # optional custom runtime app
├── index.html                   # optional custom runtime app
├── vite.config.ts               # optional custom runtime app
├── amodal/
│   ├── connections/
│   │   └── s3/
│   │       ├── spec.json
│   │       ├── policy.json
│   │       ├── surface.md
│   │       ├── entities.md
│   │       └── rules.md
│   ├── skills/
│   │   └── ask-agent/
│   │       └── SKILL.md
│   ├── knowledge/
│   │   └── operating-rules.md
│   ├── stores/
│   │   └── investors.json
│   ├── tools/
│   │   └── propose_revision/
│   │       └── tool.ts
│   ├── intents/
│   │   └── send-document/
│   │       └── intent.ts
│   ├── _lib/                    # optional shared code imported by intents and tools
│   └── _types/                  # optional shared types (not loaded as agent content)
├── hooks/
│   └── redact-pii/
│       ├── hook.json
│       └── index.mjs
├── agents/
│   └── compliance-checker/
│       └── AGENT.md
└── evals/
    └── happy-path.md

Keep agent content in these reserved directories so it stays separate from app source, scripts, fixtures, and frontend files. Underscore-prefixed folders under amodal/ (like _lib/ and _types/) are never scanned as agent content; use them for code that intents and tools import.

For a first working agent, include a default session type in amodal.json that exposes the repo capabilities you expect chat to use:

{
  "name": "my-agent",
  "version": "0.1.0",
  "session_types": {
    "default": {
      "prompt": "Answer using the configured tools and knowledge.",
      "skills": ["Support Triage"],
      "connections": ["support-api"],
      "stores": {
        "notes": "rw"
      },
      "tools": ["draft_reply"]
    }
  }
}

Reserved folders define available content. session_types.default defines what the normal chat session can actually see and call. If the files deploy but chat says a capability is missing, check this manifest wiring and the loaded names.

Reserved Paths

Path	Purpose
`amodal.json`	Root manifest: identity, packages, session types, memory, web tools, custom runtime app config.
`amodal/connections/<name>/`	API, MCP, or driver-backed connection definitions.
`amodal/skills/<name>/SKILL.md`	Reasoning methods the agent can apply.
`amodal/knowledge/*.md`	Domain reference documents injected or loaded as context.
`amodal/stores/*.json`	Typed store schemas. The runtime generates store tools from these files.
`amodal/tools/<name>/tool.ts`	Custom code tools.
`amodal/intents/<name>/intent.ts`	Deterministic typed actions that can compose tools and skills.
`amodal/_lib/`, `amodal/_types/`	Optional shared code and types imported by intents and tools. Never scanned as agent content.
`hooks/<name>/`	Guardrail hooks: a `hook.json` manifest plus an `index.mjs` handler.
`agents/<name>/AGENT.md`	Subagents and prompt overrides.
`evals/*.md`	Evaluation cases.
`src/`, `index.html`, build files	Optional custom runtime app. Used only when `runtimeApp.custom` is enabled.

Package Content

amodal.json#packages can load installed packages that ship the same content types: connections, skills, knowledge, stores, tools, and channels. Local repo content wins when names collide.

{
  "packages": [
    "@this-npm-test-org/s3-connection-driver",
    {
      "package": "@example/agent-kit",
      "use": ["skills.review", "connections.crm"]
    }
  ]
}

Platform-Managed Surfaces

Custom UI is a repo-level app declared with runtimeApp.custom, built to dist/, uploaded to R2, and served by the edge worker.
Scheduled/background automation is platform-managed through Amodal/API bindings and intent targets.

Deploy Lifecycle

On deploy, Amodal clones the repo, installs dependencies, loads and validates the agent definition, uploads server artifacts and the repo tarball to object storage, optionally builds the custom SPA, then creates or updates the hosted runtime for that deploy.