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

FAQ

For architectural positioning vs. Vercel AI SDK, LangChain, Mastra, and raw provider SDKs, see What is an agent?.

Does Amodal lock me into a specific LLM provider?

No. Provider credentials, allowlists, and current model selection are managed from Amodal/platform settings. The runtime uses a provider-agnostic interface, so agent source files do not need provider-specific code.

How is production hosted?

Amodal is operated as a hosted cloud product. Agent source lives in git, deployments run in managed infrastructure, and Amodal provides the operational interface for sessions, evals, costs, activity, runtime logs, source history, and deploy promotion.

Local development exists for fast iteration, but production agents should be deployed and operated through Amodal Cloud.

Where's the intelligence configured?

In Amodal. Configure organization-level model providers under Organization > Model Providers, then inspect or change an agent's active model from Agent > Models. Model selection is operational runtime state, not committed agent source.

Where does the agent's "personality" and behavior come from?

Three places, in order of weight:

  1. Skills (amodal/skills/<name>/SKILL.md) — expert reasoning methodologies that activate based on the question
  2. Knowledge (amodal/knowledge/*.md) — persistent domain context loaded into the agent prompt
  3. basePrompt in amodal.json — custom base system prompt that replaces the platform default

All three get compiled into the system prompt before every LLM call.

Is Amodal a framework or a platform?

Both. The runtime is the engine — a state-machine agent loop with provider, tool, store, and session systems. Amodal Cloud wraps that engine with Amodal, hosted deployments, source control, operational logs, evals, usage tracking, and team access control.

Amodal is the product surface for operating deployed agents. The Platform API is the automation surface for external tools and agentic coding workflows.

Can I extend the runtime?

Yes, several ways:

  • Custom tools: Drop a tool.ts in amodal/tools/<name>/ and it's available to the agent. See Tools.
  • MCP servers: Connect any MCP server and its tools are discovered automatically. See MCP Servers.
  • Custom connections: Define an OpenAPI-style spec in amodal/connections/<name>/ to expose a new HTTP API to the agent. See Connections.
  • Embedded chat: Use the React SDK or widget to embed a deployed agent in your application. See SDK Overview.
  • Platform APIs: Use cloud APIs and Amodal to manage source, deploys, evals, and runtime configuration.

Is there reusable package content?

Yes. Agent packages can provide reusable connections, skills, knowledge, stores, and tools. Declare packages in amodal.json#packages, then add local files under amodal/connections/, amodal/skills/, amodal/knowledge/, amodal/stores/, or amodal/tools/ when the agent needs project-specific behavior.

How does the runtime compare to Claude Code, Cursor, Aider?

Those are coding agents — the domain is "your codebase" and the tools are file editing, shell commands, and git. They're opinionated products.

Amodal is a runtime for building domain-specific agents. You specify the domain (via connections, skills, knowledge). The domain isn't code — it's whatever you want: SOC compliance, payment investigation, customer support, HR recruiting, ops incident response.

If you want a coding agent, use Claude Code or Cursor. If you want to build an agent that lives inside your SaaS product, your operations workflow, or your vertical domain, use Amodal.

Can I use my own database?

Agents use Postgres-backed stores. Define store schemas in amodal/stores/*.json and use Amodal-managed deployment settings for the backing database.

Postgres is required for durable sessions, stores, activity, and runtime logs.

Are sessions persistent across server restarts?

Yes. Sessions are stored durably and can continue across deploys. A deploy changes the code and configuration available to the agent; it should not force a user to restart a conversation.

How do I handle secrets?

Environment variables can be referenced from repo files with the env: prefix:

{
  "baseUrl": "https://api.stripe.com",
  "auth": {
    "type": "bearer",
    "token": "env:STRIPE_API_KEY"
  }
}

Secrets are resolved at startup and held only in memory. They never appear in logs, the LLM prompt, or deployment snapshots. See Security & Guardrails.

How do I prevent the agent from making destructive API calls?

Connection policies live in amodal/connections/<name>/policy.json:

  • Omit confirm for read endpoints that can run without approval
  • Use confirm: true for writes that need user approval
  • Use confirm: "review" when the user should approve the full plan first
  • Use confirm: "never" to block an endpoint
  • Use fieldRestrictions to remove or redact sensitive fields

The runtime enforces these rules before tool calls execute. See Confirmation Model, Security & Guardrails, and Connections.

How do I test an agent?

Evals. Define test cases in evals/*.md with LLM-judged assertions, then run them from Amodal or the Platform API to compare behavior across models. See Evals.

Can background runs happen without the UI open?

Yes. Scheduled and webhook-triggered background runs are platform-managed and execute independently of any connected chat client.

How do I debug when something's wrong?

  • Amodal logs: Use runtime logs and activity logs to inspect tool calls, state transitions, errors, deploys, and operator actions.
  • Inspect endpoints: GET /inspect/context shows the compiled system prompt, active skills, and loaded knowledge. /inspect/connections/:name shows a connection's resolved spec.
  • Session replay: Amodal shows conversation history, tool calls, costs, scopes, and deployment context for debugging.

Is there a chat widget I can drop into my own web app?

Yes. @amodalai/react/widget ships ChatWidget, an embeddable chat surface with SSE streaming, theming, and callbacks; it renders with React (a dependency of your app), and the subpath keeps the embed from importing the whole SDK. See Chat.