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

Quick Start

This guide walks through the cloud path: connect a GitHub repo, create an agent, deploy it, and verify it in Studio. The CLI exists for local development, but Studio is the primary product surface.

1. Connect GitHub

Open Studio, choose your organization, and connect GitHub from the agent creation flow.

The GitHub installation controls which repositories Amodal can see. If a repo does not appear, check the GitHub App installation and make sure the repo is selected there.

2. Create an Agent

Create a new agent from an existing repo or a starter template. An agent repo contains plain files:

amodal.json
connections/
skills/
knowledge/
stores/
pages/
automations/
evals/

amodal.json is the manifest. The folders define what the agent knows, what it can call, what UI it can render, what data it stores, what scheduled work it can run, and how it is evaluated.

3. Configure Models and Secrets

In Studio, open the agent settings and configure:

  • Model providers — Anthropic, OpenAI, Google, or another supported provider.
  • Secrets — connection credentials and provider keys.
  • Auth and embedding settings — how end users reach the deployed agent.
  • Deploy settings — whether source changes deploy automatically and how promotion works.

Secrets stay in the platform/deployment environment. Source files should reference secrets by name, not contain secret values.

4. Deploy

Open Source in Studio, inspect the repo, then deploy the current commit.

Studio separates source history from deploy history:

  • Source shows commits, branches, files, and diffs.
  • Deploys shows materialized deployments, runtime state, URLs, and which deploy is production.
  • Promote points the production URL at a selected deploy.

For a new agent, the first deploy creates the runtime. Before that, runtime-backed pages such as Sessions, Cost, Logs, and Chat may have no data to show.

5. Chat and Inspect

After deployment, open the agent chat in Studio or use the deployed agent URL. Ask a question that exercises a connection:

What happened in the incidents channel today?

Studio records the session so you can inspect:

  • Messages and tool calls
  • Scope and session IDs
  • Model and token usage
  • Runtime logs
  • Activity and deployment context

6. Edit and Redeploy

Open Source, edit a skill, knowledge file, connection doc, eval, page, or automation, then review the diff.

When you commit, Studio asks for:

  • Branch
  • Commit message
  • Deploy name
  • Promotion behavior

After the deploy finishes, the Deploys page shows the new runtime state and whether production points at it.

7. Add Evals

Add Markdown evals in evals/ and run them from Studio. Evals let you compare behavior across models and catch regressions before promoting a deploy.

Next Steps