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.
Karta is the core class. It detects your harness, discovers agents and skills,
holds session handles, and exposes send/stream in sync and async forms.
Construct
Karta(
project_path: str | Path = ".",
*,
harness: HarnessAdapter | None = None, # override auto-detection
runnable: Runnable | None = None,
)
app = Karta() # detect harness in the current directory
app = Karta("./my-app") # point at a folder
app = Karta.from_path("./my-app") # explicit classmethod
karta.jsonc if present,
and discovers agents and skills from the harness.
Properties
Discovered agents, keyed by name.
The fallback agent used when none is specified.
Discovered skills and their metadata.
The current user profile (from karta.jsonc or the OS user).
Sending turns
All four take the same keyword arguments: metadata, agent, session_id,
participant, thinking.
async def send(text, *, metadata=None, agent=None, session_id=None,
participant=None, thinking=False) -> Response
def send_sync(...) -> Response
async def stream(...) -> AsyncIterator[StreamEvent]
def stream_sync(...) -> Iterable[StreamEvent]
resp = app.send_sync("Audit invoice #789", agent="billing-specialist")
print(resp.text)
async for event in app.stream("Explain quicksort", thinking=True):
if event.type == "text":
print(event.text, end="", flush=True)
Response carries text, the user and assistant messages, the agent that
handled the turn, and usage (input_tokens, output_tokens, total_tokens).
Opening a session
def session(metadata=None, *, harness_args=None) -> Session
session = app.session(metadata={"customer_id": "abc123"})
session.send_sync("I need help with my order")
Hooks
Register handlers for lifecycle events: message.received,
message.completed, agent.handoff, session.created.
@app.on("message.completed")
async def log_response(event):
print(event.session.id, event.message.text)
Policies
def policy(self, name: str, value) -> None
app.policy("max_message_length", 4000)
