Sub-agents

A sub-agent is an optional harness-native role inside one agent project. For Claude Code, it is usually a .claude/agents/*.md file; for OpenCode, it is the equivalent .opencode/agents/*.md file. Karta discovers those files and lets sessions route to them, but it does not deploy them as separate top-level agents with their own stable URLs.

Where sub-agents come from

Harness	Agent files	Shared context
Claude Code	`.claude/agents/*.md`	`CLAUDE.md` (or `AGENTS.md`)
OpenCode	`.opencode/agents/*.md`	`AGENTS.md`

Each sub-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 sub-agent, it is selected automatically; with several, you route by name.

Routing

Send a turn to a named sub-agent, or let the default handle it. The API field is still named agent because it names the harness actor for that turn:

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 sub-agent:
response = app.send_sync("Audit my last invoice", agent="billing-specialist")

Handoff within a session

A session has a current sub-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 a general intake agent can hand a thread to a specialist without losing context. The session and its history carry across the handoff.

Runtime authority

When a deployed agent runs, the resulting karta - a durable computer for a user-agent relationship, virtual employee, backend job, account role, or fleet member - is itself an actor with shell and tool access. It can be steered by user input or by data it fetches (prompt injection). Karta treats it as its own actor: its authority is scoped to the current karta and session, not the platform, so a prompt-injected or misbehaving karta is contained to its own boundary.

Sub-agent files

The full frontmatter format and conventions.

Skills

Give agents reusable capabilities.

Get started

Concepts

Agent project

The CLI

Deploy

Platform

Security

Enterprise

Tutorials

Where sub-agents come from

Routing

Handoff within a session

Runtime authority

Sub-agent files

Skills

​Where sub-agents come from

​Routing

​Handoff within a session

​Runtime authority

Sub-agent files

Skills

Where sub-agents come from

Routing

Handoff within a session

Runtime authority