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, fixtures, and frontend files. Underscore-prefixed folders under amodal/ (like _lib/ and _types/) are never scanned 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.

agents/main/AGENT.md overrides the base prompt when no named agent applies. Its agent.json adds opt-in tools, but does not narrow the default chat's skills, connections, or stores.

The loader also accepts top-level connections/, skills/, knowledge/, stores/, and tools/. For each content type, a nonempty amodal/<type>/ takes precedence over the top-level directory. Use one location per type to avoid hiding files.

Reserved Paths

Package Content

Declare installed content packages in amodal.json#packages. Packages can provide connections, skills, knowledge, stores, tools, and channels. Install them with your package manager before running locally. Local content wins when names collide. The package and content names below are placeholders:

{
  "packages": [
    {
      "package": "@example/agent-kit",
      "use": ["skills.review", "connections.crm"]
    }
  ]
}

Platform-Managed Surfaces

• Custom UI is a frontend app declared with runtimeApp.custom. Amodal builds it and serves it from the agent's origin.
• Scheduled and background automation is configured in Amodal. It is separate from the source bundle.

Deploy Lifecycle

On deploy, Amodal retrieves the selected source version, installs dependencies, validates the agent definition, and builds its artifacts. If a custom app is enabled, its build must succeed. Amodal then provisions the runtime according to the deploy settings. Check the deployment status and production indicator separately; a finished build does not always activate production.