Agent Execution Trace Protocol (AETP)

Version 1.0 · Status: Stable · License: Apache 2.0

Abstract

The Agent Execution Trace Protocol (AETP) is an open specification that defines how a multi-agent AI system should record its own execution. AETP specifies the structure of a trace — a complete record of every step a multi-agent system took to reach an outcome, including which agent acted, what data it received, what tool or model calls it made, what it passed to other agents, and whether a human was brought into the loop. Any system that produces an AETP-compliant trace can be evaluated, diagnosed, and audited by any AETP-compliant tool, regardless of which framework built the agent.

1. Introduction

Multi-agent AI systems are, by construction, distributed systems: several specialized agents each handle part of a task and pass information to one another. When such a system produces an incorrect outcome, diagnosing which agent — and which specific decision — caused the failure requires a structured record of what actually happened during execution.

Today, every agent framework logs this information differently, if it logs it in a structured way at all. This fragmentation means diagnostic tooling has to be rebuilt per-framework, and a trace produced by one system cannot be evaluated by a tool built for another. AETP exists to remove that fragmentation.

AETP is deliberately agnostic to which agent framework, orchestration pattern, or model provider produced the trace. It specifies the shape of the record, not how the agent system itself is built.

2. Conformance Language

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in RFC 2119.

A system is AETP v1.0 compliant if every trace it produces validates against the schema in Section 9 and satisfies every MUST and MUST NOT requirement stated in this document.

3. Terminology

Trace — a complete record of one end-to-end execution of a multi-agent system, from initial input to final outcome.

Step — a single unit of work performed by one agent within a trace. A trace consists of an ordered sequence of steps.

Agent — a distinct, named reasoning unit within the system under trace. An agent may correspond to a single LLM call, a sub-graph of calls, or a more complex internal process; AETP does not prescribe agent internals, only what an agent must report about its step.

Escalation — a step in which the system hands a decision to a human reviewer rather than acting autonomously.

Memory operation — a read, write, or delete against any persistent or session-scoped memory system (vector store, key-value store, or in-context memory) performed during a step.

4. Data Model

4.1 AETPTrace (Envelope)

The root object of every AETP-compliant trace.

4.2 AETPSystemInfo

4.3 AETPModelInfo

4.4 AETPStep

4.5 AETPStepType

An enumerated value, one of:

4.6 Step Inputs and Output

Inputs object:

Output object:

4.7 AETPLLMCall

4.8 AETPToolCall

4.9 AETPMemoryOp

4.10 AETPOutcome

4.11 AETPEscalationEvent

5. Privacy and Data Minimization Requirements

A conforming trace MUST NOT contain:

• Raw values of tool call parameters or outputs — only structural hashes (Section 4.8)
• Real customer, patient, or end-user identifiers in any scope, key, or content_summary field — these MUST be anonymized or pseudonymized before being written into the trace
• Any field not explicitly defined in this specification containing free-text content that has not been reviewed for personally identifiable information

content_summary fields SHOULD be either hand-authored or generated specifically to be a description of what occurred, never a verbatim copy of the underlying data the step processed.

6. Worked Examples

6.1 Healthcare — Clinical Scheduling Step

{
  "step_id": "step_042",
  "step_number": 3,
  "agent_name": "theatre-allocation-agent",
  "agent_role": "Theatre Allocator",
  "started_at": "2026-07-20T14:02:11Z",
  "completed_at": "2026-07-20T14:02:13Z",
  "step_type": "REASONING",
  "inputs": {
    "from_agents": [
      { "from": "patient-record-agent", "summary": "infection_risk_flag and isolation_class provided" }
    ],
    "from_tools": [],
    "from_memory": [],
    "context_window_tokens": 4120
  },
  "llm_calls": [
    {
      "call_id": "llm_017",
      "model_alias": "planner",
      "input_tokens": 1800,
      "output_tokens": 220,
      "latency_ms": 1140,
      "cached": false
    }
  ],
  "tool_calls": [],
  "memory_ops": [],
  "output": {
    "to_agents": ["anaesthetist-assignment-agent"],
    "content_summary": "Assigned patient to Theatre 4, respecting isolation_class requirement for the following case.",
    "constraints_referenced": ["HC-014"]
  },
  "status": "completed"
}

6.2 Financial Services — Credit Underwriting Step With Escalation

