Hooks & policies

Two mechanisms let you observe and constrain a Karta app without touching the harness: hooks (react to lifecycle events) and policies (validate messages before they run).

Hooks

Register a handler for a lifecycle event with @app.on(...). Handlers receive a HookEvent carrying the session, message, and any event-specific payload.

app = Karta()

@app.on("message.completed")
async def log_response(event):
    print(f"Session {event.session.id}: {event.message.text}")

@app.on("agent.handoff")
async def track_handoff(event):
    print(f"Handoff: {event.payload['from']} -> {event.payload['to']}")

Available events

Event	Fires when
`session.created`	A new session is opened.
`message.received`	An inbound message is accepted, before the turn runs.
`message.completed`	A turn finishes and the agent response is ready.
`agent.handoff`	A session’s `current_agent` changes.

Use hooks for logging, metrics, side effects (notify a channel on handoff), or enrichment - they observe the flow without owning it. Hook handlers are best-effort. Handlers fired by synchronous state changes, such as session.created and agent.handoff, may run after a later event. Exceptions are logged and do not fail the turn.

HookEvent field	Type	Meaning
`name`	`str`	Event name that fired.
`session`	`Session \| None`	Session associated with the event, when present.
`message`	`Message \| None`	Message associated with the event, when present.
`payload`	`dict`	Event-specific data, such as `{ "from": "...", "to": "..." }` for `agent.handoff`.
`timestamp`	`datetime`	UTC timestamp for the hook event object.

Policies

Policies validate messages against configurable rules before a turn runs - message counts and keyword gates.

app.policy("max_messages_per_session", 50)
app.policy("require_human_approval_for", ["refund", "delete account"])

A message that violates a policy is rejected before reaching the harness, so policy checks are cheap and deterministic - exactly the kind of guardrail you want in code rather than left to the model.

Policy	Value	Rejects when
`max_messages_per_session`	integer	The session message count exceeds the limit.
`require_human_approval_for`	list of strings	The inbound text contains one of the listed restricted intents.

max_tokens_per_session is accepted as a compatibility alias for max_messages_per_session; new code should use max_messages_per_session.

Hooks and policies run as part of Karta’s orchestration, around the harness. They do not see or alter conversation history (the harness owns that); they gate and observe the turns that flow through Karta. See How Karta works.

Python SDK

TypeScript

Chat Widget

Hooks & policies

Hooks

Available events

Policies

​Hooks

​Available events

​Policies

Hooks

Available events

Policies