# Amodal

> Documentation for the Amodal Agent Runtime — build domain-specific AI agents from your repo.

## Docs

- [Chat Widget](/sdk/chat-widget): A standalone, embeddable chat widget for adding agent-powered chat to any web application. Available as a sub-export of `@amodalai/react`.
- [SDK Overview](/sdk): Two ways to embed Amodal in your product:
- [@amodalai/react](/sdk/react): High-level React components for embedding Amodal agents in your product. Provides a provider, chat UI, action components, and hooks.
- [Architecture Overview](/reference/architecture): Amodal is a layered system. The Runtime is the agent engine (state machine, providers, tools, stores, session manager). The CLI provides the developer interface. The React SDK and chat widget embed the runtime's streaming output in web apps. Each layer has a clear boundary and a clear job.
- [Runtime Event Bus](/reference/events): The runtime publishes server-level state changes (sessions created/updated, automations triggered/completed, store writes, config reloads) as events. Clients subscribe once to `GET /api/events` via SSE and react in real time — no polling.
- [Runtime Server](/reference/runtime): The runtime (`@amodalai/runtime`) is an HTTP server that hosts the agent engine and exposes it over SSE for chat clients. It handles session management, automation scheduling, webhook ingestion, and tool execution. It is the bridge between "someone sends a message" and "the agent reasons about it and responds."
- [Quick Start](/quickstart/create-agent): This guide walks you through creating an agent from scratch, connecting it to an API, and having a conversation with it. By the end you will have a working agent running locally that can query external systems and reason about the results.
- [Introduction](/quickstart/introduction): Amodal is a **git-repo-centric agent runtime**. Your agent's configuration — connections, skills, knowledge, tools, automations — lives as files in your repository. The runtime reads these files, compiles them into an optimized context, and runs a reasoning loop against any supported LLM provider.
- [Project Structure](/quickstart/project-structure): Everything that defines your agent lives in your repo root. The runtime reads these files at startup and watches for changes during development.
- [FAQ](/learn/faq): For architectural positioning vs. Vercel AI SDK, LangChain, Mastra, and raw provider SDKs, see [What is an agent?](/learn/what-is-an-agent).
- [What is an agent?](/learn/what-is-an-agent): Useful definition:
- [Agent Architecture](/learn/architecture/agents): Amodal uses a multi-agent architecture where a **primary agent** delegates data-intensive work to ephemeral **task agents**, keeping its own context clean for reasoning.
- [Context Management](/learn/architecture/context): The SDK provides several mechanisms to keep agent context clean and within limits, even during complex multi-step investigations.
- [The Core Loop](/learn/architecture/core-loop): Every Amodal agent runs the same fundamental cycle:
- [State Machine](/learn/architecture/state-machine): The Amodal agent loop is built as an **explicit state machine** — a discriminated union of states plus a `transition()` function that dispatches to a handler per state. This is what runs every time you send a message to an agent.
- [Admin Agent](/guide/admin-agent): When you run `amodal dev`, the dev UI exposes a separate **admin chat** at `/config/chat`. Admin chat runs in its own session with its own system prompt — separate from your regular user chat — and has access to a set of file tools that let it read, search, and edit the files in your agent repo. You use it to configure the agent itself: add a connection, write a skill, fix a knowledge doc, delete a stale automation.
- [Agents](/guide/agents): The `agents/` directory defines **custom subagents** and lets you **override built-in agents**. Each subdirectory is an agent with an `AGENT.md` file.
- [Automations](/guide/automations): Automations let your agent work proactively — monitoring systems, digesting data, responding to incidents, detecting drift — without someone typing in a chat box. Instead of waiting for a user to ask "what happened overnight?", the agent runs on its own, queries the systems it needs, and routes the results to Slack, email, a webhook, or wherever your team actually looks.
- [amodal.json](/guide/config): Every Amodal project starts with a single file: `amodal.json` at the root of your repo. This is the manifest. It tells the runtime who the agent is, which LLM to use, how to handle failover when a provider goes down, and how to connect to the outside world — MCP servers, data stores, and sandbox environments.
- [Connections](/guide/connections): Each connection is a directory in `connections/` containing a spec, access rules, and optional documentation. Pre-built plugins come with everything maintained — you just provide credentials.
- [Engineering Standards](/guide/engineering-standards): The standards the runtime holds itself to. If you're writing custom tool handlers, embedding the runtime via `createAgent()`, or extending the codebase, follow these patterns. They're not aesthetic — every one exists because we paid for the opposite in a previous version of the codebase.
- [Evals](/guide/evals): Evals live in `evals/` as Markdown files. Each eval defines a query, setup context, and assertions that measure agent quality.
- [Knowledge Base](/guide/knowledge-base): The knowledge base is what turns a general-purpose reasoning engine into *your* agent. Without knowledge, the agent is smart but uninformed — it can follow methodologies and call APIs, but it does not know that your payments service spikes every Friday at payroll time, or that the `svc-deploy` service account triggers brute-force alerts every time CI runs, or that your team prefers Slack over email for P1 escalations.
- [MCP Servers](/guide/mcp): Amodal supports the [Model Context Protocol](https://modelcontextprotocol.io) for connecting external tool servers. MCP tools appear alongside your custom tools and built-in tools — the agent uses them transparently.
- [Pages](/guide/pages): Pages are **React components** that render custom UI views in the runtime app. They live in `pages/` and use SDK hooks to read from stores, invoke skills, and display structured data. This is how you build dashboards, morning briefs, investigation views, and other composed screens.
- [Providers](/guide/providers): Amodal supports multiple LLM providers with a unified interface, built on the Vercel AI SDK. Switch providers by changing a field in `amodal.json` — no code changes needed.
- [Security & Guardrails](/guide/security): Security is built into the runtime at every layer. Six components work together to protect sensitive data and control agent behavior.
- [Skills](/guide/skills): Every LLM can answer questions. The difference between a generic chatbot and a domain expert is *how it reasons* about a problem. Skills encode that reasoning — they are step-by-step methodologies, written in Markdown, that teach the agent how to investigate, assess, and respond to specific situations.
- [Stores](/guide/stores): Stores give your agent persistent, typed data storage. Define a schema in `stores/` and the runtime auto-generates CRUD tools the agent can use.
- [Tools](/guide/tools): Tools are how the agent interacts with the world beyond conversation. They make API calls, query stores, dispatch sub-agents, create tickets, send messages, and perform any action your product needs. The tool system has two layers: built-in tools that ship with every Amodal agent, and custom tools that you define for your specific business logic.
- [amodal chat](/cli/chat): Open an interactive terminal chat with your agent. The chat UI is a React-based TUI built with Ink.
- [amodal pkg connect & sync](/cli/connect): Add a connection to your agent. Connections give the agent API access and documentation for external systems.
- [amodal dev](/cli/dev): Start a local runtime server for development. The server watches your repo config files and hot-reloads on every change.
- [amodal eval](/cli/eval): Run evaluation suites against your agent to measure quality, compare models, and track regressions.
- [CLI](/cli): The `amodal` CLI is the primary interface for building, running, and testing agents. Install it globally or use via `npx`:
- [amodal init](/cli/init): Initialize a new Amodal agent project. Creates the config file, directory structure, and starter files.