Skip to content
Night Brownie Night Brownie
⌘K

Protocol

Pydantic models for the harness↔agent message protocol.

Task (harness → agent) and Decision (agent → harness) message contracts, plus supporting types.

Classes:

  • ActionItem –

    A single action to be executed by the harness after a decision.

  • DecisionMessage –

    Decision returned from an agent to the harness.

  • DecisionType –

    Valid agent decision values.

  • LLMBackendRef –

    Reference to the LLM backend the agent should use.

  • TaskContext –

    Context injected by the harness into each task.

  • TaskMessage –

    Task sent from the harness to an agent container.

ActionItem pydantic-model

Bases: BaseModel

A single action to be executed by the harness after a decision.

Extra fields are allowed to support future action types without schema changes.

Parameters:

  • type (str) –

    Action type identifier (e.g. add_label, comment).

Show JSON schema: 
{
  "additionalProperties": true,
  "description": "A single action to be executed by the harness after a decision.\n\nExtra fields are allowed to support future action types without schema changes.",
  "properties": {
    "type": {
      "title": "Type",
      "type": "string"
    }
  },
  "required": [
    "type"
  ],
  "title": "ActionItem",
  "type": "object"
}

Config:

  • default: {'extra': 'allow'}

Fields:

type pydantic-field 

type: str

Action type identifier (e.g. add_label, comment).

DecisionMessage pydantic-model

Bases: BaseModel

Decision returned from an agent to the harness.

Parameters:

  • task_id (str) –

    Must match the task_id from the corresponding TaskMessage.

  • decision (DecisionType) –

    The agent's decision on how to handle the task.

  • rationale (str) –

    Human-readable explanation of the decision.

  • actions (list[ActionItem], default: [] ) –

    Ordered list of actions for the harness to execute.

Show JSON schema: 
{
  "$defs": {
    "ActionItem": {
      "additionalProperties": true,
      "description": "A single action to be executed by the harness after a decision.\n\nExtra fields are allowed to support future action types without schema changes.",
      "properties": {
        "type": {
          "title": "Type",
          "type": "string"
        }
      },
      "required": [
        "type"
      ],
      "title": "ActionItem",
      "type": "object"
    },
    "DecisionType": {
      "description": "Valid agent decision values.",
      "enum": [
        "label_and_respond",
        "close",
        "escalate",
        "skip"
      ],
      "title": "DecisionType",
      "type": "string"
    }
  },
  "description": "Decision returned from an agent to the harness.",
  "properties": {
    "task_id": {
      "title": "Task Id",
      "type": "string"
    },
    "decision": {
      "$ref": "#/$defs/DecisionType"
    },
    "rationale": {
      "title": "Rationale",
      "type": "string"
    },
    "actions": {
      "default": [],
      "items": {
        "$ref": "#/$defs/ActionItem"
      },
      "title": "Actions",
      "type": "array"
    }
  },
  "required": [
    "task_id",
    "decision",
    "rationale"
  ],
  "title": "DecisionMessage",
  "type": "object"
}

Fields:

actions pydantic-field 

actions: list[ActionItem] = []

Ordered list of actions for the harness to execute.

decision pydantic-field 

decision: DecisionType

The agent's decision on how to handle the task.

rationale pydantic-field 

rationale: str

Human-readable explanation of the decision.

task_id pydantic-field 

task_id: str

Must match the task_id from the corresponding TaskMessage.

DecisionType

Bases: str, Enum

Valid agent decision values.

LLMBackendRef pydantic-model

Bases: BaseModel

Reference to the LLM backend the agent should use.

Parameters:

  • provider (str) –

    LLM provider identifier (e.g. anthropic, ollama).

  • model (str) –

    Model name / identifier (e.g. claude-sonnet-4-6).

Show JSON schema: 
{
  "description": "Reference to the LLM backend the agent should use.",
  "properties": {
    "provider": {
      "title": "Provider",
      "type": "string"
    },
    "model": {
      "title": "Model",
      "type": "string"
    }
  },
  "required": [
    "provider",
    "model"
  ],
  "title": "LLMBackendRef",
  "type": "object"
}

