Architecture Overview

Amodal has three customer-facing parts: the app for managing agents, the Platform API for automation, and the runtime API for conversations and tool execution. The React SDK connects your application to a deployed runtime.

Source and deployments

Agent source lives in a connected Git repository or Amodal-hosted snapshots. It includes amodal.json, instructions, connections, skills, knowledge, stores, tools, evals, and optional frontend code.

Amodal records a source version.
The build service validates the source and builds runtime and frontend artifacts.
A deployment runs those artifacts on hosted infrastructure.
The production URL routes to the selected active deployment.

A source version, a successful build, and an active deployment are separate records. See Source & Deploy and the Deployment API for activation, environment promotion, and rollback.

Runtime request flow

Your app or the Amodal chat UI
  → Runtime API: authenticate and resolve the session
  → Agent loop: call the model with instructions and available tools
  → Tools: query APIs, read knowledge, update stores, or call specialists
  → Agent loop: read results and continue
  → Client: receive streamed text, tool activity, and completion

Chat requests use session_id to continue a conversation. scope_id selects the data scope; authenticated claims and application authorization determine who may use it. See Embedding.

Prompts and tools

The runtime prepares each session's instructions, skills, knowledge index, connection guidance, and store descriptions. Named agents narrow access through resource declarations. Tool schemas are sent to the model alongside the prompt.

AGENT.md supplies operating instructions within the compiled prompt.
CONTEXT.md renders current app context before each model call.
Skills load on demand unless configured as eager or selected for a skill-scoped session.
Knowledge documents load through load_knowledge; corpora use search and read tools.
A non-empty basePrompt overrides normal prompt compilation.

The model chooses tools from the available set. The runtime validates arguments and applies the checks supported by the execution path. Tool errors usually return as observations so the model can respond or try another action. See Tools and Guardrails for permission boundaries.

Storage

The hosted runtime uses platform-backed clients for durable sessions and stores. The Platform API owns cloud records and database access. The local development server uses in-memory sessions and stores.

Saving conversation history does not by itself coordinate concurrent requests across runtime replicas. Hosting also manages execution ownership, routing, and event delivery.

Packages

Package	Role
`@amodalai/react`	Published React components, hooks, and streaming clients
`@amodalai/react/widget`	Chat-widget entry point from the React package
`@amodalai/types`	Shared contracts for bundles, tools, stores, and events
`@amodalai/runtime`	Internal runtime engine, sessions, tools, providers, and HTTP routes
`@amodalai/core`	Internal source loading, schemas, package resolution, evals, and shared utilities
`@amodalai/platform-api`	Organizations, agents, source versions, deployments, auth, billing, and runtime-facing storage APIs
`@amodalai/build-server`	Source validation and artifact builds
`@amodalai/hosted-runtime`	Hosted execution and platform-backed runtime clients

The runtime and core packages are private workspace packages. Use the CLI for local development and the published React SDK to embed hosted agents.

Authentication and secrets

Platform automation tokens manage cloud resources. Runtime tokens and agent API keys authorize runtime calls. Hosted browser sessions can authenticate through the edge, which forwards runtime credentials server-side. These credentials serve different purposes; see Authentication.

Agent source should contain secret references such as env:SUPPORT_API_KEY, with values configured separately. Custom handlers run with access to their deployment environment. Review their logging, outputs, and side effects; connection policies do not sandbox arbitrary code.

Named OAuth connections hold application secrets, account tokens, and consent transactions encrypted in the platform database or in private local broker files. Connection definitions carry an opaque credential reference instead of a value. Before each REST or HTTP MCP request, the broker checks the agent, environment, binding, and approved resource origin, then refreshes expiring tokens. OAuth grants never become environment variables.

Protocols

Protocol	Use
HTTP and SSE	Chat requests and streamed responses
REST	Platform operations, session history, and runtime data
MCP	External tool discovery and execution

The ordinary chat stream is a POST response and does not automatically reconnect. The runtime event bus uses a separate subscription with replay behavior described in Event Bus.