AI Agents Need a Semantic Layer, Not More Data: UnifiedModel Boosts Accuracy 10-20%

The Problem: Agents Have Data but Lack System Structure

AI agents can write code, call tools, plan multi-step tasks, and retrieve logs, metrics, traces, and change records. Yet when placed in a real production system and asked "What's wrong with payment-gateway right now?" they often give plausible but dangerous answers. The issue isn't that individual tools return wrong data — CPU 88%, P99 2150ms, a slow trace are all correct. The problem is these are isolated phenomena; the agent doesn't know which object they belong to, how objects connect, who depends on whom, or which upstream configuration changed recently. This is the "blind men and elephant" problem: metrics, logs, traces, tickets, and code repositories each capture a real fragment, but no unified structure tells the agent what the whole elephant looks like.

Typical reactions — stronger models, longer context, RAG, memory, more MCP tools, multi-agent collaboration — address "more capability" and "more data" but not "system structure." Accessing all systems doesn't equal understanding the system; having all fragments in context doesn't equal knowing their relationships.

Solution: A Semantic Layer as an External World Model

What's missing is a semantic layer that materializes objects, relationships, fields, observational evidence, and actionable context from the real system. For an agent, a complex system should be a queryable "world model" covering:

Objects: services, hosts, databases, configs, deployments, teams, alerts

Connections: service calls service, service runs on host, deployment affects service, config applies to trace

Fields per object type: status, owner, SLO, lifecycle, primary key, tags

Observational evidence attached to objects: metrics, logs, traces, events, runbooks

Actions executable under conditions: rollback, rate-limit, scale, retry adjustment

In information science this is ontology — the study of what types of things exist in a domain and how they relate. UnifiedModel brings this idea to engineering systems using a small set of unified primitives to describe a digital-twin object graph.

The semantic layer doesn't copy all data into a new database or stuff document chunks into a vector store. It acts like a system map: agents still call Prometheus, SLS, Elasticsearch, MySQL, Kubernetes, CMDB, but they start from "objects," follow relationships to evidence, then generate executable queries or operation plans.

UnifiedModel Design & Capabilities

3.1 Minimal Primitives: Set + Link + Field

UnifiedModel converges the object graph to three core primitives:

EntitySet ──DataLink──> DataSet ──StorageLink──> Storage
  │
  └──EntitySetLink──> EntitySet

Minimal observability example: platform.service is an EntitySet representing services. platform.host is another EntitySet for hosts. runs_on relationship is an EntitySetLink.

Service latency, error rate, QPS live on a MetricSet via a DataLink.

That MetricSet maps to Prometheus or SLS via a StorageLink. latency_p99_ms is a Field with type, unit, semantics, and query mapping.

The key is not just drawing a graph but making it queryable, verifiable, and discoverable by agents.

3.2 Classes and Instances: Model Once, Write Continuously

Two layers are easily confused: class (definition) and instance (runtime).

Class (TBox) : Defines what fields an object type has, its primary key, which data sets it can link, which entities it can relate to. Described by EntitySet, DataSet, Link, Field.

Instance (ABox) : Real entities like checkout-service, payment-gateway, catalog-api; real relationships like payment-gateway calls risk-control. These are continuously written, updated, expired as the system runs.

Simplified definition layer (YAML):

kind: entity_set
domain: platform
name: platform.service
pk:
  - id
fields:
  - name: id
    type: string
    semantic_role: entity_id
  - name: status
    type: string
  - name: latency_p99_ms
    type: double
    unit: ms

Runtime instance write:

{
  "entity_set": "platform@[email protected]",
  "entity_id": "payment-gateway",
  "fields": {
    "status": "degraded",
    "latency_p99_ms": 2150
  }
}

This separation matters: classes let agents know "what types and methods exist in the world"; instances show "what's happening in the real world right now." Together they form a living object graph.

3.3 Runtime: Shared Query Surface for Humans and Agents

UnifiedModel Runtime adds a semantic runtime atop existing systems, not a new isolated platform. Four layers:

Access : Web UI, CLI, Skill, MCP Gateway — usable by both humans and agents.

Runtime Service : Workspace, definition validation, entity/relation writes, query service, Agent Gateway.

Graph Abstraction : Unified encapsulation of objects, relationships, methods, data sets, storage mappings.

Storage : Memory, files, graph DB, plus external sources (Prometheus, SLS, ES, MySQL).

3.4 Unified Query: SPL Covers Definitions, Entities, Topology, Data Plans

Object graph must be stably queryable. UnifiedModel uses SPL query surfaces: .umodel — query model definitions and metadata .entity — query concrete entities .entity_set — invoke methods on an entity type (list data sets, generate metric/log plans) .topo — query topology relationships and neighbors .runbook_set — query runbooks and action suggestions bound to objects

Entity query example:

.entity with(domain='platform', name='platform.service')
| project id, display_name, status, owner
| limit 20

