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 choice is a one-line config change. Amodal supports Anthropic, OpenAI, and Google Gemini today, with automatic failover between providers. Adding a new provider is wiring in the corresponding @ai-sdk/* package — the runtime's provider interface is thin.

How is production hosted?

Amodal is operated as a hosted cloud product. Agent source lives in git, deployments run in managed infrastructure, and Studio 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?

amodal.json at the root of your agent repo:

{
  "name": "My Agent",
  "version": "0.1.0",
  "models": {
    "main": {
      "provider": "anthropic",
      "model": "claude-sonnet-4-20250514"
    }
  }
}

Swap the provider and model to change the intelligence. See Providers for the full list.

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

Three places, in order of weight:

  1. Skills (skills/*.md) — expert reasoning methodologies that activate based on the question
  2. Knowledge (knowledge/*.md) — persistent domain context the agent loads on demand
  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 Studio, hosted deployments, source control, operational logs, evals, usage tracking, and team access control.

The CLI is development tooling for working with agent source. Studio is the product surface for operating deployed agents.

Can I extend the runtime?

Yes, several ways:

  • Custom tools: Drop a handler.ts in 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 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 Studio to manage source, deploys, evals, and runtime configuration.

Is there a package ecosystem?

Yes. Install pre-built connections, skills, and tools from the registry:

amodal pkg install @amodalai/slack       # Slack connection
amodal pkg install @amodalai/stripe      # Stripe connection
amodal pkg install @amodalai/ops-pack    # Bundle of on-call skills

Packaged connections and skills drop into your connections/ and skills/ directories. Install once, use everywhere. Publish your own to the marketplace.

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 ops pipeline, or your vertical domain, use Amodal.

Can I use my own database?

Agents use Postgres-backed stores. Configure store schemas in your agent source and use Studio-managed deployment settings for the backing database:

{
  "stores": {
    "backend": "postgres",
    "postgresUrl": "env:DATABASE_URL"
  }
}

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 referenced from amodal.json with the env: prefix:

{
  "connections": {
    "stripe": { "auth": { "api_key": "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 ACLs via connections/<name>/access.json:

  • Mark endpoints allow, confirm, or deny
  • Mark fields hidden to strip them from responses
  • Require intent: "write" or "confirmed_write" on mutating HTTP methods
  • Rate limits per connection

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

How do I test an agent?

Evals. Define test cases in evals/*.md with LLM-judged assertions, run them with amodal eval, compare scores across models. See Evals.

Can automations run without the UI open?

Yes. Automations are cron/webhook-triggered and run in the runtime process. They execute independently of any connected chat client and can post results to external systems (Slack, webhooks). See Automations.

How do I debug when something's wrong?

  • Studio 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: Studio 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 is a standalone embeddable chat widget with SSE streaming, theming, and callbacks. No React required on the host page. See Chat Widget.