Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Introduction

Amodal is a git-repo-centric cloud platform for agents. Your agent definition — connections, skills, knowledge, tools, stores, intents, evals, and optional runtime app code — lives as files in your repository. Amodal reads these files, deploys them to a hosted runtime, and gives your team the operational surface around the agent: sessions, costs, logs, source history, deployments, and evals.

How It Works

Your Repo
  ├── amodal.json          ← agent identity and runtime features
  ├── amodal/
  │   ├── connections/     ← API contracts, docs, and policies
  │   ├── skills/          ← Markdown reasoning frameworks
  │   ├── knowledge/       ← Domain knowledge documents
  │   ├── stores/          ← Typed persistent data schemas
  │   ├── tools/           ← Custom tool handlers
  │   └── intents/         ← Deterministic typed actions
  ├── hooks/               ← Guardrail hooks
  ├── evals/               ← Test cases for agent quality
  └── src/                 ← Optional custom runtime app
 
       ↓ deploy from Amodal
 
Hosted Runtime
  ├── Context Compiler     ← builds optimized prompts
  ├── Token Allocator      ← manages context window budget
  ├── Security Layer       ← field scrubbing, output guards, action gates
  ├── Provider Adapter     ← model provider selected in Amodal/platform settings
  └── Session Manager      ← durable scoped sessions

The Core Loop

Every agent runs the same fundamental cycle:

Explore → query connected systems, load knowledge, gather context
Plan    → reason about findings, decide next steps
Execute → call APIs, dispatch sub-agents, present results, learn

Simple questions skip planning. Complex questions get the full loop with multi-agent dispatch and skill activation. The runtime matches depth to the question automatically.

Core Concepts

Before embedding an agent in an application, it helps to separate the runtime concepts that often get conflated:

ConceptMeaningExample
AgentThe versioned behavior definition Amodal deploys: knowledge, skills, tools, stores, hooks, connections, evals, and optional app code.underwriting-agent
SessionOne conversation or workflow run. This is the chat history, tool-call history, approvals, traces, and token/cost record for a specific interaction. Resume it with session_id.session_01J...
ScopeThe application boundary the agent is operating inside. It partitions data, memory, stores, credentials, and operator visibility.tenant:acme, case:merchant-123, account:42
Scope contextThe current facts your app injects for this turn: route, selected record, user role, tenant id, visible page state, or other grounding data.{ "case_id": "merchant-123", "page": "risk-review" }
Session type / agent surfaceA curated behavior surface that narrows the loaded tools, skills, and instructions for a particular UI or workflow.request-intake, admin, review

The most important distinction is:

  • scope_id tells Amodal where the agent is operating and what data boundary applies.
  • session_id tells Amodal which exact conversation to continue.

You can have multiple sessions in the same scope. For example, a support app might have ten chat sessions inside tenant:acme; all are isolated to Acme's data, but each has its own conversation history. Passing the same scope_id does not automatically mean "resume the last chat." To continue a specific conversation, pass its session_id.

Key Capabilities

CapabilityWhat It Does
Multi-providerAnthropic Claude, OpenAI, Google Gemini, and other supported providers
Git-native configEverything is a file. Version, diff, review, and deploy your agent like code
Connection pluginsInstall or define connection packages for the systems your agent should call
Security infrastructureField scrubbing, output guards, action gates, scope checking, leak detection
Evaluation frameworkLLM-judged evals, experiments, cost tracking, multi-model comparison
Amodal deploymentsCommit source changes, deploy them, promote production, and inspect history
React SDK@amodalai/react components and chat widget for embedding
Operations UISession replay, activity logs, runtime logs, deploy state, and usage analytics

Next Steps