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

# Agents

> What you actually ship: an agent project that a harness can run - and how Karta detects, packages, and runs it.

An **agent** is the deployable unit Karta runs and manages: an agent project
that configures an agent harness. It is the folder with a native instruction
file (`CLAUDE.md` or `AGENTS.md`) and the harness's own config directory,
packaged so Karta can run it for users, virtual employees, backend jobs, and
fleet members.

You may hear this project shape called a **harness application**: the
application is the folder, and the harness is the runtime that executes it. In
Karta's product, CLI, API, and docs, the normal term is **agent** or **agent
project**.

<Note>
  "Agent" is the term everywhere - in prose, the CLI, the HTTP API, and the
  SDK (`karta agent list`, `karta agent show`). It names the folder you ship.
  Use "agent project" when you need to emphasize the folder. Use "harness
  application" only when you are explicitly contrasting the project with the
  **agent harness** that runs it, or with the
  [sub-agents](/build/defining-agents) defined inside it. See
  [Supported harnesses](/build/supported-harnesses) for the current harness
  formats Karta detects and runs.
</Note>

## Anatomy

The minimum is a single instructions file. Everything else is additive.

<CodeGroup>
  ```text Claude Code theme={null}
  my-agent/
  |-- CLAUDE.md              # agent instructions (the one required file)
  |-- .claude/
  |   |-- agents/            # sub-agents, one .md each
  |   |   |-- billing.md
  |   |   `-- shipping.md
  |   |-- skills/            # skills the agent can invoke
  |   `-- settings.json      # harness settings (tools, permissions, MCP)
  |-- karta.toml             # optional: deploy/build hints
  `-- karta.jsonc            # optional: Karta CLI/runtime settings
  ```

  ```text OpenCode theme={null}
  my-agent/
  |-- AGENTS.md              # shared context
  |-- .opencode/
  |   |-- agents/            # sub-agents, one .md each
  |   |-- skills/            # SKILL.md per skill
  |   `-- opencode.jsonc     # harness config (incl. default_agent)
  |-- karta.toml             # optional: deploy/build hints
  `-- karta.jsonc            # optional: Karta CLI/runtime settings
  ```

  ```text DeepAgents theme={null}
  my-agent/
  |-- AGENTS.md
  |-- .deepagents/
  |   |-- agents/
  |   `-- karta.jsonc
  |-- karta.toml
  `-- karta.jsonc
  ```

  ```text Goose theme={null}
  my-agent/
  |-- AGENTS.md
  |-- .goose/
  |   |-- agents/
  |   `-- karta.jsonc
  |-- karta.toml
  `-- karta.jsonc
  ```

  ```text Codex CLI theme={null}
  my-agent/
  |-- AGENTS.md
  |-- .codex/
  |   |-- agents/
  |   `-- config.toml
  |-- karta.toml
  `-- karta.jsonc
  ```
</CodeGroup>

The agent definitions stay in the **harness's own native format**. Karta reads
the files the harness already understands instead of asking you to translate
them into a separate Karta-only agent-definition format.

Karta starts after this project exists. You author and test the agent in your
own repo, IDE, harness, model setup, and evaluation loop; Karta packages that
project into releases and runs it as durable kartas in production.

## Harness detection

Karta auto-detects the harness from the folder layout, so you rarely specify it
explicitly:

| Signal                                  | Harness              |
| --------------------------------------- | -------------------- |
| `.claude/` directory **or** `CLAUDE.md` | Claude Code          |
| `.opencode/` directory                  | OpenCode             |
| `.deepagents/` directory                | DeepAgents           |
| `.goose/` directory                     | Goose                |
| `.codex/config.toml`                    | Codex CLI            |
| neither                                 | defaults to OpenCode |

Karta detects which supported harness your agent uses from its layout,
discovers agents from that harness's format, and streams each turn through
Karta's [event model](/concepts/streaming-events). `karta create --harness`
writes the native marker files when you scaffold a new agent from the CLI. See
[Supported harnesses](/build/supported-harnesses) for the full list.

If a folder carries mixed harness markers, declare the harness explicitly in
[`karta.toml`](/build/karta-toml). Mixed layouts are difficult for teammates and
CI to reason about.

## What the harness owns vs. what Karta owns

<Columns cols={2}>
  <Card title="The harness owns" icon="robot">
    Conversation history, session persistence and resumption, tools, MCP
    servers, memory, context management, skills, and the agent loop.
  </Card>

  <Card title="Karta owns" icon="layer-group">
    Durable karta identity, workspace boundaries, session *handles*,
    participant attribution, release routing, policies, and lifecycle hooks -
    plus the platform: HTTP/CLI/SDK surface, multi-tenancy, metering, budgets,
    BYOK, webhooks, and releases.
  </Card>
</Columns>

## Configuration files

Two optional files tune behavior without touching your agent definitions:

* **`karta.toml`** - your agent's deploy identity and build settings: its `name`,
  the `deploy` gate, entry point, and buildpack. See the
  [`karta.toml` reference](/build/karta-toml).
* **`karta.jsonc`** - Karta-specific CLI, harness, and runtime settings (hidden
  event types, approval policy, idle timeouts, thinking budget). See
  [Configuration](/build/configuration).

Neither is required to run locally.

## Next

<CardGroup cols={2}>
  <Card title="Agent structure" icon="folder-tree" href="/build/agent-structure">
    Lay out a real agent, file by file.
  </Card>

  <Card title="Sub-agent files" icon="users-gear" href="/build/defining-agents">
    The `.md` frontmatter format for sub-agents.
  </Card>
</CardGroup>