Implementation:Microsoft Agent framework Durable Agent Entity State Schema

Knowledge Sources	Microsoft_Agent_framework JSON Schema 2020-12
Domains	Durable_Agents, State_Management, Schema_Definition
Last Updated	2026-02-11 17:00 GMT

Overview

JSON Schema definition for the durable agent entity state, providing the formal contract for serializing and deserializing conversation history and message content types across agent framework implementations.

Description

The durable-agent-entity-state.json schema defines the structure of a durable agent's persisted state using JSON Schema 2020-12. It specifies:

• Content types (discriminated by $type field): textContent, dataContent, errorContent, hostedFileContent, hostedVectorStoreContent, textReasoningContent, uriContent, usageContent, functionCallContent, functionResultContent, unknownContent
• Chat messages: Structured with authorName, role (user/assistant/system/tool), contents array, and createdAt timestamp
• Conversation entries: Groups of messages with optional correlationId and createdAt
• Agent requests and responses: Specialized conversation entries for prompts (with responseSchema, responseType, orchestrationId) and responses (with usage statistics)
• Top-level state: Contains a schemaVersion (semver) and data object with conversationHistory array

This schema ensures interoperability between .NET and Python implementations of durable agents.

Usage

Reference this schema when implementing durable agent state persistence, deserializing agent conversation history, or validating state payloads across different language implementations of the framework.

Code Reference

Source Location

• Repository: Microsoft_Agent_framework
• File: schemas/durable-agent-entity-state.json
• Lines: 1-217

Signature

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://github.com/microsoft/agent-framework/schemas/durable-agent-entity-state.json",
  "type": "object",
  "properties": {
    "schemaVersion": {
      "type": "string",
      "pattern": "^\\d+\\.\\d+\\.\\d+$"
    },
    "data": {
      "type": "object",
      "properties": {
        "conversationHistory": {
          "type": "array",
          "items": { "$ref": "#/$defs/conversationEntry" }
        }
      }
    }
  },
  "required": ["schemaVersion", "data"]
}

Import

{
  "$ref": "https://github.com/microsoft/agent-framework/schemas/durable-agent-entity-state.json"
}

I/O Contract

Inputs

Name	Type	Required	Description
schemaVersion	string (semver)	Yes	Semantic version of the state schema (e.g., "1.0.0")
data	object	Yes	Container for the durable agent state data
data.conversationHistory	array of conversationEntry	No	Ordered list of conversation exchanges

Outputs

Name	Type	Description
Validated state	object	A conformant durable agent state object
chatMessage.role	enum	One of: user, assistant, system, tool
chatContentItem.$type	enum	One of: text, data, error, hostedFile, hostedVectorStore, reasoning, uri, usage, functionCall, functionResult, unknown

Usage Examples

Minimal Valid State

{
  "schemaVersion": "1.0.0",
  "data": {
    "conversationHistory": []
  }
}

State with Conversation History

{
  "schemaVersion": "1.0.0",
  "data": {
    "conversationHistory": [
      {
        "createdAt": "2026-01-15T10:30:00Z",
        "$type": "request",
        "messages": [
          {
            "role": "user",
            "contents": [
              {
                "$type": "text",
                "text": "What is the weather in Seattle?"
              }
            ],
            "createdAt": "2026-01-15T10:30:00Z"
          }
        ]
      },
      {
        "createdAt": "2026-01-15T10:30:05Z",
        "$type": "response",
        "usage": {
          "inputTokenCount": 15,
          "outputTokenCount": 42,
          "totalTokenCount": 57
        },
        "messages": [
          {
            "role": "assistant",
            "contents": [
              {
                "$type": "text",
                "text": "The weather in Seattle is currently 55F and cloudy."
              }
            ],
            "createdAt": "2026-01-15T10:30:05Z"
          }
        ]
      }
    ]
  }
}

Related Pages

No outgoing connections. This is a standalone schema definition with no runtime environment or heuristic dependencies.