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

Where does agent source live?

In a connected Git repository or Amodal-hosted snapshots. Both contain amodal.json and the agent's files. See Source & Deploy.

Can I change the model?

Yes. Configure provider access under Organization > Model Providers and choose an agent's model under Models. Model selection is an operational setting, separate from source files. See Providers.

Where do instructions and behavior come from?

Use AGENT.md for operating instructions, skills for task procedures, and knowledge for reference documents. Named agents declare which resources they can use.

A non-empty basePrompt in amodal.json overrides the normal compiled system prompt. Use agent instructions when you want to keep the platform's prompt scaffolding.

Can I run an agent locally?

Yes. The CLI runs an agent on your machine. Deploy production agents through Amodal or the Platform API.

Are sessions persistent across restarts?

Hosted sessions use platform-backed storage. Continue a conversation by sending its session_id.

Local development uses in-memory sessions and stores, so restarting the process loses that data. When embedding the runtime yourself, persistence depends on the storage you inject. See Session Lifecycle.

How do scope and session differ?

A session is one conversation. A scope partitions memory and non-shared store data for a tenant, user, or other application entity. Several sessions can be labeled with the same scope.

Token scope does not restrict session history or authorize resumed session IDs. For a multi-tenant product, keep runtime credentials on an application backend that authorizes each scope, session, and operation before proxying it. See Embedding & Multi-tenancy.

How do I handle secrets?

Keep secret values out of agent source. For example, a connection spec can reference an environment variable:

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

Configure the value in Amodal or your local environment. Connection authentication resolves the reference for API requests. Custom code can access credentials and produce output, so review handlers and avoid logging or returning secrets. See Guardrails.

How do I restrict API writes?

Set endpoint policies in amodal/connections/<name>/policy.json:

  • confirm: true asks for approval.
  • confirm: "review" refuses execution and requires a separate review workflow.
  • confirm: "never" blocks execution.

Listing read endpoints is not an allowlist for the whole API. Unmatched endpoints follow the default policy. Custom handler side effects need their own permission checks. See Confirmation Model and Connections.

How do I add capabilities?

  • Connections provide API access through OpenAPI operations, generic HTTP requests, or connection drivers.
  • Custom tools define actions and their handlers.
  • MCP servers expose external tools.
  • Packages provide reusable connections, skills, knowledge, stores, and tools.

How do I test behavior?

Write evals with example requests and assertions. Run them in Amodal, through the CLI, or through the Platform API. Use the results to check changes to instructions, tools, and models.

Can an agent work without an open chat client?

Yes. Platform-managed schedules and webhooks can start background runs. Agent Workflows covers work that needs durable steps, pauses, and resumes.

How do I investigate a failed run?

Open the session in Amodal to inspect messages, tool calls, usage, and errors. Check runtime logs for execution failures and deployment logs for build or startup failures. Use evals to reproduce behavior with a specific input.

Can I embed chat in my app?

Yes. Use the React SDK or ChatWidget. For multi-tenant use, connect through an application backend that authorizes scope and session access. See Embedding.