Agent Specification

This document defines a clean, production-ready schema for describing an “Agent” (your Subject) — its identity, metadata, persona, prompting rules, execution policy, integrations (tools/models/etc.), runtime resources, and governance.

It’s designed for:

Declarative configuration (files, DB rows, or APIs)
Deterministic execution (stable defaults, explicit types)
Modularity (drop-in capabilities and subsystems)
Extensibility (safe addition of new items/sections)

What this spec gives you

Separation of concerns Identity vs. persona vs. policy vs. runtime resources vs. governance are cleanly scoped.
Composable capabilities Tools, functions, DSLs, models, memory systems, subsystems, and addons plug in uniformly.
Prompting ergonomics Consistent system/input/output templates and per-prompt overrides.
Execution safety Explicit logging level, code-execution toggle, and memory-class controls.
Runtime portability Per-replica resource profile, node selectors, and env for any orchestrator.
Governance & ownership Contact/owner metadata kept distinct for audits and approvals.

Full agent specification structure

from dataclasses import dataclass, field
from typing import List, Dict, Optional, Any, Literal


# ---------- Core ----------
@dataclass
class SubjectVersion:
    version: str
    release_tag: str


@dataclass
class OwnerInfo:
    org_id: Optional[str] = None
    org_name: Optional[str] = None
    team: Optional[str] = None
    owners: List[str] = field(default_factory=list)         # emails/user IDs
    contacts: Dict[str, str] = field(default_factory=dict)  # {"slack":"...", "email":"..."}


@dataclass
class ResourceProfile:
    device: Literal["cpu", "gpu", "tpu"] = "cpu"
    cpu_cores: float = 1.0                # per replica
    memory_mb: int = 2048                 # per replica
    storage_mb: int = 0                   # per replica
    gpu_count: int = 0                    # per replica
    gpu_memory_mb: Optional[int] = None
    node_selector: Dict[str, str] = field(default_factory=dict)
    env: Dict[str, str] = field(default_factory=dict)


# ---------- Capability items ----------
@dataclass
class ContractItem:
    contract_type: str
    contract_id: str
    contract_parameters: Dict[str, Any] = field(default_factory=dict)


@dataclass
class DSLItem:
    dsl_type: str
    dsl_workflow_id: str
    dsl_parameters: Dict[str, Any] = field(default_factory=dict)


@dataclass
class ModelItem:
    llm_type: str
    llm_block_id: str
    llm_selection_query: Dict[str, Any] = field(default_factory=dict)
    llm_parameters: Dict[str, Any] = field(default_factory=dict)


@dataclass
class AddonItem:
    addon_id: str
    addon_type: str
    addon_config: Dict[str, Any] = field(default_factory=dict)


@dataclass
class ToolItem:
    tool_id: str
    tool_description: str = ""
    tool_execution_mode: Literal["local", "remote"] = "local"
    tool_custom_config: Dict[str, Any] = field(default_factory=dict)
    tool_calling_config: Dict[str, Any] = field(default_factory=dict)


@dataclass
class MemoryItem:
    memory_id: str
    memory_type: str = ""
    memory_backend: str = ""
    memory_custom_config: Dict[str, Any] = field(default_factory=dict)


@dataclass
class SubSystemItem:
    sub_system_id: str
    sub_system_type: str = ""
    sub_system_config: Dict[str, Any] = field(default_factory=dict)


@dataclass
class FunctionItem:
    function_id: str
    function_custom_parameters: Dict[str, Any] = field(default_factory=dict)
    function_calling_config: Dict[str, Any] = field(default_factory=dict)


# ---------- Grouped configs ----------
# Identity & metadata
@dataclass
class SubjectIdentity:
    subject_id: str = field(init=False)
    subject_name: str = ""
    subject_type: str = ""
    subject_version: SubjectVersion = field(
        default_factory=lambda: SubjectVersion("0.1.0", "dev")
    )


@dataclass
class SubjectMetadata:
    subject_description: str = ""
    subject_search_tags: List[str] = field(default_factory=list)
    subject_traits: List[str] = field(default_factory=list)
    subject_metadata: Dict[str, str] = field(default_factory=dict)


# Agent persona, prompting & execution policy
@dataclass
class AgentPersona:
    role: str = ""                      # function/expertise
    goal: str = ""                      # objective
    persona: str = ""                   # narrative/backstory
    default_system_message: str = ""    # default system prompt


