What is Act-onomy?
Act-onomy is a taxonomy for describing and analyzing AI agent behavior at runtime. It provides a shared vocabulary of 10 actions, 46 subactions, and 120 leaf categories to help people make sense of what agents do.
Read the trace
“To verify that this change resolves the issue, we should create a script that replicates the problem as described.”
SWE-agent · Turn 6Describe the behavior
Decompose into subgoals with success conditions
Follow the trajectory
Plan a checkPlanning
Run the scriptExecuting
Check the resultEvaluating
Agents produce long reasoning trajectories and execution traces, but these records are often difficult to interpret at scale. Act-onomy connects behavior labels to quoted evidence, helping researchers, agent designers, and users examine how an agent plans, reasons, executes, evaluates, and adapts.
The taxonomy was developed through Grounded Theory. The accompanying repository contains the living codebook, research datasets, automated analysis tools, and a protocol for extending the vocabulary as new agent behaviors emerge.
Overview
- Purpose — Describe and analyze agent behavior at runtime.
- Structure — Action → Subaction → Leaf category.
- Evidence — Each trace annotation is linked to the words behind it.
- Applications — Compare behavioral profiles across agents and examine differences within a single agent’s trajectories.
- Extension — Adapt the codebook to behaviors in new agent systems.
The released taxonomy
- 10 actions, including Planning, Reasoning, Executing, and Reflecting.
- 46 subactions that distinguish more specific kinds of behavior.
- 120 leaf categories with definitions or examples from the codebook.
Getting Started
An example from a real SWE-agent trajectory. Switch between the raw text and its annotation, or follow the next steps:
Browse the complete taxonomy or explore three annotated trajectories: two SWE-agent tasks and a SWE-chat session with human feedback (best viewed on desktop).
Download the released codebook and machine-readable taxonomy:
How Was It Developed?
Act-onomy uses a Grounded Theory approach to turn descriptions of agent behavior into a structured, extensible vocabulary.
- Ground the vocabulary. Collect behavior descriptions from agent research, review their evidence, and refine category boundaries.
- Apply it to trajectories. Link labels to quoted evidence and examine patterns across agents and across runs.
- Keep it open to change. Propose new behaviors through a documented extension protocol.
Tools and Resources
Analyze your own trajectories with the Act-onomy skills. Download all four skills with their codebook, scripts, report templates, examples, and usage guide.
Run the skills in a coding agent with Python 3.10+. Your agent performs the annotation and produces an interactive HTML report.
How to use the downloaded skills
- Extract the ZIP and keep the
actonomy-skills/folder together. - Open that folder in your coding agent and add your trajectory file.
- Send this prompt, replacing the example filename with your own:
Read tools/trace-qualitative-analyst/SKILL.md and use it to analyze my-trajectory.json. Follow the codebook, ground labels in exact quotes, and save the annotated JSON and HTML report under outputs/.For a Claude Code session JSONL with human messages, use tools/human-trace-qualitative-analyst/SKILL.md and your session filename instead.
The ZIP also includes skills for discovering behaviors in papers and maintaining the codebook. The discovery skill's Word builders additionally need Node.js and npm. See README.md or README.zh.md in the download for all four workflows and a local setup check.
Explore the research corpus, inspect the skill source, or extend the codebook:
Cite This Work
How to Interpret Agent Behavior
NeurIPS 2026
View citation
Have Questions?
Ask a question or share feedback through the Act-onomy GitHub repository.