Traceability & Audit Log

A full compliance trail for Agent Builder: who changed a workflow or skill and what changed, plus a tool-call-by-tool-call record of what happened during any run — including calls across a multi-agent chain.

This feature answers two distinct questions, tracked in two separate logs:

Question	Log	Scope
"Who changed this workflow/skill, and what did they change?"	Audit Log	Config mutations: create, update, delete, publish, unpublish, permission changes
"What exactly happened during this run?"	Execution Trace	Every node, tool call, and sub-agent call in a run, in order, with real success/error status

Not the same as Lifecycle History or OTel tracing

The Audit Log described here is a general "who changed what" trail for agent_workflow and agent_skill resources. It's distinct from the workflow's lifecycle event history (GET /{id}/lifecycle), which only covers stage/approve/reject/revise status transitions and has its own UI in the Review Queue. It's also distinct from Logging & Tracing, which covers OpenTelemetry spans/metrics and structured log lines — this feature persists a queryable, permanent record in the database instead.

---

Audit Log — config changes

Every mutating action on a workflow or skill is recorded as one immutable row, written atomically with the change itself (same database transaction — an audit entry is never lost even if the process crashes right after).

What gets audited

Resource	Actions tracked
Workflow (agent_workflow)	Create, update (graph/name/description), delete, publish, unpublish, rollback, promote, import, default-skill change
Workflow triggers (cron / webhook / event)	Create, update (including enable/disable), delete — recorded as an UPDATE on the parent workflow
Approval matrix	Configure or remove — recorded as PERMISSION_CHANGE on the workflow
Skill (agent_skill)	Create, update, delete, publish, unpublish, version snapshot

Each entry captures:

Field	Description
actor_id	User who made the change (null for system-initiated changes)
actor_type	HUMAN, SYSTEM, or API_KEY
action	CREATE, UPDATE, DELETE, PUBLISH, UNPUBLISH, or PERMISSION_CHANGE
resource_type	AGENT or SKILL
resource_id	The workflow or skill ID
before_state / after_state	Full JSON snapshot before and after the change (null for create/delete respectively) — enough to manually revert a change if needed
diff_summary	Human-readable one-line summary of what changed
ip_address / user_agent	Captured from the request
space_id	Space the resource belongs to
created_at	Unix timestamp

Example entry (a workflow being published):

{
  "id": "audit-abc123",
  "actor_id": "user-lm-01",
  "actor_type": "HUMAN",
  "action": "PUBLISH",
  "resource_type": "AGENT",
  "resource_id": "wf-xyz",
  "before_state": { "status": "staged", "version": "1.2.0" },
  "after_state": { "status": "published", "version": "1.2.0" },
  "diff_summary": "published (from staged)",
  "ip_address": "10.0.4.12",
  "user_agent": "Mozilla/5.0 ...",
  "space_id": "space-eng",
  "created_at": 1750842000
}

Viewing the audit log

In the editor: open the History panel (top toolbar) → Audit Log tab. Entries are shown newest-first with an expandable before/after diff.

Via API:

GET /api/v1/agent-workflows/{workflow_id}/audit-log
GET /api/v1/agent-skills/{skill_id}/audit-log

Skill audit log is admin-only

Unlike the workflow audit log (which follows normal space read-access), the skill audit-log endpoint currently requires admin access — skill CRUD has no existing space/catalog RBAC layer to extend safely yet.

The History panel also surfaces Graph Versions

The same panel's Graph Versions tab lists every immutable snapshot taken on publish (or manually), lets you view a version's full graph JSON, and roll back to it — see Versioning for the full versioning model.

---

Execution Trace — run behavior

Every workflow run already persists a per-node timeline (see Run Infrastructure). This feature extends that timeline down to individual tool calls, and adds step classification so the frontend doesn't need to guess what kind of event each row represents.

Step types