@dataclass
class ManagementCommandItem:
    command: str
    command_description: Optional[str] = None
    input_template: Optional[str] = None
    output_template: Optional[str] = None


@dataclass
class PromptingConfig:
    default_system_template: Optional[str] = None
    input_template: Optional[str] = None
    output_template: Optional[str] = None
    prompts_config: Dict[str, Any] = field(default_factory=dict)


@dataclass
class ExecutionPolicy:
    logging_level: Literal["CRITICAL", "ERROR", "WARNING", "INFO", "DEBUG"] = "INFO"
    support_delegations: bool = False
    execute_code: bool = False
    # enabled memory classes like ["short-term", "long-term", "context"]
    enabled_memory_classes: List[str] = field(default_factory=list)

    def __post_init__(self):
        # Normalize/validate values once
        self.logging_level = str(self.logging_level).upper()  # type: ignore


@dataclass
class BuiltinModules:
    module_id: str = ""
    module_description: str = ""
    module_input_template: str = ""
    module_output_template: str = ""
    module_management_commands: List[ManagementCommandItem] = field(default_factory=list)


# Integrations (runtime bindings)
@dataclass
class IntegrationConfig:
    dsls: List[DSLItem] = field(default_factory=list)
    models: List[ModelItem] = field(default_factory=list)
    addons: List[AddonItem] = field(default_factory=list)
    contracts: List[ContractItem] = field(default_factory=list)
    subject_tools: List[ToolItem] = field(default_factory=list)
    subject_functions: List[FunctionItem] = field(default_factory=list)
    memory_systems: List[MemoryItem] = field(default_factory=list)
    sub_systems: List[SubSystemItem] = field(default_factory=list)
    builtin_modules: List[BuiltinModules] = field(default_factory=list)  # <— surfaced


@dataclass
class RuntimeConfig:
    resources: ResourceProfile = field(default_factory=ResourceProfile)
    management_commands: List[ManagementCommandItem] = field(default_factory=list)


# ---------- Main aggregated Subject ----------
@dataclass
class Subject:
    identity: SubjectIdentity = field(default_factory=SubjectIdentity)
    metadata: SubjectMetadata = field(default_factory=SubjectMetadata)
    persona: AgentPersona = field(default_factory=AgentPersona)
    prompting: PromptingConfig = field(default_factory=PromptingConfig)
    execution: ExecutionPolicy = field(default_factory=ExecutionPolicy)
    integrations: IntegrationConfig = field(default_factory=IntegrationConfig)
    runtime: RuntimeConfig = field(default_factory=RuntimeConfig)
    owner: OwnerInfo = field(default_factory=OwnerInfo)  # governance

Top-Level Layout

{
  "identity": { ... },
  "metadata": { ... },
  "persona": { ... },
  "prompting": { ... },
  "execution": { ... },
  "integrations": { ... },
  "runtime": { ... },
  "owner": { ... }
}

Below, each section lists: Field, Type, Required?, Default, Description.

1) identity — SubjectIdentity

Field	Type	Required?	Default	Description
subject_id	`str` (set post-init)	No	—	Unique ID assigned by your service layer (e.g., UUID).
subject_name	`str`	No	`""`	Human-friendly name for the agent.
subject_type	`str`	No	`""`	Category/class (e.g., `"researcher"`, `"assistant"`).
subject_version	`SubjectVersion`	No	`{"version":"0.1.0","release_tag":"dev"}`	Semver + release tag for this agent build.

SubjectVersion

Field	Type	Required?	Default	Description
version	`str`	Yes	—	Semantic version (e.g., `"1.2.3"`).
release_tag	`str`	Yes	—	Channel or label (e.g., `"dev"`, `"stable"`).

2) metadata — SubjectMetadata

Field	Type	Required?	Default	Description
subject_description	`str`	No	`""`	Narrative description of the agent.
subject_search_tags	`List[str]`	No	`[]`	Searchable tags for discovery.
subject_traits	`List[str]`	No	`[]`	Behavioral traits (e.g., `"concise"`, `"formal"`).
subject_metadata	`Dict[str,str]`	No	`{}`	Freeform key-value metadata (small strings).

3) persona — AgentPersona

Field	Type	Required?	Default	Description
role	`str`	No	`""`	The agent’s function/expertise.
goal	`str`	No	`""`	Primary objective guiding decisions.
persona	`str`	No	`""`	Backstory/narrative for tone and consistency.
default_system_message	`str`	No	`""`	Baseline system prompt; applied when no template overrides.

