Hermes Agent ShareGPT Trajectory Format: Structure and Implementation

Hermes Agent saves conversation trajectories as ShareGPT-style JSONL records using the AIAgent._convert_to_trajectory_format() method in run_agent.py, persisting them via save_trajectory() in 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, 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 (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:

{
  "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, handling the mapping from OpenAI-compatible messages to ShareGPT schema.
• File persistence is managed by save_trajectory() in 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 (approximately lines 998-1055). The file writing logic resides in save_trajectory() within agent/trajectory.py (lines 44-48).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}