Agent Spec

Status link

Draft proposed canonical extension aligned to the April 2026 Synedrix OS canon. Revised to include the canonical mission → goal → task → action hierarchy and the task_surface sub-object. Supersedes: v0.1. Related artifacts: Synedrix OS - Taxonomy & Platform Spec, Synedrix OS - Workflow Contract Spec, Synedrix OS - Responsibility Matrix, Synedrix OS - Interoperability & Protocol Strategy.

Purpose link

This specification defines what an agent is in Synedrix OS as a governed, versioned, registry-discoverable software actor that participates in orchestrated workflows under explicit authority, contract, memory, tool, and interoperability constraints.

The intent is to give Synedrix OS a canonical agent-definition model consistent with the platform’s existing principles: bounded autonomy, orchestration as the center of gravity, governance before execution, scoped access to shared context, explainability by design, and standards-aware interoperability.

This specification is contract-centric, not prompt-centric. Prompts matter, but the durable system value in Synedrix OS comes from explicit authority, workflow contracts, policy bindings, observability, and reusable packaging boundaries.

Canonical definition link

An agent in Synedrix OS is a scoped software actor with a defined mission, authority boundary, input/output contract, tool permissions, memory scope, and escalation path.

Building on that taxonomy, an agent is further a first-class operating-system artifact with the following properties:

• Registered and discoverable through shared registry semantics.
• Participates in workflows through explicit roles declared in workflow contracts.
• Cannot bypass governance, approval, or observability controls when producing side effects.
• May use native adapters or MCP-backed tools — both governed through the same control model.
• May collaborate with external agents through A2A only as a bounded interoperability pattern at the platform edge.

Position in the architecture link

Core design principles link

Bounded autonomy. Every agent must have an explicit authority envelope. Authority boundaries must be machine-readable, not implicit in prompt text.

Workflow-first participation. Agents should not own workflows. Workflows are typed, versioned capabilities; agents participate through declared roles.

Governance before execution. High-impact actions require policy awareness and, where configured, approval gates or human review.

Layered truth. Memory is not a single generic bucket. Synedrix OS separates hot state, transactional truth, temporal truth, relationship truth, similarity truth, and observability truth across Redis, Postgres, QuestDB, Neo4j, Qdrant, Langfuse, PostHog, and Grafana/Prometheus.

Standards-aware but not protocol-led. MCP and A2A extend the OS at the interoperability boundary; they do not replace internal orchestration, governance, or observability.

Agent anatomy link

Every agent definition in Synedrix OS is built from the same sub-objects, each answering a different question about that agent.

The agent definition and its sub-objects, each with the question it answers:

flowchart LR
    A["Agent definition"]
    S1["Identity: Who is this agent"]
    S2["Purpose: Why does it exist"]
    S3["Authority: What may it do"]
    S4["Prompt policy: How should it behave"]
    S5["Contracts: What goes in and out"]
    S6["Tool permissions: What can it invoke"]
    S7["Memory profile: What can it remember and access"]
    S8["Task surface: What task classes can it handle"]
    S9["Workflow roles: Where can it participate"]
    S10["Interoperability: How it connects outward"]
    S11["Runtime policy: How it executes"]
    S12["Policy bindings: Which governance rules apply"]
    S13["Observability: How it is traced and evaluated"]
    A --> S1
    A --> S2
    A --> S3
    A --> S4
    A --> S5
    A --> S6
    A --> S7
    A --> S8
    A --> S9
    A --> S10
    A --> S11
    A --> S12
    A --> S13

Mission, goals, tasks, and actions link

A generic tasks field is underspecified for Synedrix OS. Understanding what “tasks” means requires a precise four-level hierarchy across agent definition, orchestration, and runtime.

The canonical hierarchy link

flowchart TD
  M[Mission: Why this agent exists, agent-owned, static]:::term --> G[Goal: A bounded desired outcome in a given context, workflow-owned]:::agent
  G --> T[Task: A structured unit of work handed to this agent, orchestration-owned]:::agent
  T --> A[Action: A single atomic step the agent performs to complete the task, agent runtime]:::agent

flowchart TB
    M["Mission: why this agent exists. Agent-owned, static"]
    G["Goal: a bounded desired outcome in a given context. Workflow-owned"]
    T["Task: a structured unit of work handed to this agent. Orchestration-owned"]
    A["Action: a single atomic step to complete the task. Agent runtime"]
    M --> G --> T --> A