Fields:

model pydantic-field 

model: str

Model name / identifier (e.g. claude-sonnet-4-6).

provider pydantic-field 

provider: str

LLM provider identifier (e.g. anthropic, ollama).

TaskContext pydantic-model

Bases: BaseModel

Context injected by the harness into each task.

Parameters:

  • llm_backend (LLMBackendRef) –

    LLM backend the agent should use for this task.

  • memory_summary (str | None, default: None ) –

    LLM-generated summary of prior actions on this issue/repo, if any.

Show JSON schema: 
{
  "$defs": {
    "LLMBackendRef": {
      "description": "Reference to the LLM backend the agent should use.",
      "properties": {
        "provider": {
          "title": "Provider",
          "type": "string"
        },
        "model": {
          "title": "Model",
          "type": "string"
        }
      },
      "required": [
        "provider",
        "model"
      ],
      "title": "LLMBackendRef",
      "type": "object"
    }
  },
  "description": "Context injected by the harness into each task.",
  "properties": {
    "llm_backend": {
      "$ref": "#/$defs/LLMBackendRef"
    },
    "memory_summary": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Memory Summary"
    }
  },
  "required": [
    "llm_backend"
  ],
  "title": "TaskContext",
  "type": "object"
}

Fields:

llm_backend pydantic-field 

llm_backend: LLMBackendRef

LLM backend the agent should use for this task.

memory_summary pydantic-field 

memory_summary: str | None = None

LLM-generated summary of prior actions on this issue/repo, if any.

TaskMessage pydantic-model

Bases: BaseModel

Task sent from the harness to an agent container.

The harness generates a task_id automatically if not supplied.

Parameters:

  • task_id (str, default: '0c6c0c5c-5244-4465-9b96-83829b3e79e0' ) –

    Unique identifier for this task (UUID4).

  • type (str) –

    Task type (e.g. issue.triage).

  • repo (str) –

    Repository in owner/repo format.

  • payload (dict[str, Any]) –

    Raw GitHub event payload.

  • context (TaskContext) –

    Harness-injected context (memory summary, LLM backend).

Show JSON schema: 
{
  "$defs": {
    "LLMBackendRef": {
      "description": "Reference to the LLM backend the agent should use.",
      "properties": {
        "provider": {
          "title": "Provider",
          "type": "string"
        },
        "model": {
          "title": "Model",
          "type": "string"
        }
      },
      "required": [
        "provider",
        "model"
      ],
      "title": "LLMBackendRef",
      "type": "object"
    },
    "TaskContext": {
      "description": "Context injected by the harness into each task.",
      "properties": {
        "llm_backend": {
          "$ref": "#/$defs/LLMBackendRef"
        },
        "memory_summary": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Memory Summary"
        }
      },
      "required": [
        "llm_backend"
      ],
      "title": "TaskContext",
      "type": "object"
    }
  },
  "description": "Task sent from the harness to an agent container.\n\nThe harness generates a `task_id` automatically if not supplied.",
  "properties": {
    "task_id": {
      "title": "Task Id",
      "type": "string"
    },
    "type": {
      "title": "Type",
      "type": "string"
    },
    "repo": {
      "title": "Repo",
      "type": "string"
    },
    "payload": {
      "additionalProperties": true,
      "title": "Payload",
      "type": "object"
    },
    "context": {
      "$ref": "#/$defs/TaskContext"
    }
  },
  "required": [
    "type",
    "repo",
    "payload",
    "context"
  ],
  "title": "TaskMessage",
  "type": "object"
}

Fields:

context pydantic-field 

context: TaskContext

Harness-injected context (memory summary, LLM backend).

payload pydantic-field 

payload: dict[str, Any]

Raw GitHub event payload.

repo pydantic-field 

repo: str

Repository in owner/repo format.

task_id pydantic-field 

task_id: str

Unique identifier for this task (UUID4).

type pydantic-field 

type: str

Task type (e.g. issue.triage).