# Hermes Agent ShareGPT Trajectory Format: Structure and Implementation

> Understand the Hermes Agent ShareGPT trajectory format. Learn how conversations are saved as JSONL records with speaker roles, tool interactions, and metadata for efficient persistence.

- Repository: [Nous Research/hermes-agent](https://github.com/NousResearch/hermes-agent)
- Tags: internals
- Published: 2026-03-09

---

**Hermes Agent saves conversation trajectories as ShareGPT-style JSONL records using the `AIAgent._convert_to_trajectory_format()` method in [`run_agent.py`](https://github.com/NousResearch/hermes-agent/blob/main/run_agent.py), persisting them via `save_trajectory()` in [`agent/trajectory.py`](https://github.com/NousResearch/hermes-agent/blob/main/agent/trajectory.py) with fields for speaker roles, tool interactions, and metadata.**

The NousResearch/hermes-agent repository implements a structured logging system for AI agent interactions using the ShareGPT trajectory format. This format captures multi-turn conversations between users, models, and tools in a standardized JSON structure that facilitates training data collection and debugging.

## Core Trajectory Structure

The ShareGPT trajectory format used by Hermes Agent consists of a JSON object with a `conversations` array containing turn-based message objects. Each turn specifies the speaker role and content value.

The structure includes:

- **`from`**: Speaker identifier (`system`, `human`, `gpt`, `tool`)
- **`value`**: Message content with XML-style tags for tool interactions
- **`timestamp`**: ISO-8601 timestamp of when the trajectory was written
- **`model`**: Model identifier (e.g., `anthropic/claude-opus-4.6`)
- **`completed`**: Boolean indicating successful completion

## Conversion Pipeline

The trajectory creation process involves two main components: message format conversion and file persistence.

### Internal Message Conversion

Located in [`run_agent.py`](https://github.com/NousResearch/hermes-agent/blob/main/run_agent.py), the private method `AIAgent._convert_to_trajectory_format()` (lines 998-1055) transforms the internal OpenAI-compatible message list into the ShareGPT schema. This method maps standard roles to ShareGPT's `from` field values and processes tool interactions.

### File Persistence

The `save_trajectory()` function in [`agent/trajectory.py`](https://github.com/NousResearch/hermes-agent/blob/main/agent/trajectory.py) (lines 44-48) handles the actual file operations. It appends JSONL entries to either `trajectory_samples.jsonl` for successful runs or `failed_trajectories.jsonl` for errors, including metadata fields like timestamp and completion status.

## Special XML Tags for Tool Interactions

The format uses specific XML-style tags to demarcate tool usage and reasoning:

- **`<tool_call>`**: Wraps function calls made by the model, containing JSON with `name` and `arguments` fields
- **`<tool_response>`**: Encloses results returned from tool execution, including `tool_call_id`, `name`, and `content`
- **Reasoning tags**: Model reasoning steps are enclosed in dedicated XML-style tags during the conversion process

Example trajectory structure:

```json
{
  "conversations": [
    {
      "from": "system",
      "value": "You are a function-calling AI model..."
    },
    {
      "from": "human",
      "value": "Find me the latest release notes for pandas."
    },
    {
      "from": "gpt",
      "value": "\n<tool_call>\n{\"name\":\"web_search\",\"arguments\":{\"query\":\"pandas release notes\"}}\n</tool_call>"
    },
    {
      "from": "tool",
      "value": "<tool_response>\n{\"tool_call_id\":\"123\",\"name\":\"web_search\",\"content\":\"...HTML content...\"}\n</tool_response>"
    }
  ],
  "timestamp": "2024-01-15T10:30:00Z",
  "model": "anthropic/claude-opus-4.6",
  "completed": true
}

```

## Summary

- Hermes Agent uses a **ShareGPT-style JSONL format** for trajectory storage, implementing the standard `conversations` array structure with `from` and `value` fields.
- The conversion logic resides in `AIAgent._convert_to_trajectory_format()` within [`run_agent.py`](https://github.com/NousResearch/hermes-agent/blob/main/run_agent.py), handling the mapping from OpenAI-compatible messages to ShareGPT schema.
- File persistence is managed by `save_trajectory()` in [`agent/trajectory.py`](https://github.com/NousResearch/hermes-agent/blob/main/agent/trajectory.py), writing to `trajectory_samples.jsonl` or `failed_trajectories.jsonl` with metadata including timestamps and completion status.
- **XML-style tags** (`<tool_call>`, `<tool_response>`) encapsulate tool interactions and reasoning steps within message values.

## Frequently Asked Questions

### What is the difference between trajectory_samples.jsonl and failed_trajectories.jsonl?

The `trajectory_samples.jsonl` file stores successfully completed conversation trajectories where the agent finished the task normally, while `failed_trajectories.jsonl` contains trajectories from runs that encountered errors or failed to complete. Both files use the same ShareGPT JSONL format but are separated to facilitate filtering during dataset curation and debugging.

### How does Hermes Agent handle tool calls in the ShareGPT format?

Hermes Agent wraps tool calls in `<tool_call>` XML tags within the `value` field of `gpt` turns, containing a JSON object with `name` and `arguments` fields. Tool responses are similarly wrapped in `<tool_response>` tags within `tool` turns, including the `tool_call_id`, `name`, and `content` fields. This XML wrapping occurs in the `_convert_to_trajectory_format()` method.

### What metadata fields are added to each trajectory record?

Each trajectory record includes three metadata fields added by `save_trajectory()`: `timestamp` (ISO-8601 format indicating when the record was written), `model` (the model identifier used for the run, such as `anthropic/claude-opus-4.6`), and `completed` (a boolean indicating whether the conversation ended successfully or failed).

### Where is the conversion logic located in the codebase?

The conversion from internal OpenAI-compatible message format to ShareGPT schema is implemented in the private method `AIAgent._convert_to_trajectory_format()` located in [`run_agent.py`](https://github.com/NousResearch/hermes-agent/blob/main/run_agent.py) (approximately lines 998-1055). The file writing logic resides in `save_trajectory()` within [`agent/trajectory.py`](https://github.com/NousResearch/hermes-agent/blob/main/agent/trajectory.py) (lines 44-48).