The orchestrator decomposes goals into tasks, routes work to specialist agents, manages retries and sequencing, and coordinates approvals and escalations. Goal decomposition is the orchestration layer’s responsibility, not the agent’s.An agent only sees the task it has been handed, executes within its authority envelope, and returns a structuredoutcome (see Synedrix OS Outcome Spec).

What belongs where in the schema link

Two concerns must not be conflated:

• What an agent is capable of handling — static definition state → task_surface on the agent definition.
• What an agent has been asked to do right now — the durable invocation start and identity → agent_invocations; ephemeral execution progress → Redis.

task_surface schema link

task_surface:
  supported_task_classes:

    - validate-policy
    - synthesize-recommendation
  input_schema_per_class:
    validate-policy: schema://policy-guard/input/v1
    synthesize-recommendation: schema://risk/input/v1
  max_concurrent_tasks: 20
  task_timeout_ms: 5000
  escalation_on_timeout: true
  autonomous_task_classes:

    - synthesize-recommendation      # no approval gate needed
  approval_required_task_classes:

    - validate-policy                # policy gate required

The workflow_roles array binds a task class to a specific workflow:

workflow_roles:

  - workflow_id: WF-OPS-001-SUPPORT-TRIAGE
    role: validator
    task_class: validate-policy
    allowed_actions: [analyze, validate, emit-decision]
    confidence_threshold: 0.85
    escalation_rules: low-confidence-or-policy-conflict

Three separate tables link

1. agent_task_surfaces — static definition of task classes, approval requirements, timeouts. Agent definition layer, versioned.
2. workflow_task_assignments — which agent handles which task class in which workflow. Workflow registry.
3. agent_invocations plus agent_invocation_outcomes — append-only start and terminal records for actual task executions; Redis contains only ephemeral execution progress.

Normative field schema link

agent_id:
name:
status:
domain_scope:
capability_tags:
owner_team:

purpose:
  mission:
  non_goals:
  success_criteria:

authority:
  can_recommend:
  can_draft:
  can_execute:
  can_approve:
  can_delegate:
  risk_tier:
  approval_requirements:
  escalation_path:

prompt_policy:
  base_prompt_ref:
  role_prompt_ref:
  safety_overlay_ref:
  domain_overlay_ref:
  tenant_overlay_ref:
  environment_overlay_ref:
  version:

contracts:
  accepted_inputs_schema:     # Schema of structured JSON input this agent accepts.
  context_requirements_schema: # Schema of any additional context required at invocation.
  output_schema:              # Schema of outcome.result — the domain-specific payload inside the outcome envelope.
                              # The full outcome envelope shape is defined in Synedrix OS Outcome Spec v0.2.
  confidence_schema:          # Schema of outcome.quality.confidence (if this agent produces a confidence signal).
                              # Must declare: metric name, range (e.g., 0.0–1.0), and interpretation.
  emitted_events:             # OS events emitted alongside the outcome (not part of the outcome envelope itself).
  side_effect_declarations:   # Every persistent or external write this agent may produce.

tool_permissions:

  - tool_id:
    access_mode:
    operation_scope:
    side_effect_class:
    approval_tier:
    rate_limits:
    audit_mode:

memory_profile:
  # Store access (unchanged)
  working_memory:
  canonical_memory_access:
  semantic_memory_access:
  graph_memory_access:
  temporal_memory_access:
  audit_memory_access:
  retention_policy:

  # Memory-tier access (added v0.3). read | write | none.
  # `write` means "may propose"; only os-agt-010 commits.
  episodic_memory_access:
  procedural_memory_access:
  profile_memory_access:

  # Control-plane authority (added v0.3)
  recall_scope:          # session | agent | subject | tenant — the widest scope
                         # this agent may recall. Intersected with the request
                         # scope by os-agt-012 before the store is queried.
  promotion_authority:   # none | propose | commit — `commit` is reserved for
                         # os-agt-010; every other agent is `propose` or `none`.
  forget_authority:      # none | propose — erasure is always approved by
                         # os-agt-002 and executed by os-agt-010.
  retention_class:       # ephemeral | session | operational | durable | audit |
                         # regulated — the default class for records this agent
                         # forms. Instance config may narrow it, never widen it.

task_surface:
  supported_task_classes:
  input_schema_per_class:
  max_concurrent_tasks:
  task_timeout_ms:
  escalation_on_timeout:
  autonomous_task_classes:
  approval_required_task_classes:

workflow_roles:

  - workflow_id:
    role:
    task_class:
    allowed_actions:
    confidence_threshold:
    escalation_rules:

