Multi-Agent Sessions

Link parent and child agents into a unified session tree.

The tree model

In many real-world systems, agents delegate work to other agents. AOP models this as a tree of sessions. Every session has an optional parent_session_id field. When set, it declares that this session was spawned by the parent.

orchestrator
│spawn↓
researcher
│spawn↓
writer
│spawn↓
editor
│spawn↓
reviewer

The collector and dashboard use this tree to show the full execution graph — you can see which agent spawned which, what goals were delegated, and how the work flowed.

Setting parent_session_id

Pass parentSessionId when constructing the child agent's AOPClient:

// Parent agent
const parent = new AOPClient({ agentId: 'orchestrator' })
await parent.sessionStarted({ goal: 'Write a report' })

// Spawn a child agent
const childSessionId = await parent.agentSpawn('researcher', {
  goal: 'Gather sources'
})

// In the child agent process
const child = new AOPClient({
  agentId: 'researcher',
  sessionId: childSessionId,
  parentSessionId: parent.sessionId
})
await child.sessionStarted({ goal: 'Gather sources' })

operation.agent_spawn

The parent emits an operation.agent_spawn event when it creates a child. This event links the two sessions in the tree and records the delegation intent.

{
  "type": "operation.agent_spawn",
  "payload": {
    "child_session_id": "sess_researcher",
    "child_agent_id": "researcher",
    "goal": "Gather sources"
  }
}

AOPClient.agentSpawn()

The SDK provides a convenience method that emits the spawn event and returns a fresh session ID for the child:

const childSessionId = await aop.agentSpawn(
  'child-agent-id',        // agentId of the child
  { goal: 'Sub-task' }     // optional metadata
)
// childSessionId is a new UUID you pass to the child's AOPClient

This method:

  • Generates a new session ID for the child
  • Emits operation.agent_spawn with the child's session ID and agent ID
  • Returns the child session ID so you can pass it to the child process

Dashboard visualization

The dashboard renders multi-agent sessions as a collapsible tree. Each node shows the agent ID, session status, and goal. Clicking a child session navigates into its event feed while maintaining the tree context in the sidebar.

Related