Topology query from an object:

.topo
| graph-call getNeighborNodes(
    'platform@[email protected]',
    'payment-gateway',
    2
  )

Method invocation is key. Agents first ask an EntitySet what methods it exposes, then call by signature. A service object may expose get_metrics, get_logs, list_data_set. The call returns an executable plan (PromQL, SLS query, ES DSL, or structured query plan), not raw data — reducing hallucination and mis-query risk.

.entity_set with(
  domain='platform',
  name='platform.service',
  ids=['payment-gateway']
)
| entity-call get_metrics('latency_p99_ms', '5m')

3.5 AI-Friendly: Self-Description, Progressive Disclosure, MCP & Skills

"Agent-friendly" means giving the runtime discoverability, not dumping docs into the model.

Self-description & progressive disclosure : Agents call __list_method__ to learn available methods, parameters, returns — context isn't flooded, agents don't guess.

MCP Gateway : Exposes query, explain, example, validation via standard protocol. Read tools enabled by default; write tools off or require explicit auth; resources expose only metadata; all access goes through Query Service.

Skills : Package common capabilities (object-graph query, RCA, impact analysis) as loadable skills so Claude Code, Cursor, Codex share the same semantic layer instead of each writing custom adapters.

Design principle: let agents discover first, then call; get a plan first, then execute; go through semantic layer first, then hit underlying tools.

UnifiedModel in Practice

4.1 Onboarding: From Real System to Queryable Object Graph

Three steps:

Model : Write model-pack YAML defining entities, fields, relationships, data sets, storage mappings. Validate with umctl umodel validate, import with umctl umodel import.

Write runtime instances : Continuously write entities, relations, lifecycle, state, observational evidence. Sources: CMDB, Kubernetes, OpenTelemetry Resource, service catalog, deployment system; relations from call traces, config systems, code dependencies, manual entry. Commands: umctl entity write, umctl topo write.

Graph becomes queryable : Humans use .entity and .topo with Explorer auto-visualization; agents discover methods via MCP and Skills, generate query plans, execute troubleshooting workflows.

Process can start small — one scenario, one domain, one service chain — and grow incrementally. Future automation (auto-registration, OTel mapping, service discovery, code scanning) will lower onboarding cost.

4.2 Case 1: Read Metrics by Object, Not Hand-Written PromQL

Question: "How is payment-gateway doing?"

Without semantic layer , agent must guess:

Which service object corresponds to payment-gateway?

Which system holds the metrics?

What's the exact metric name for P99?

Label: service, service_id, or app?

Unit: seconds or milliseconds?

Any mistake yields plausible but unusable results.

With object graph : .entity locates platform.service/payment-gateway.

Follow DataLink to its MetricSet and LogSet.

Call get_metrics to generate query plan with entity ID, window, unit conversion, metric semantics auto-applied.

Agent answers:

Status: degraded QPS: 4200 Error rate: 14.8% P99: 2150ms Replicas: 5/5 Key: these numbers are retrieved "by object." Agent doesn't need to learn PromQL dialect or guess labels; the object graph translates "that service" into a precise query.

4.3 Case 2: RCA by Traversing Relationships, Not Guessing Recent Releases

Scenario: payment-gateway P99 breaches SLO. Why?

Object graph provides a traversable relationship chain:

Flash Sale
 └─triggers─> cfg-checkout-retry
      └─affects─> checkout-service
            └─calls─> payment-gateway

This chain connects business event, config change, upstream service, affected service. Agent doesn't just see payment-gateway slow; it walks upstream to find "upstream checkout's retry config was bumped by flash sale and amplified traffic."

It also eliminates red herrings. A deployment payment-gateway v3.2.1 12 hours ago looks suspicious, but relations and evidence show it only changed log format — doesn't explain P99 breach. Agent avoids mechanically blaming the latest release.

Quantitative analysis:

4000 QPS × 3.5x flash-sale traffic × (5 / 2) retry amplification = 35000 QPS
35000 / 4000 = 8.75x

Conclusion:

Root cause: upstream retry increased from 2 to 5, combined with flash-sale traffic.

Overload ~8.75x original capacity.

Recommended action: roll retry back to 2, add rate limiting.

Benchmark: DataAgentBench

On the DataAgentBench benchmark, adding the semantic layer improved four flagship models by 10-20 percentage points. GLM-5.2 reached 50.2% pass@1.

Conclusion: Model the Real World First, Then Organize Data

In the Agent era, the real gap isn't more fragments but a structure that organizes them. Data are phenomena; objects and relationships are system structure.

UnifiedModel's core attempt: use Set + Link + Field to build real systems into a queryable, traversable, executable object graph; expose it via SPL, Runtime, MCP, and Skills for shared human-agent use; close the loop of data, knowledge, and action so agents don't just "see metrics" but understand systems along real relationships.

One sentence: model the real world first, then organize data. The semantic layer is the infrastructure of the Agent era.