Orchestration History Agent

System Run Ledger & Observability Interface · GET /v1/agent/orchestrator/history

Category: Core Observability · Execution Model: Read-only, Deterministic, Immutable

Purpose

The Orchestration History Agent provides a canonical, immutable record of all orchestrator executions. It functions as the system’s authoritative audit log, enabling debugging, performance analysis, failure inspection, and learning verification across the entire multi-agent pipeline. Every orchestration run produces exactly one history document, capturing execution state, participating agents, structured errors, and contextual metadata generated during runtime.

Expected Inputs

limit number — default: 10
Maximum number of orchestration runs to return. Results are ordered by most recent execution first.

Outputs

HTTP Response

{
  "message": "string",
  "count": "number",
  "data": [
    {
      "_id": "ObjectId",
      "runType": "\"weekly-discovery\" | \"manual\"",
      "status": "\"pending\" | \"success\" | \"partial\" | \"failed\"",
      "startedAt": "ISODate",
      "finishedAt": "ISODate | null",
      "agentsTriggered": "string[]",
      "fauxSessionsGenerated": "number",
      "notes": "string | null",
      "errors": [
        {
          "agent": "string",
          "message": "string",
          "stack": "string | null"
        }
      ],
      "meta": "object",
      "createdAt": "ISODate",
      "updatedAt": "ISODate"
    }
  ]
}

Side Effect
```
None (read-only interface)
```
Side Effect
```
No state mutation or downstream writes
```

Responsibilities

Expose recent orchestration runs for diagnostics and review
Provide visibility into agent execution order and participation
Surface structured, per-agent error information
Enable inspection of partial and failed orchestration runs
Serve as a trusted data source for analytics and learning validation

Lifecycle

Orchestrator initializes a history record at run start (status: pending)
Agents execute sequentially under orchestrator control
Errors and metadata are appended during execution
Run status is finalized (success | partial | failed)
History record becomes immutable and queryable

Downstream Dependencies

Learning Agent (indirect)
Analytics & Monitoring Systems
Human Operators & Debugging Tools

Guarantees

One immutable history record per orchestrator run
Runs are returned in reverse chronological order
Returned data reflects finalized execution state only

Failure Model

This agent does not fail partially. If the database is reachable, it returns the most recent orchestration records. If retrieval fails, a 500 error is returned with no side effects or state changes.

Internal State

{
  "persistence": [
    "OrchestrationHistory"
  ],
  "guarantees": [
    "History records are append-only",
    "Completed runs are never mutated",
    "Each orchestrator execution maps to exactly one history record"
  ]
}

Sample cURL


curl -X GET https://api.whook.ai/v1/agent/orchestrator/history