Agent Sessions for Orchestrated AI Workflows
Agent Sessions let you launch, inspect, message, review, and continue agent work while keeping its history in one place.
Each session records who ran the work, the role and provider settings, task context, instructions, working directory, transcript, file changes, and current status.
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 provider 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, provider preset, and optional capabilities | The agent begins with structured context instead of a loose prompt |
| Run | The agent works while messages, tool calls, commands, and live output appear in the session | 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
Orchestrators can use pm_session to launch and control agents directly. The launch_task action creates a session with task context 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 provider 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.
Choose Claude, Codex, OpenCode, or Ollama through a registered provider preset. OpenCode sessions use your native models, authentication, agents, plugins, and MCP configuration. See Providers & Presets for setup and migration from the removed direct Gemini, OpenAI API, and Anthropic API providers.
Queue follow-ups or steer active work
Session chat defaults to Queue: the agent receives your follow-up on its next turn. Choose Steer to redirect a supported active Codex or Claude ad-hoc turn while it works. OpenCode supports queued continuation; workflow-owned turns do not accept steering. Valdr retains your message if steering fails or delivery cannot be confirmed.
The same choice is available through pm_session.input using delivery: "queue" or "steer". See the session MCP reference for request IDs and delivery receipts, or Reply to agent for the UI controls.
Chained execution
A Valdr orchestrator can move work through multiple specialized agents while preserving context and history 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 provider 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 provider 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.