Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Tasks and History

What you'll learn: What a task is, how history enables path-dependent policies, and how task lifecycle and memory management work.

What is a task?

A task is one end-to-end agent execution, identified by a task_id. It represents everything an agent does from start to finish for a single request, conversation turn, or job.

The task's history holds completed steps in completion order, followed by open intents in evaluation order. An intent is an allowed or warned step that has passed evaluate() but has not reached record(). Path-dependent policies see both, so a second preflight can account for a step still running.

Task lifecycle

start_task()
  |
  v
evaluate() -> execute -> record()    (repeat per step)
  |
  v
end_task()  or  error_task()

start_task()

Begins a new task. Returns a task_id. Optionally accepts a caller-provided task_id.

A framework handler (KyvvuLangChainHandler, KyvvuLangGraphHandler, KyvvuCrewAIListener) opens and closes its own task, and it raises KyvvuConfigError if a task is already active in the current context, so do not call start_task() around a handler. The handler closes only the tasks it opened.

The SDK emits a task.start Behavior that flows through the normal evaluate() path — step_execution policies run; agent_registration policies do not — those are evaluated once, at register_agent(), and never again.

evaluate() / record() cycle

For each step within the task:

  1. evaluate(intended, context) — checks the intended Behavior against policies and history. An allow or warn registers a step.* intent under its action_id; a block does not. The runner's evaluate() changes task history, while PolicyEngine.evaluate() and explain() only read it.

  2. The caller executes the step.

  3. record(completed_step) — settles the matching intent by action_id and appends the outcome to completed history. It assigns a monotonic step number in completion order. A recorded outcome with no open intent is appended as a replayed step.

For concurrent calls on one task, the runner completes each evaluation and intent registration before the next evaluation reads history. Recording an outcome uses the same task lock.

end_task(task_id)

Normal completion. The SDK emits a task.end Behavior through evaluate(), then calls the runner's end_task(). This:

  • Records each still-open intent with output.status of abandoned, preserving its action_id in the exported trace

  • Evicts the task's history from memory

  • Queues the task's buffered steps for delivery to the log endpoint (if configured). A background worker sends them; end_task() does not wait, so a short script calls kv.flush() before it exits

No policies run in end_task() itself — it is cleanup. To enforce task-end invariants, use policies that match on the task.end behaviour type.

error_task(task_id)

Abnormal termination. Same cleanup as end_task(), but emits a task.error Behavior first. History is evicted identically. Calling it for a task that is already closed raises KyvvuConfigError.

A block does not end the task

When a policy blocks a step, on any surface (@kv.step, kv.add_step, the framework handlers), the blocked step is recorded (output.status is blocked), KyvvuBlockedError is raised, and the task stays open. History is kept, so the taint, gate and sequence state the path rules read is intact. The caller chooses what happens next: error_task(), end_task(), or record an approval gate and retry in the same task. (A framework's own error callback, such as LangChain's on_chain_error once the exception propagates, closes the task the handler opened.) A task nobody closes is evicted by the sweeper (below).

Blocked, failed and abandoned attempts remain in history, and open intents appear in the in-flight tail. They can count for rules that forbid or count attempts, but none satisfies a requirement. step_requires_gate and step_requires_predecessor require a successful completed step; step_directly_preceded_by looks past attempts that cannot satisfy it.

Path-dependent evaluation

Because evaluate() reads the full task history, policies can express path-dependent constraints:

  • "Code execution requires a preceding gate" — step_requires_gate checks whether step.gate exists anywhere in history before step.exec.

  • "External content taint requires a fresh gate" — step_directly_preceded_by checks whether the immediately previous step was a step.gate.

  • "No more than 50 resource calls" — execution_max_steps counts step.resource entries in history.

  • "Forbidden sequence" — sequence_forbidden checks whether a specific ordered sequence has occurred.

The same step can be allowed or blocked depending on what happened earlier. This is the core of the "policies on paths" model.

Memory management

Task history lives in memory, keyed by task_id. Three mechanisms prevent unbounded growth:

Normal termination: end_task(task_id) evicts history from memory and queues the buffered logs for delivery.

Automatic background sweeper: A daemon thread calls sweep_stale_tasks() every KV_SWEEP_INTERVAL_SECONDS (default: 300s / 5 minutes). Tasks older than KV_TASK_MAX_AGE_SECONDS (default: 3600s / 1 hour) are evicted automatically — no manual wiring needed.

Pause-aware eviction: When a task records a task.idle Behavior (e.g., waiting for human input), the sweep TTL clock resets. This prevents idle-but-legitimate tasks from being evicted prematurely. If the task remains idle beyond a full TTL window with no further activity, it is still evicted.

Flush-before-evict: When the sweeper evicts an abandoned task, it attempts a best-effort batch post of the buffered steps to the log endpoint (if KV_SWEEP_FLUSH_ON_EVICT=true, which is the default). This captures partial traces for debugging even when tasks crash.

Config
Default
Purpose

KV_TASK_MAX_AGE_SECONDS

3600

Max age before a task is considered abandoned

KV_SWEEP_INTERVAL_SECONDS

300

How often the sweeper runs

KV_SWEEP_ENABLED

true

Set to false to disable automatic sweeping

KV_SWEEP_FLUSH_ON_EVICT

true

Post partial traces before discarding

A new task_id always starts with a fresh, empty history. Task histories are completely independent — there is no relationship between tasks.

Concurrent tasks

In web servers and concurrent agents, multiple tasks may be active simultaneously. The SDK uses a ContextVar to track the active task_id per execution context (thread or asyncio task). The @kv.step decorator automatically reads the active task ID from this context.

For explicit control:

Next steps

PreviousPolicies and Rules
NextTemplates

Last updated