interop:
  a2a_profile:
  mcp_profile:

runtime_policy:
  runtime_engine:          # n8n-aiagent | langgraph (optional; defaults to n8n-aiagent)
                           # Declares which execution engine runs this agent. Cyclic/multi-agent
                           # execution_patterns (iterative, consensus, reflect-and-revise,
                           # hierarchical) require langgraph. See Agent Runtime Policy Spec v0.4
                           # and Orchestration & Runtime Strategy v0.1.
  model_routing:
  latency_budget_ms:
  token_budget:
  retry_policy:
  fallback_policy:
  max_tool_hops:
  concurrency_limit:

policy_bindings:
  policy_pack_ids:
  approval_matrix_id:
  compliance_labels:
  kill_switch_group:

observability:
  trace_level:
  langfuse_project:
  eval_suite_ids:
  cost_center:
  metric_tags:
  alert_policies:

Worked example: Policy Guard Agent (os-agt-002) link

The normative schema above is abstract. This section instantiates every field for a real OS-owned agent, os-agt-002 — Policy Guard Agent, so the schema has a concrete reference point. Policy Guard is a useful worked example because it is the agent the task_surface example above already borrows its validate-policy task class from, and because its approve-only decision scope exercises the authority, task-surface, and runtime fields differently from an execute-scope agent like the Orchestrator.

agent_id: os-agt-002
name: Policy Guard Agent
status: active
domain_scope: cross-domain               # control-plane function, not bound to any single domain pack
capability_tags: [policy-evaluation, risk-scoring, authority-enforcement]
owner_team: synedrix-os

purpose:
  mission: >
    Evaluate proposed actions against the active policy ruleset before execution
    proceeds, enforce authority boundaries, apply risk thresholds, and emit a
    binding allow/block/escalate decision that the Orchestrator Agent must respect.
  non_goals:
    - Does not execute the action it evaluates
    - Does not originate business logic or business decisions
    - Does not modify workflow state directly — decisions are binding but enforced
      by the Orchestrator Agent, not by Policy Guard itself
  success_criteria:
    - Zero policy-bypassing executions across all workflows
    - Decision latency stays within the invoking workflow's latency budget
    - Every decision carries a traceable policy_rule_triggered reference

authority:
  can_recommend: false
  can_draft: false
  can_execute: false
  can_approve: true
  can_delegate: false
  risk_tier: control-plane
  approval_requirements: none            # Policy Guard is itself a governance control, not a governed actor
  escalation_path: [os-agt-004, human-risk-owner]

prompt_policy:
  base_prompt_ref: prompt://os-agt-002/base/v1
  role_prompt_ref: prompt://os-agt-002/role/v1
  safety_overlay_ref: prompt://global/safety-overlay/v3
  domain_overlay_ref: null               # domain-agnostic control function — no domain pack overlay applies
  tenant_overlay_ref: prompt://tenant/{tenant_id}/policy-thresholds/v1
  environment_overlay_ref: prompt://env/production/strict-mode/v1
  version: 0.1

contracts:
  accepted_inputs_schema: schema://os-agt-002/input/v1
    # { action_type, action_payload, requesting_agent_id, workflow_id, domain, correlation_id, policy_context? }
  context_requirements_schema: schema://os-agt-002/context/v1
    # active policy pack version; tenant-specific risk threshold overrides
  output_schema: schema://os-agt-002/output/v1
    # { decision: allow|block|escalate, policy_rule_triggered?, risk_score?, reason, requires_hitl }
  confidence_schema: schema://os-agt-002/confidence/v1
    # risk_score, range 0.0-1.0; 1.0 = highest confidence the action violates policy
  emitted_events: [policy.evaluated, policy.blocked, policy.escalated]
  side_effect_declarations:
    - Audit record write to the Supabase audit trail — the only side effect this agent produces

tool_permissions:
  - tool_id: policy-rule-engine
    access_mode: native
    operation_scope: [evaluate]
    side_effect_class: none
    approval_tier: none
    rate_limits: 500 evaluations/min per workflow
    audit_mode: full
  - tool_id: risk-scoring-adapter
    access_mode: native
    operation_scope: [score]
    side_effect_class: none
    approval_tier: none
    rate_limits: 500 evaluations/min per workflow
    audit_mode: full
  - tool_id: audit-log-writer
    access_mode: native
    operation_scope: [write]
    side_effect_class: append-only-write
    approval_tier: none
    rate_limits: none
    audit_mode: full