step_type	Covers
REASONING	Node start/complete/error/timeout, review pause/approve/reject/modify
TOOL_CALL	A single tool invocation made by an agent/classify/guardrails node
SUB_AGENT_CALL	A sub_workflow node, or a trigger_workflow tool call, invoking another workflow
OUTPUT	The run's final output

Tool-call fields

Each TOOL_CALL step records:

Field	Description
tool_name	Which tool was called (e.g. api_caller, sql_query)
tool_input	The exact arguments passed to the tool
tool_output	The exact output text — the real result, not a generic message
event_type	tool_call_complete or tool_call_error
latency_ms	How long the call took

A failed tool call shows its real error

Previously, a tool handler's success/failure flag was discarded once its output was flattened to text, so a failed call could only be told apart from a successful one by pattern-matching the output string. Now is_error is a first-class part of the tool-dispatch return value, so failed calls are unambiguously tagged tool_call_error with the exact failure text preserved in tool_output — never a generic "something went wrong."

Viewing execution steps

In the editor: open the Runs panel → expand a run to see its step timeline, grouped by step_type. Tool-call rows show tool_name/tool_input/tool_output, styled red on error.

Via API:

GET /api/v1/agent-workflows/{workflow_id}/runs
GET /api/v1/agent-workflows/{workflow_id}/execution-log?run_id={run_id}

The first endpoint lists run headers (status, trigger type, timing) for the Runs-tab list view; the second returns the full ordered step timeline for one run.

---

Agent-to-agent chain correlation

When a sub_workflow node or the trigger_workflow tool starts another workflow run from inside a running one, the child run is linked back to its parent — so a multi-agent call chain can be walked as a tree instead of appearing as disconnected, unrelated runs.

How a run is tagged

Every run now records:

Field	Values	Meaning
triggered_by_type	USER, SCHEDULE, WEBHOOK, AGENT	What started this run
parent_run_id	run ID or null	The run that spawned this one (only set when triggered_by_type = AGENT)
parent_node_id	node ID or null	Which node in the parent run spawned it (the sub_workflow node, or the node whose agent called trigger_workflow)

Viewing a run's call chain

In the editor: in the Runs panel, expand a run and click View call chain.

Via API:

GET /api/v1/agent-workflows/runs/{run_id}/chain

Returns a flat list of every ancestor (walking parent_run_id up to the root) plus every direct child the given run spawned:

[
  { "run_id": "run-parent", "workflow_id": "wf-orchestrator", "parent_run_id": null, "parent_node_id": null, "status": "completed", "triggered_by_type": "USER" },
  { "run_id": "run-child-1", "workflow_id": "wf-billing", "parent_run_id": "run-parent", "parent_node_id": "sub_workflow_1", "status": "completed", "triggered_by_type": "AGENT" },
  { "run_id": "run-child-2", "workflow_id": "wf-shipping", "parent_run_id": "run-parent", "parent_node_id": "sub_workflow_2", "status": "failed", "triggered_by_type": "AGENT" }
]

Access to a run and its chain follows the same rule as viewing the run itself: the triggering user, or an admin.

---

Retention

Both logs are purged automatically by the same daily background job that already handles soft-deleted file cleanup.

Log	Env var	Default retention
Audit Log	AUDIT_LOG_RETENTION_DAYS	2555 days (~7 years — compliance-oriented)
Execution Trace (workflow_run + its execution-log/cost rows)	EXECUTION_TRACE_RETENTION_DAYS	90 days (debugging-oriented, high-volume)

Fire-and-forget writes are monitored

Execution-step writes happen off the hot path (asyncio.create_task, not awaited) so a logging hiccup can never fail the underlying tool call or node. If a write does fail, it's surfaced as a normal ERROR-level log line — nothing is silently dropped. Audit Log writes, by contrast, are never fire-and-forget: they're staged on the same database transaction as the change they describe, so an audit row and its resource change always succeed or fail together.

---

Role reference

Action	Required role / permission
View a workflow's audit log	Any member with read access to the workflow's space
View a skill's audit log	Admin
View run list / execution steps / call chain	The triggering user, or admin

See Permissions for configuration details.