4) prompting — PromptingConfig & ManagementCommandItem

Field	Type	Required?	Default	Description
default_system_template	`Optional[str]`	No	`None`	Jinja-like template for the system prompt.
input_template	`Optional[str]`	No	`None`	Template for user/input formatting.
output_template	`Optional[str]`	No	`None`	Template for agent outputs.
prompts_config	`Dict[str,Any]`	No	`{}`	Named prompt snippets/vars for advanced setups.

ManagementCommandItem (used in runtime.management_commands or inside modules)

Field	Type	Required?	Default	Description
command	`str`	Yes	—	Command name (e.g., `"reset"`, `"warmup"`).
command_description	`Optional[str]`	No	`None`	Human-friendly description.
input_template	`Optional[str]`	No	`None`	Template for command input.
output_template	`Optional[str]`	No	`None`	Template for command output.

5) execution — ExecutionPolicy

Field	Type	Required?	Default	Description
logging_level	`"CRITICAL" \\| "ERROR" \\| "WARNING" \\| "INFO" \\| "DEBUG"`	No	`"INFO"`	Runtime log verbosity.
support_delegations	`bool`	No	`False`	Allow the agent to delegate tasks to other agents/tools.
execute_code	`bool`	No	`False`	Permit code execution (use cautiously).
enabled_memory_classes	`List[str]`	No	`[]`	Memory tiers the agent may use (e.g., `["short-term","long-term","context"]`).

6) integrations — IntegrationConfig

This is the “plug-in board” for capabilities.

Field	Type	Required?	Default	Description
dsls	`List[DSLItem]`	No	`[]`	Registered DSL workflows.
models	`List[ModelItem]`	No	`[]`	Model/LLM backends and parameters.
addons	`List[AddonItem]`	No	`[]`	Sidecar features (analytics, guards, etc.).
contracts	`List[ContractItem]`	No	`[]`	Contract modules and parameters.
subject_tools	`List[ToolItem]`	No	`[]`	Tools the agent can call (local/remote).
subject_functions	`List[FunctionItem]`	No	`[]`	Functions callable by the agent (strong typing optional).
memory_systems	`List[MemoryItem]`	No	`[]`	Memory providers (vector DBs, caches).
sub_systems	`List[SubSystemItem]`	No	`[]`	External subsystems (routing, evaluators, schedulers).
builtin_modules	`List[BuiltinModules]`	No	`[]`	First-class modules shipped with the platform.

DSLItem

Field	Type	Required?	Default	Description
dsl_type	`str`	Yes	—	E.g., `"graph"`, `"dag"`.
dsl_workflow_id	`str`	Yes	—	Registry/workflow identifier.
dsl_parameters	`Dict[str,Any]`	No	`{}`	Runtime parameters / overrides.

ModelItem

Field	Type	Required?	Default	Description
llm_type	`str`	Yes	—	Model family/type (`"hf"`, `"openai"`, etc.).
llm_block_id	`str`	Yes	—	Concrete deployment or block id.
llm_selection_query	`Dict[str,Any]`	No	`{}`	Query for dynamic model selection.
llm_parameters	`Dict[str,Any]`	No	`{}`	Generation params (temperature, top_p, …).

AddonItem

Field	Type	Required?	Default	Description
addon_type	`str`	Yes	—	Addon kind (e.g., `"guardrails"`, `"analytics"`).
addon_config	`Dict[str,Any]`	No	`{}`	Configuration map.

ToolItem

Field	Type	Required?	Default	Description
tool_id	`str`	Yes	—	Tool registry ID.
tool_description	`str`	No	`""`	Human-readable description.
tool_execution_mode	`"local" \\| "remote"`	No	`"local"`	Where the tool executes.
tool_custom_config	`Dict[str,Any]`	No	`{}`	Tool-specific config (auth, timeouts, etc.).
tool_calling_config	`Dict[str,Any]`	No	`{}`	Function-calling schema, arg hints, safety flags.

FunctionItem

Field	Type	Required?	Default	Description
function_id	`str`	Yes	—	Function registry ID.
function_custom_parameters	`Dict[str,Any]`	No	`{}`	Input defaults/overrides.
function_calling_config	`Dict[str,Any]`	No	`{}`	JSON schema / arg mapping / safety.

MemoryItem