memory_profile:
  working_memory: none
  canonical_memory_access: read (policy store) / write (audit trail only)
  semantic_memory_access: none
  graph_memory_access: none
  temporal_memory_access: none
  audit_memory_access: write
  retention_policy: audit records retained per compliance_labels; policy store retention is out of scope for this agent
  episodic_memory_access: none
  procedural_memory_access: none
  profile_memory_access: none
  recall_scope: none                    # this agent evaluates policy against the payload it is handed; it recalls nothing
  promotion_authority: none
  forget_authority: none                # it *approves* erasure as a policy decision, which is not the same as proposing one
  retention_class: audit

task_surface:
  supported_task_classes: [validate-policy]
  input_schema_per_class:
    validate-policy: schema://os-agt-002/input/v1
  max_concurrent_tasks: 200
  task_timeout_ms: 800
  escalation_on_timeout: true
  autonomous_task_classes: []             # every evaluation is a governance function, never an unattended autonomous action
  approval_required_task_classes: [validate-policy]

workflow_roles:
  - workflow_id: WF-OS-POLICY-EVAL
    role: validator
    task_class: validate-policy
    allowed_actions: [evaluate, score, decide, emit-decision]
    confidence_threshold: n/a             # risk_score drives the decision directly; this agent has no accept/reject confidence gate
    escalation_rules: risk_score above tenant threshold, or policy rule ambiguity

interop:
  a2a_profile: none                      # never exposed at the A2A edge — policy evaluation is an internal control-plane function
  mcp_profile: none                      # all tool bindings are native adapters over internal policy and audit stores

runtime_policy:
  runtime_engine: n8n-aiagent            # deterministic rule evaluation; no cyclic/multi-agent reasoning required
  model_routing: rules-first; LLM invoked only to disambiguate free-text policy_context on ambiguous action payloads
  latency_budget_ms: 800
  token_budget: 2000                     # consumed only on the disambiguation path
  retry_policy: 1 retry on transient policy-store read failure; never retried after a block/escalate decision is reached
  fallback_policy: on rule-engine unavailability, default to block + escalate — fail closed, never fail open
  max_tool_hops: 3
  concurrency_limit: 200

policy_bindings:
  policy_pack_ids: [os-core-policy-v1, tenant-risk-thresholds-v1]
  approval_matrix_id: os-approval-matrix-v1
  compliance_labels: [sox-relevant, audit-required]
  kill_switch_group: control-plane

observability:
  trace_level: full
  langfuse_project: synedrix-os-control
  eval_suite_ids: [policy-guard-regression-v1, policy-guard-fail-closed-v1]
  cost_center: os-control-plane
  metric_tags: [family:control, layer:9, decision_scope:approve]
  alert_policies:
    - alert if block rate deviates more than 20% from the 7-day rolling baseline
    - alert if fallback_policy triggers more than once per hour

Three design choices in this instantiation generalize to any approve-scope control agent:

• autonomous_task_classes is empty. An agent whose entire mission is to gate other agents’ actions has nothing to run unattended — every task it handles is, by definition, subject to the approval framework it enforces. Contrast this with an execute-scope agent, where autonomous_task_classes is typically the larger of the two lists.
• fallback_policy fails closed. When the rule engine is unavailable, the agent defaults to block + escalate rather than allow. Any control-plane agent — anything with can_approve: true or can_execute: true — must define a fallback that preserves the governance invariant under infrastructure failure, not one that optimizes for availability.
• No a2a_profile or mcp_profile. Not every agent needs an interoperability surface. Policy Guard is a purely internal control function; declaring none explicitly (rather than omitting the fields) keeps the schema self-documenting about what was considered and deliberately excluded.

System prompt model link

A raw system_prompt field is too narrow. Since Langfuse is already the prompt-versioning and trace layer, prompt behaviour should be a versioned prompt-policy object.

Prompt-policy layers:

• Base prompt — stable identity and operating stance.
• Role prompt — agent-specific behaviour instructions.
• Safety and governance overlay — platform-wide restrictions.
• Domain overlay — domain-pack vocabulary and constraints.
• Tenant or business-instance overlay — thresholds and customer-specific behaviour.
• Environment overlay — for example stricter production guidance or verbose development logging.

Tools and MCP link

Each tool binding should carry governance and operational metadata:

• Tool ID and adapter type.
• Access mode — native adapter or MCP-backed invocation.
• Allowed operations and side-effect class.
• Approval tier and policy requirements before writes.
• Rate limits, retry rules, idempotency expectations, and audit mode.

