Project Structure

An agent source bundle has amodal.json at its root. It can contain only agent definitions, or include a frontend app that Amodal builds and serves with the deployed agent. The same layout works in a Git repository and in Amodal-hosted source.

Put agent definition files under the amodal/ content directory, with hooks, named agents, and evals in their 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
│   ├── _lib/                    # optional shared code imported by tools
│   └── _types/                  # optional shared types (not loaded as agent content)
├── hooks/
│   └── redact-pii/
│       ├── hook.json
│       └── index.mjs
├── agents/
│   └── compliance-checker/
│       ├── AGENT.md
│       ├── agent.json
│       └── CONTEXT.md             # optional context rendered each turn
└── evals/
    └── happy-path.md

Keep agent content in these reserved directories so it stays separate from app source, scripts, and fixtures. Folders under amodal/ other than the content types, such as _lib/ and _types/, are not loaded as agent content; use them for code that tools import.

To configure the default chat, add agents/default/AGENT.md with the agent's instructions and agents/default/agent.json with its capabilities. The prompt file is required; a directory containing only agent.json is ignored.

For example, agents/default/agent.json can select a custom tool:

{
  "name": "Default",
  "tools": ["propose_revision"]
}

The runtime uses default when a chat request omits agent. Other named agents are selected with "agent": "<directory-name>". Their capability lists determine which skills, connections, stores, and tools are available; see Agents.

Without an authored default, chat is unscoped and uses agents/main/AGENT.md, when present, as its instructions inside the platform prompt. agents/main/agent.json can add opt-in tools to that chat but does not narrow its skills, connections, or stores.

The loader also accepts top-level connections/, skills/, knowledge/, stores/, and tools/. When amodal/<type>/ has entries, the top-level directory for that type is ignored. Use one location per type.

Reserved Paths

Path	Purpose
`amodal.json`	Root manifest: identity, packages, 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/_lib/`, `amodal/_types/`	Optional shared code and types imported by tools. Never scanned as agent content.
`hooks/<name>/`	Guardrail hooks: a `hook.json` manifest plus an `index.mjs` handler.
`agents/<name>/AGENT.md`	Instructions for a named agent.
`agents/<name>/agent.json`	The named agent's capabilities and execution settings.
`agents/<name>/CONTEXT.md`	Optional named-agent context rendered each turn.
`evals/*.md`	Evaluation cases.
`src/`, `index.html`, build files	Optional custom runtime app. Used only when `runtimeApp.custom` is enabled.

Outside The Source Bundle

Installed content packages are declared in amodal.json#packages; see amodal.json.
Scheduled and background automations are configured in Amodal, not in source files.