Field	Type	Required?	Default	Description
memory_id	`str`	Yes	—	Memory system ID.
memory_type	`str`	No	`""`	Logical type (`"short-term"`, `"long-term"`, etc.).
memory_backend	`str`	No	`""`	Engine/driver (e.g., `"weaviate"`, `"redis"`).
memory_custom_config	`Dict[str,Any]`	No	`{}`	Index names, TTLs, dimensions, etc.

SubSystemItem

Field	Type	Required?	Default	Description
sub_system_id	`str`	Yes	—	Subsystem ID.
sub_system_type	`str`	No	`""`	Category (router, evaluator, scheduler).
sub_system_config	`Dict[str,Any]`	No	`{}`	Config map.

ContractItem

Field	Type	Required?	Default	Description
contract_type	`str`	Yes	—	Contract class/kind.
contract_id	`str`	Yes	—	Registry/deployment ID.
contract_parameters	`Dict[str,Any]`	No	`{}`	Parameters for evaluation/execution.

BuiltinModules

Field	Type	Required?	Default	Description
module_id	`str`	No	`""`	Built-in module ID.
module_description	`str`	No	`""`	Description of functionality.
module_input_template	`str`	No	`""`	Input template for the module.
module_output_template	`str`	No	`""`	Output template for the module.
module_management_commands	`List[ManagementCommandItem]`	No	`[]`	Module-scoped management commands.

7) runtime — RuntimeConfig & ResourceProfile

Field	Type	Required?	Default	Description
resources	`ResourceProfile`	No	See defaults	Per-replica compute/storage and scheduling hints.
management_commands	`List[ManagementCommandItem]`	No	`[]`	Global management commands for this agent.

ResourceProfile

Field	Type	Required?	Default	Description
device	`"cpu" \\| "gpu" \\| "tpu"`	No	`"cpu"`	Execution device type.
cpu_cores	`float`	No	`1.0`	vCPU per replica.
memory_mb	`int`	No	`2048`	Memory (MB) per replica.
storage_mb	`int`	No	`0`	Ephemeral/storage (MB) per replica.
gpu_count	`int`	No	`0`	GPUs per replica.
gpu_memory_mb	`Optional[int]`	No	`None`	GPU memory hint (MB).
node_selector	`Dict[str,str]`	No	`{}`	Scheduler affinity hints (labels).
env	`Dict[str,str]`	No	`{}`	Environment variables for the process.

8) owner — OwnerInfo (Governance)

Field	Type	Required?	Default	Description
org_id	`Optional[str]`	No	`None`	Organization ID.
org_name	`Optional[str]`	No	`None`	Organization name.
team	`Optional[str]`	No	`None`	Team name/slug.
owners	`List[str]`	No	`[]`	Owner user IDs/emails.
contacts	`Dict[str,str]`	No	`{}`	Contact channels (e.g., `"slack"`, `"email"`).

Minimal JSON Example

{
  "identity": {
    "subject_name": "Policy Researcher",
    "subject_type": "researcher",
    "subject_version": { "version": "1.0.0", "release_tag": "stable" }
  },
  "metadata": {
    "subject_description": "Analyzes policy proposals and drafts briefs",
    "subject_search_tags": ["policy", "analysis"],
    "subject_traits": ["concise", "evidence-driven"]
  },
  "persona": {
    "role": "Policy Analyst",
    "goal": "Summarize and critique policy drafts",
    "persona": "Pragmatic, neutral, cites sources",
    "default_system_message": "Answer with citations and balanced tone."
  },
  "prompting": {
    "default_system_template": "You are {{role}}. Goal: {{goal}}.",
    "prompts_config": { "citation_style": "APA" }
  },
  "execution": {
    "logging_level": "INFO",
    "support_delegations": true,
    "execute_code": false,
    "enabled_memory_classes": ["short-term", "context"]
  },
  "integrations": {
    "models": [
      { "llm_type": "hf", "llm_block_id": "llama3-70b", "llm_parameters": {"temperature": 0.2} }
    ],
    "subject_tools": [
      { "tool_id": "web-search", "tool_execution_mode": "remote" }
    ],
    "memory_systems": [
      { "memory_id": "weaviate-prod", "memory_backend": "weaviate" }
    ]
  },
  "runtime": {
    "resources": { "device": "gpu", "gpu_count": 1, "memory_mb": 8192 },
    "management_commands": [
      { "command": "warmup", "command_description": "Prime caches" }
    ]
  },
  "owner": {
    "org_name": "ExampleOrg",
    "owners": ["owner@example.org"],
    "contacts": {"slack":"#agents","email":"owner@example.org"}
  }
}