Agent Sessions for Orchestrated AI Workflows
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.”
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:
pm_session to start task-scoped agents with the right role, prompt, tools, and launcher presetThis 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.
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:
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.
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_sessionMCP reference for exact actions and parameters. - Open the Agent Sessions UI guide to see how transcripts, metadata, diffs, and terminals are inspected.
- Pair sessions with Workspace Knowledge when agents need cross-project context before they run.