Session - Karta

A Session is a lightweight handle for a multi-turn conversation. You don’t construct it directly — app.session(...) returns one. It carries metadata, participants, and the current agent, but holds no messages (the harness does). See the concept page for the model.

Create

session = app.session(metadata={"customer_id": "abc123"})

Fields

Field	Type	Meaning
`id`	`str`	Session identifier (maps to a harness thread).
`metadata`	`dict`	Arbitrary key/values; route and look up by these.
`status`	`str`	`active`, etc.
`participants`	`list[Participant]`	Humans and AIs in the session.
`current_agent`	`Agent \| None`	The agent handling turns now.
`pending_input`	`dict \| None`	A `request_id` awaiting an approval decision.
`permission_mode`	`str \| None`	How approval prompts are handled.
`parent_id`	`str \| None`	Parent session, for sub-sessions.

Send and stream

async def send(text, *, participant=None, thinking=False) -> Response
def      send_sync(...) -> Response
async def stream(...) -> AsyncIterator[StreamEvent]
def      stream_sync(...) -> list[StreamEvent]

session.send_sync("I need help with my order")
session.send_sync("It's order #12345")     # same thread

Participants

from karta import HumanAgent

alice = HumanAgent(name="alice", display_name="Alice Chen")
session.add_participant(alice)
session.send_sync("Looking into it now", participant=alice)

Each message is attributed to its sending participant. Multiple humans and AIs can share one session.

Agent handoff

Assigning current_agent fires the agent.handoff hook:

session.current_agent = app.agents["billing-specialist"]
session.send_sync("Was invoice #789 charged twice?")

Resolving approvals

When a turn pauses with an input_required event, resolve it and continue streaming:

async for event in session.stream_pending_input("approve_once", request_id=req_id):
    if event.type == "text":
        print(event.text, end="")

Decisions are approve_once, approve_session, or deny.

Documentation Index

​Create

​Fields

​Send and stream

​Participants

​Agent handoff

​Resolving approvals