> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opencomputer.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents

> Reusable agent configuration

An **agent** is a reusable identity, runtime, model, and deployed behavior. Every [session](/agent-sessions/sessions) runs on an agent, so create one first, then start as many sessions on it as you like. Every agent also has one permanent [Agent URL](/agent-sessions/agent-urls): a trusted backend can invoke its root with an OpenComputer key, and external systems can use named, revocable [Hook URLs](/agent-sessions/hooks). For the built-in runtimes, behavior is `prompt` plus optional skills and is frozen into independently routable [revisions](/agent-sessions/revisions). A [Flue](/agent-sessions/flue) agent instead carries its instructions, tools, and packaged skills in a compiled Flue app.

<Note>
  The [dashboard](https://app.opencomputer.dev) starts with **Import from
  GitHub** and keeps **Configure manually** available. Repository import
  recognizes both a complete [Flue](/agent-sessions/flue) app and a
  prompt-defined Flue root containing `agent.toml`, `prompt.md`, and optional
  `skills/`. You can also deploy either local shape with `oc agent deploy`;
  prompt-defined roots build in the isolated managed builder, while complete
  apps build locally. Both paths produce the same deployment and revision
  history.
</Note>

<CodeGroup>
  ```ts TypeScript SDK theme={null}
  import { OpenComputer } from "@opencomputer/sdk";

  const oc = new OpenComputer({ apiKey: process.env.OPENCOMPUTER_API_KEY! });

  const agent = await oc.agents.create({
    name: "reviewer",
    runtime: "claude",
    model: "anthropic/claude-opus-4-8",
    prompt: "Review the repo. Run tests. Summarize risks.",
    key: "sk-ant-...",
  });
  ```

  ```http REST API theme={null}
  POST https://api.opencomputer.dev/v3/agents
  Authorization: Bearer $OPENCOMPUTER_API_KEY
  Content-Type: application/json

  {
    "name": "reviewer",
    "runtime": "claude",
    "model": "anthropic/claude-opus-4-8",
    "prompt": "Review the repo. Run tests. Summarize risks.",
    "key": "sk-ant-..."
  }
  ```
</CodeGroup>

Pass your model `key` inline and it's stored as a [credential](/agent-sessions/credentials) and attached to the agent — sessions run the model on it. The provider is taken from `model` (Anthropic for `anthropic/…`, OpenAI for `openai/…`), so the key has to be for that provider. Already have a credential? Reference it with `credential: "cred_…"` instead. Or skip keys entirely with `credential: "managed"` to run the model **via OpenComputer, billed to your credits** (the default for new orgs). Omit both `key` and `credential` to use your org default. Optionally set default [`limits`](/agent-sessions/sessions#usage-and-limits) (`tokens`/`turn_seconds`/`turns`) too; sessions inherit them.

<Tip>
  Keep the org key and model key on your backend. Only return session-scoped
  client tokens to browsers.
</Tip>

## Start simple, add capability as you go

For a built-in runtime, the only behavior an agent needs is a **model** and a **prompt**. Everything beyond that is additive: reach for a rung only when you need it, and nothing earlier is undone. Flue has a separate [app deployment path](/agent-sessions/flue#add-opencomputer-to-a-flue-app).

| Rung                                 | What you add                                                                                                  | What you get                                                                                                   |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| **Default agent**                    | `name` + `model` (+ a prompt)                                                                                 | a working agent on the default runtime — no setup                                                              |
| **+ Skills**                         | [`SKILL.md` folders](/agent-sessions/skills) (upload a `.zip`, or include in a repo)                          | reusable procedures the agent loads when relevant — still the default runtime                                  |
| **+ Source-controlled deployment**   | link a built-in agent to `prompt.md` + `skills/`, or import a prompt-defined or complete Flue app from GitHub | versioned [deployments and revisions](/agent-sessions/revisions); Flue imports also include durable build logs |
| **+ Custom runtime** *(coming soon)* | bring your own runtime image                                                                                  | full control of the execution environment                                                                      |

At every built-in rung the agent is a small directory, at most `agent.toml` + `prompt.md` + `skills/`. You can stop at any rung; most agents never go past skills.

## Create from a repository

Choose **Agents → Create agent → Import from GitHub**, install the OpenComputer GitHub App if needed, and select a repository, production branch, and root. **Review agent** resolves one exact commit without running repository code.

* A prompt-defined or complete Flue root shows its entrypoint, model, Managed model access, and an editable OpenComputer agent name.
* A broken Flue root explains what must be fixed. OpenComputer does not reinterpret it as another agent type.
* An unrecognized root creates nothing. You can choose another folder, fork the Flue starter, or configure a built-in agent manually.
* In a monorepo, OpenComputer may suggest bounded candidate folders. You choose one explicitly and review it before deployment.

Review and import are intentionally separate. Import rechecks the exact source plan; if the repository changed in between, nothing is created and the dashboard asks you to review again. A successful import returns the new agent and its first deployment immediately, then opens guided setup instead of making you wait on a log screen. Connect Slack while the deployment continues in the background; its compact phases and expandable log remain available. When both are ready, setup changes to **Open Slack** without a refresh and invites you to send the first message. Manually configured agents use the same setup journey.

If one of your Slack workspaces already sends messages to another agent, setup
shows that claim before OAuth. Open the connected agent, choose another
workspace, or disconnect it in place after reviewing the routing impact. A
completed first conversation adds direct exits to the agent home, full session,
session history, and Slack.

For a Flue agent, setup also offers **Working repositories** without blocking
Slack or chat. Choose all repositories granted to the OpenComputer GitHub App,
an explicit subset, or an empty subset for chat-only use. The same policy is
available later under **Agent → Settings → Repository access**. This policy is
separate from the repository that deploys the Flue app.

The repository picker marks roots already used by another agent before review.
An exact linked root cannot be reviewed again: open its owning agent, choose a
different monorepo root, or unlink it in place after confirming that
deploy-on-push will stop. Unlinking preserves the existing agent, active
revision, deployment history, and sessions. Guided setup remains available from
the agent page; after the first Slack message creates a session, it shows the
first conversation and links to the complete session view.

## Session-pinned config

For a built-in runtime, creating a session **freezes** the agent's active [revision](/agent-sessions/revisions), including its `prompt`, `model`, `runtime`, and `skills`. It also pins the resolved credential. A one-off [`model`](/agent-sessions/sessions#model) override is pinned in the same way. Editing the named agent does not change a running or resumed session: existing sessions keep what they started with, while new sessions pick up the change. Rotating a credential's **key value** is the exception, so a compromised key can be replaced; see [credentials](/agent-sessions/credentials).

That isolation applies to the built-in runtimes. A Flue session records the selected deployment, but all sessions for that agent execute on its one live Worker. Deploying a new Flue Worker can therefore change existing sessions; see [Flue deployment behavior](/agent-sessions/flue#deployment-and-revision-behavior).

## Model

`model` is a `provider/model` id, and its provider must match the [runtime](/agent-sessions/runtimes): `claude` runs `anthropic/…` (e.g. `anthropic/claude-opus-4-8`), `codex` runs `openai/…` (e.g. `openai/gpt-5-codex`). The model runs either **Managed** (via OpenComputer, billed to your credits — no key) or on [your own key](/agent-sessions/credentials) for that provider, so a key isn't required. The `runtime` / `model` / credential pairing is validated when you **create** the agent. `runtime` is fixed at creation — to switch engines, create a new agent; you can still update `model` later, but keep it within the runtime's provider.

Flue currently uses Managed Anthropic access. Its model is declared in both the compiled app and `agent.toml`; per-session model overrides are not supported.