Skip to main content

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.

An agent in Karta is a thin wrapper over an AgentDefinition that the harness adapter discovers from your project. You don’t define agents in Karta’s own format — you define them the way your harness already expects, and Karta reads them.

​
Where agents come from

HarnessAgent filesShared context
Claude Code.claude/agents/*.mdCLAUDE.md (or AGENTS.md)
OpenCode.opencode/agents/*.mdAGENTS.md
Each agent is a Markdown file with YAML frontmatter and a prompt body:
.claude/agents/billing.md
---
name: billing-specialist
description: Handles invoice and billing questions
model: claude-sonnet-4-6        # optional
temperature: 0.3                 # optional
tools:                           # optional
  read: true
  write: false
permissions:                     # optional
  skill:
    billing-lookup: allow
type: primary                    # primary | auxiliary
---

You are a billing specialist. Help customers with invoices and charges.
Be precise, cite invoice numbers, and never guess at amounts.
The discovered definition exposes name, description, prompt, optional model, tools, skills, permissions, temperature, and type. With a single agent, it’s selected automatically; with several, you route by name.

​
Routing

Send a turn to a named agent, or let the default handle it: 
from karta import Karta

app = Karta()

app.agents                 # {"billing-specialist": Agent, "shipping": Agent, ...}
app.default_agent          # the fallback when none is specified

# Route a one-off message to a specialist:
response = app.send_sync("Audit my last invoice", agent="billing-specialist")

​
Handoff within a session

A session has a current agent. Reassign it to hand off mid-conversation; the change fires an agent.handoff hook. 
session = app.session(metadata={"customer_id": "abc123"})
session.send_sync("I have a question about my order")   # → default agent
session.current_agent = app.agents["billing-specialist"] # handoff
session.send_sync("Was invoice #789 charged twice?")    # → billing specialist
This is how you build a triage-and-specialist topology: a generalist greets and classifies, then hands the thread to the right expert without losing context — because the session and its history carry across the handoff.

​
Agents as principals

When a deployed harness app runs, the agent is itself an actor with shell and tool access — it can be steered by end-user input or by data it fetches (prompt injection). The data plane issues it a distinct principal at runtime, and its authority is explicitly bounded and scoped to the current end user, never inherited ambiently. See Personas & trust boundaries.

Define agents

The full frontmatter format and conventions.

Skills

Give agents reusable capabilities.