# Agent Sessions for Orchestrated AI Workflows
{{< badge content="Sovereign" color="purple" class="tier-badge" >}}

Agent Sessions are the runtime layer for Valdr. They turn agent work from one-off chats into persistent, inspectable execution that can be launched, routed, messaged, reviewed, and continued.

An Agent Session is a persistent runtime record for orchestrated agent execution. It carries the agent identity, role, provider configuration, task context, prompt, worktree policy, transcript, event stream, diff, and lifecycle state.

The powerful part is not just that Valdr can start an agent. It is that agents can launch other agents through MCP, inspect the results, send follow-up input, and keep the workflow moving. That is how an orchestrator can turn a planned task into execution, route it to review, request changes, and continue the chain without you manually copying prompts between tools.

This is the step from "I used an agent" to "my agent system can operate."

{{< callout type="info" >}}
**Sovereign tier required.** Agent Sessions are Sovereign because they turn Valdr from a place that tracks agent work into a runtime control plane that can launch agents, route context, message running sessions, and chain execution across a workflow.
{{< /callout >}}

## What this page covers

- What Agent Sessions add to Valdr
- How MCP launches make agent execution programmable
- How chained agent execution works
- What each session records for inspection and review
- How sessions pair with Workspace Knowledge and Agent Memory Notebooks
- Where to go for the MCP and UI references

## Why it matters

Ad-hoc agent runs usually depend on you to be the router. You paste the task into one agent, wait, copy the output to another agent, explain the review criteria, paste feedback back into the first agent, then manually inspect what changed.

Agent Sessions make that workflow explicit and repeatable:

{{< cards >}}
  {{< card title="Programmable launches" subtitle="Use `pm_session` to start task-scoped agents with the right role, prompt, tools, and launcher preset" icon="play" >}}
  {{< card title="Chained execution" subtitle="Let orchestrators dispatch executors, reviewers, auditors, and follow-up runs as the workflow advances" icon="switch-horizontal" >}}
  {{< card title="Inspect every run" subtitle="Open transcripts, events, metadata, worktree diffs, prompts, config, and live deltas" icon="eye" >}}
  {{< card title="Message running sessions" subtitle="Send clarification, review feedback, or updated constraints without abandoning the current run" icon="chat" >}}
{{< /cards >}}

This is programmable orchestration for persistent AI agent workflows: agents can be launched, observed, corrected, reviewed, and chained without losing the execution record.

## The session lifecycle

Every useful agent run has a lifecycle. Valdr makes each step visible and callable:

| Step | What happens | Why it matters |
|------|--------------|----------------|
| **Launch** | A session starts from a task, role, agent handle, launcher preset, and optional capabilities | The agent begins with structured context instead of a loose prompt |
| **Run** | The provider executes the session and emits events, messages, tool calls, commands, and deltas | Reviewers can inspect what the agent actually did |
| **Interact** | Operators or orchestrators can send input to a running or idle session | Feedback, follow-up instructions, and review decisions stay attached to one execution timeline |
| **Inspect** | Valdr stores prompt, config, transcript, metadata, diff, and worktree details | Debugging and approval use evidence, not memory |
| **Route** | The workflow can launch reviewer, auditor, or follow-up sessions | One agent's output becomes the next agent's input without manual handoff |
| **Close or restart** | Sessions can be aborted, restarted, or purged according to workflow policy | Operators keep control over long-running or failed work |

## Launching agents with MCP

Once workflows become programmable, orchestrators need a way to launch and control agents directly. In Valdr, that runtime entry point is `pm_session`. The high-level action for task execution is `launch_task`, which creates a task-scoped session and can run it immediately.

```text
pm_session {
  action: "launch_task",
  clientRequestId: "01HXYZ...",
  actor: "@skadi",
  taskKey: "VALDR-42",
  launcherConfigKey: "coder-codex",
  agentHandle: "coder-codex",
  capabilityKeys: ["valdr-executor"],
  additionalInstructions: "Focus on the failing build path first."
}
```

That launch can carry:

- Task description and acceptance criteria
- Agent identity and role
- Capability prompts and workflow instructions
- Provider and model configuration from the launcher preset
- Worktree policy and branch naming
- Runtime limits and configuration overrides
- Additional instructions for this specific run

The `clientRequestId` makes launches idempotent, so an orchestrator can retry safely without creating duplicate sessions.

## Chained execution

Chained execution is where Agent Sessions become a runtime control plane instead of a launch button. A Valdr orchestrator can move work through multiple specialized agents while preserving state at each handoff.

Example chain:

{{% steps %}}

### Plan the task

A planner turns a request into a task with requirements, acceptance criteria, and project context.

### Launch an executor

An orchestrator calls `pm_session { action: "launch_task" }` to start an executor session against the task. The executor works in its configured worktree and records a transcript, commands, and file changes.

### Start review

When execution finishes, the workflow can route the result to a reviewer session through the review flow. The reviewer sees the task, evidence, and session output instead of starting cold.

### Send feedback back

If review requests changes, the orchestrator can send input to the existing executor session or launch a follow-up session with targeted instructions.

### Audit the run

An auditor can inspect the session transcript, score the work, and attach findings before approval.

### Advance the workflow

Once review and audit gates pass, the orchestrator can move the task forward, clean up sessions according to policy, and launch the next task.

{{% /steps %}}

Each handoff is recorded. You can see who launched what, which prompt and config were used, what changed, and why the workflow advanced.

## What sessions record

Agent Sessions give reviewers and operators the evidence package they need:

| Record | Use it for |
|--------|------------|
| **Transcript** | Read agent messages, tool calls, command output, and lifecycle events |
| **Prompt** | Verify the exact system prompt and task context used at launch |
| **Config** | Inspect launcher preset, provider, model, tools, environment, and worktree settings |
| **Events** | Reconstruct execution order across messages, commands, and tool calls |
| **Live deltas** | Watch a running session stream output without waiting for completion |
| **Worktree diff** | Review the actual file changes produced by the session |
| **Metadata** | Check timing, status, role, provider, paths, and session identity |

That evidence is what makes chained agents reviewable. Without it, multi-agent execution turns into an opaque chain of handoffs.

## Pairing with Workspace Knowledge

Agent Sessions and Workspace Knowledge reinforce each other:

- **Workspace Knowledge** gives launched agents project docs, source context, code map queries, and cross-project search.
- **Agent Memory Notebooks** preserve discoveries and project-specific decisions for future sessions.
- **Agent Sessions** turn that context into executable work with transcripts, diffs, reviews, and follow-up inputs.

Together, they let a Sovereign workflow do more than run a prompt. It can investigate, execute, review, remember, and continue.

## Guardrails

Session control is powerful, so Valdr keeps the workflow explicit:

- Session MCP actions are Sovereign-gated.
- Task launches use launcher presets instead of ad-hoc provider configuration.
- Launches should use idempotency keys to avoid duplicate work.
- Worktree policy is part of the session config, so changes stay inspectable before merge.
- Inputs sent to running sessions are recorded in the session timeline.
- Purge is destructive and should be handled intentionally.

These guardrails let agents chain execution without hiding what happened from the operator.

## Next steps

- Read the [`pm_session` MCP reference](/valdr/docs/valdr-mcp/sessions/) for exact actions and parameters.
- Open the [Agent Sessions UI guide](/valdr/docs/ui/agent-sessions/) to see how transcripts, metadata, diffs, and terminals are inspected.
- Pair sessions with [Workspace Knowledge](/valdr/docs/features/knowledge/) when agents need cross-project context before they run.