{
  "step_id": "step_118",
  "step_number": 6,
  "agent_name": "affordability-agent",
  "agent_role": "Affordability Calculator",
  "started_at": "2026-07-20T09:15:44Z",
  "completed_at": "2026-07-20T09:15:46Z",
  "step_type": "ESCALATION",
  "inputs": {
    "from_agents": [
      { "from": "compliance-check-agent", "summary": "binding regulatory floor for secondary jurisdiction provided" }
    ],
    "from_tools": [],
    "from_memory": [],
    "context_window_tokens": 5460
  },
  "llm_calls": [
    {
      "call_id": "llm_063",
      "model_alias": "underwriter",
      "input_tokens": 2400,
      "output_tokens": 340,
      "latency_ms": 1580,
      "cached": false
    }
  ],
  "tool_calls": [],
  "memory_ops": [],
  "output": {
    "to_agents": [],
    "content_summary": "Application exceeds thin-file multi-jurisdiction risk threshold; escalated to Tier 2 human reviewer.",
    "constraints_referenced": ["HC-031"],
    "escalation_event": {
      "escalation_id": "esc_009",
      "tier": "Tier 2 — Senior Underwriter",
      "trigger_constraint_id": "HC-031",
      "context_fields_included": ["financial_impact", "reversibility", "alternatives_considered"],
      "reversibility_flagged": true,
      "financial_impact_included": true,
      "approval_deadline": "2026-07-21T09:15:46Z"
    }
  },
  "status": "escalated"
}

6.3 Logistics — Multi-Hub Routing With Tool Call

{
  "step_id": "step_204",
  "step_number": 2,
  "agent_name": "carrier-assignment-agent",
  "agent_role": "Carrier Assigner",
  "started_at": "2026-07-20T02:40:03Z",
  "completed_at": "2026-07-20T02:40:05Z",
  "step_type": "RETRIEVAL",
  "inputs": {
    "from_agents": [],
    "from_tools": [],
    "from_memory": [],
    "context_window_tokens": 3210
  },
  "llm_calls": [],
  "tool_calls": [
    {
      "call_id": "tool_088",
      "tool_name": "customs_clearance_lookup",
      "mcp_server": "logistics-tools",
      "parameters_schema_hash": "sha256:9f2a...",
      "output_schema_hash": "sha256:41bd...",
      "latency_ms": 340,
      "status_code": 200
    }
  ],
  "memory_ops": [],
  "output": {
    "to_agents": ["capacity-planning-agent"],
    "content_summary": "Confirmed customs clearance signal received before carrier assignment.",
    "constraints_referenced": ["HC-007"]
  },
  "status": "completed"
}

7. Validation and Conformance

A trace is validated against the JSON Schema in Section 9. Validation checks:

1. All MUST fields are present and correctly typed.
2. aetp_version matches a version this validator supports.
3. Every model_alias referenced in an AETPLLMCall corresponds to an entry in agent_system.models.
4. No field flagged in Section 5 as prohibited contains content matching common PII patterns (this check is advisory, not a hard schema constraint, since PII detection cannot be fully guaranteed by schema validation alone).

An online validator and downloadable conformance test suite are available via the reference implementations listed in Section 8.

8. Reference Implementations

• TypeScript: @truvyx/aetp (npm) — AETPTracer class for instrumenting agent code, validateAETPTrace() for validation.
• Python: truvyx-aetp (PyPI) — equivalent AETPTracer and validation functions.

Both packages are Apache 2.0 licensed and maintained by Truvyx.

9. Appendix — JSON Schema (Excerpt)

The following is the top-level JSON Schema for AETPTrace. The complete schema, including all nested object definitions, is published alongside the reference implementations.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://spec.truvyx.org/aetp/v1.0/schema.json",
  "title": "AETPTrace",
  "type": "object",
  "required": ["aetp_version", "trace_id", "created_at", "agent_system", "steps", "outcome"],
  "properties": {
    "aetp_version": { "const": "1.0" },
    "trace_id": { "type": "string", "format": "uuid" },
    "scenario_id": { "type": "string" },
    "created_at": { "type": "string", "format": "date-time" },
    "agent_system": { "$ref": "#/definitions/AETPSystemInfo" },
    "steps": {
      "type": "array",
      "minItems": 1,
      "items": { "$ref": "#/definitions/AETPStep" }
    },
    "outcome": { "$ref": "#/definitions/AETPOutcome" }
  }
}

10. Changelog

11. License

Copyright Truvyx. Licensed under the Apache License, Version 2.0. You may obtain a copy of the License at https://www.apache.org/licenses/LICENSE-2.0.