Skip to main content
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.
“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 defined inside it. See Supported harnesses for the current harness formats Karta detects and runs.

​
Anatomy

The minimum is a single instructions file. Everything else is additive.
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: 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. karta create --harness writes the native marker files when you scaffold a new agent from the CLI. See Supported harnesses for the full list. If a folder carries mixed harness markers, declare the harness explicitly in karta.toml. Mixed layouts are difficult for teammates and CI to reason about.

​
What the harness owns vs. what Karta owns

The harness owns

Conversation history, session persistence and resumption, tools, MCP servers, memory, context management, skills, and the agent loop.

Karta owns

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.

​
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.
  • karta.jsonc - Karta-specific CLI, harness, and runtime settings (hidden event types, approval policy, idle timeouts, thinking budget). See Configuration.
Neither is required to run locally.

​
Next

Agent structure

Lay out a real agent, file by file.

Sub-agent files

The .md frontmatter format for sub-agents.