MCP should be adopted read-first. Write-capable tools should be introduced only once approval and permission semantics are clear.

Memory model link

Memory has two orthogonal axes. The store table below is the substrate axis and is unchanged. The tier axis — what kind of memory a record is — is defined in Memory Fabric Spec §3, which is authoritative for the memory model. memory_profile declares access on both axes, and it remains a security boundary rather than a configuration detail.

Three rules constrain what any agent may declare:

• write on a tier means “may propose”. Only the Memory Curator (os-agt-010) commits durable memory.
• recall_scope is a ceiling, not a request. The Memory Access Broker (os-agt-012) intersects it with the request scope and pushes the result into the store query before retrieval.
• Recall is a tool call. An agent with neither tool:memory-recall nor tool:memory-propose in its resolved active tool set has no memory access, whatever its profile says.

A2A communication model link

A2A is a bounded edge-interoperability pattern. External A2A collaborators are bounded peers, not trusted internal components by default.

Recommended A2A fields:

• Exposed endpoint IDs.
• Accepted task types and contract versions.
• External trust tier and authentication requirements.
• Allowed data scopes and redaction rules.
• Correlation-ID and lineage propagation requirements.
• Approval gates before acting on A2A-originated tasks with side effects.
• Timeout, retry, and sandboxing behaviour.

Responsibility split link

Canonical artifacts per agent link

1. Agent Definition Spec: identity, mission, authority, contracts, tools, memory profile, task surface, workflow roles, interoperability profile.
2. Agent Runtime Policy Spec: model routing, limits, retries, budget, fallback, concurrency, observability requirements.
3. Agent Evaluation Spec: test cases, policy assertions, regression checks, approval conditions, quality thresholds.

Recommended database tables link

agent_definitions
agent_versions
agent_prompt_layers
agent_authority_profiles
agent_contracts
agent_tool_bindings
agent_memory_profiles
agent_task_surfaces
agent_workflow_roles
workflow_task_assignments
agent_policy_bindings
agent_mcp_profiles
agent_a2a_profiles
agent_runtime_policies
agent_observability_profiles
agent_invocations
agent_evaluations
agent_lineage_links

Invariants link

• Every agent has explicit authority boundaries.
• Every agent participates through structured contracts.
• No agent bypasses policy-aware orchestration for side effects.
• Memory access is scoped by truth layer and purpose.
• MCP and A2A are interoperability extensions, not internal architectural replacements.
• OS, domain-pack, and business-instance boundaries remain intact.
• Every production-relevant agent is observable, auditable, and versioned.

Versioning link

• Version: 0.3
• Supersedes: v0.2
• Related artifacts: Synedrix OS - Taxonomy & Platform Spec, Synedrix OS - Workflow Contract Spec, Synedrix OS - Responsibility Matrix, Synedrix OS - Interoperability & Protocol Strategy, Synedrix OS - Agent Runtime Policy Spec, Synedrix OS Orchestration & Runtime Strategy

Related Documents link

Canonical Reference link

• Synedrix OS - Consolidated Canonical Reference — Consolidated synthesis; the agent model defined here underlies the OS agent descriptions in §4.

Registry and Lifecycle link

• Synedrix OS - Agent Registry Spec — Registry schema; the agent_id and other fields defined here are stored in the registry.
• Synedrix OS - Agent Registry — Full registry entries for the twelve OS-owned agents using the schema defined here.
• Synedrix OS — Naming Convention Spec — Authoritative reference for agent_id patterns and archetype codes.

Runtime and Evaluation link

• Synedrix OS - Agent Runtime Policy Spec — Runtime policy schema; governs how agents defined here are executed and model-routed.
• Synedrix OS - Agent Evaluation Spec — Evaluation dimensions and promotion gates; applies to agents defined using this spec.
• Synedrix OS - Agent DB Schema — Relational schema for persisting agent definitions, execution starts, outcomes, and lineage.

Architecture link

• Synedrix OS - Taxonomy & Platform Spec — Canonical taxonomy; §2.4 defines the agent concept and §7 provides the agent taxonomy.
• Synedrix OS - Responsibility Matrix — Capability-by-capability ownership split; governs which agents belong in OS vs domain packs.
• Synedrix OS - Workflow Contract Spec — Workflow standard; agents are invoked within workflows governed by this contract.
• Synedrix OS - Interoperability & Protocol Strategy — MCP and A2A protocol strategy; the A2A communication model in this spec implements that strategy.

Synedrix OS · Agent Spec · April 2026