Evaluation, Observability and Architecture Patterns¶

Egy production agent architecture addig nem teljes, amíg a failure nem rekonstruálható és a változtatás nem evaluálható deployment előtt és után. Mivel a behavior a model + context + skill + tool + state + policy + environment kombinációjából alakul ki, observabilitynek és evaluationnek a teljes execution pathot kell lefednie, nem csak a final generated textet.

Hasznos trace hierarchy:

Run
├── Step
│   ├── Context build
│   ├── Model call
│   ├── Policy decision
│   ├── Capability/tool call
│   ├── Retrieval call
│   └── State transition
├── Step
└── Final outcome

Az architecture ezt a struktúrát eleve observable-lé tegye.

Minek kell observable-nek lennie?¶

Egy runról válaszolható legyen:

What goal was requested?
Which runtime/skill/policy/model versions were used?
What state did the run start from?
Which observations/evidence were available?
Which action was proposed?
Was it allowed/denied/approved?
Which capability actually executed?
What result came back?
How did state change?
Why did the run stop?
How much time/cost did it consume?

Ehhez nem kell hidden chain-of-thought tárolása. Structured decision, input/output, evidence reference és state transition operationally hasznosabb.

Trace identifier-ek¶

trace_id
run_id
step_id
model_call_id
capability_call_id
observation_id
approval_id
artifact_id

Lehetőség szerint propagáld queue, worker és external adapter között. Így például egy MCP adapter log line-ja összeköthető azzal az agent steppel, amely kiváltotta.

Structured event model¶

Free-form logging mellett typed eventek:

RunStarted
ContextBuilt
ModelDecisionReceived
ActionRejectedByPolicy
ActionApproved
CapabilityCallStarted
CapabilityCallSucceeded
ObservationRecorded
RunCheckpointed
RunCompleted
RunFailed

Példa:

{
  "event": "CapabilityCallSucceeded",
  "run_id": "run_123",
  "step_id": "step_8",
  "capability": "pull_request.create",
  "version": "1",
  "latency_ms": 840,
  "effect": "WRITE",
  "result_status": "SUCCESS"
}

Sensitive-data logging¶

Observability ne legyen új data leak.

Ne logolj kritikátlanul:

secrets
full customer records
entire prompts
private documents
raw tool responses
access tokens

Használj reference-t, hash-t, redactiont és structured summaryt, megfelelő retention policyval.

Model-call observability¶

Hasznos metadata:

provider
model
model profile/version
input token count
output token count
latency
cost estimate
structured-output validity
tool-choice outcome
retry count
fallback used

Debughoz policy szerint tárolható exact sanitized context vagy olyan reference set, amely canonical source-okból reprodukálható.

Context observability¶

Rögzíthető:

context strategy version
included source types
evidence IDs
memory IDs
freshness metadata
token allocation per section
items dropped due to budget
trust classifications

Így megválaszolható például: retrieval nem találta meg a policyt, vagy a context builder dobta ki budget miatt?

Capability/tool observability¶

Actionönként:

requested capability
validated arguments (redacted)
policy result
approval result
adapter/provider
latency
retry/reconciliation behavior
normalized result/failure
side-effect identifier

Side-effect ID unknown outcome reconciliationhöz különösen fontos.

State-transition observability¶

A run state machine transitionje explicit legyen:

RUNNING
→ WAITING_FOR_APPROVAL
→ RUNNING
→ COMPLETED

Record:

old state
new state
state version
trigger event
step/run ID

Unexpected transition attempt legyen látható error.

Evaluation layer-ek¶

Ne legyen egyetlen monolithic „agent accuracy” score.

Model/decision evaluation¶

correct classification?
appropriate action?
structured output valid?

Skill evaluation¶

contract followed?
relevant issue found?
allowed capabilities used efficiently?

Retrieval evaluation¶

Recall@k
Precision@k
ranking quality
grounding coverage
ACL leakage

Tool/capability evaluation¶

schema correctness
failure normalization
idempotency behavior
authorization enforcement

Loop/trajectory evaluation¶

success rate
steps to completion
unnecessary calls
replans
retries
premature stop
loop explosion

End-to-end outcome¶

was the user/business goal achieved?
was result correct, safe and useful?

Layered evaluation segít lokalizálni a regressziót.

Offline eval pipeline¶

Code / prompt / skill change
        ↓
Unit + contract tests
        ↓
Deterministic integration tests
        ↓
Offline agent eval set
        ↓
Safety / policy evals
        ↓
Cost + latency comparison
        ↓
Regression gate
        ↓
Canary / production

Agent change ugyanazzal a fegyelemmel kezelendő, mint code change.

Eval dataset¶

Representative case-ek:

happy paths
ambiguous requests
missing information
conflicting evidence
provider failures
stale observations
prompt injection attempts
permission denial
approval required
long-running/resume cases
budget exhaustion

Demo promptokból álló dataset nem jó production predictor.

Deterministic vs model-based grader¶

Ami deterministic property, azt deterministic graderrel mérd:

JSON schema valid
correct API endpoint selected
forbidden tool not called
file exists
tests pass
no cross-tenant document retrieved
budget not exceeded

Semantic qualityhoz model-based grader vagy human review:

response usefulness
review completeness
tone
semantic relevance

Model grader is probabilisztikus, ezért kalibráld és versionöld.

Trajectory evaluation¶

Két agent ugyanazt a final answer-t adhatja:

Agent A:
3 steps, 2 reads, success

Agent B:
18 steps, 9 redundant reads, 3 retries, success

Outcome-only eval mindkettőt successfulnak látja, trajectory eval megmutatja az architecture problémát.

Metric:

steps per successful run
model calls per success
tool calls per success
repeated-action rate
replan rate
no-progress rate
human escalation rate
cost per success

Production metrics¶

run success/failure/block rate
p95 run latency
queue wait time
cost per successful run
provider fallback rate
capability error rate
approval rate
retrieval miss rate
budget exhaustion rate
resume-after-failure success
stuck-run count
security/policy denial count

Breakdown workload, skill, model profile, runtime version, tenant és capability szerint, privacy megtartásával.

Regression gate¶

Példa threshold:

critical-task success >= 95%
forbidden-write rate = 0
schema validity >= 99.9%
p95 cost increase <= 15%
retrieval ACL leakage = 0

Nem kell minden metricnek javulnia, de a trade-off legyen explicit.

Shadow és replay testing¶

Historical trace új model/skill/runtime ellen replayelhető real side effect nélkül:

recorded input + observations
        ↓
new runtime/model
        ↓
proposed trajectory
        ↓
compare

Write adapter helyett simulator/mock fusson.

Failure injection¶

Teszteld kontrolláltan:

model timeout
rate limit
tool 503
queue redelivery
worker crash after side effect
stale state conflict
retrieval unavailable
approval expires
sandbox crash

Ha system csak akkor működik, amikor minden dependency sikeres, nem production-ready.

Visszatérően erős architecture patternök¶

Deterministic shell a probabilistic decision körül¶

validate → model decides → validate → authorize → execute → verify

Ports and adapters¶

business capability
→ port
→ provider adapter

Durable orchestration¶

canonical run state + checkpoints + event-driven resume

Explicit context builder¶

canonical sources
→ trust/freshness/budget filters
→ temporary model context

Capability registry policy filteringgel¶

all capabilities
→ identity/task/risk filter
→ effective tool set

Deterministic workflow agentic islanddal¶

Autonomy bounded marad ismert business processen belül.

Evidence-first verification¶

Tests, tools és system of record erősebb, mint repeated self-reflection.

Architecture anti-patternök¶

Giant prompt architecture¶

Business rule, security, workflow és provider config egy promptban.

Monolithic Agent class¶

Agent
├── prompts
├── database
├── GitHub
├── billing
├── memory
├── RAG
├── retries
└── authorization

Ez normál God Object AI névvel.

Hidden state¶

Correct execution olyan facttől függ, amely csak conversation/contextben él.

Provider SDK everywhere¶

Provider/vector DB/MCP type-ok átfolynak domain/application code-ba.

Unrestricted tool access¶

Minden run minden capabilityt lát.

Agent everywhere¶

Simple deterministic operation is LLM decision lesz, felesleges cost/failure-rel.

Vector DB mint application DB¶

Operational state, memory és document retrieval egy similarity store-ba olvad.

Multi-agent by default¶

Coordination complexity measurable quality gain nélkül.

Observability = raw transcript dump¶

Drága, sensitive, és mégsem mutat structured state transitiont.

Architecture review kérdések¶

Where is canonical state?
Who owns authorization?
What can the model actually decide?
Which side effects require approval?
Where are provider-specific dependencies?
How are capabilities typed and versioned?
How does context get built?
How is untrusted evidence separated from instruction authority?
Can a run resume after worker failure?
How are retries/idempotency handled?
How is tenant isolation enforced?
Can we trace one run end to end?
Can we evaluate a change before production?
Why is each service/agent boundary necessary?

Ha ezekre nincs világos válasz, valószínűleg hidden coupling van.

Completion mental model¶

Business capabilities and domain rules
          ↓
Application use cases / ports
          ↓
Durable agent runtime
  ├── canonical state
  ├── explicit context builder
  ├── policy / authorization
  ├── skills / capabilities
  ├── budgets / recovery
  └── observability
          ↓
Infrastructure adapters
  ├── models
  ├── retrieval
  ├── MCP/connectors
  ├── queues
  ├── databases
  └── external services

Az AI-specific komponensek normál software architecture-be illeszkednek, nem helyettesítik azt.

Engineering takeaways¶

A teljes runt trace-eld, ne csak model callt/final textet.
Structured eventet és stable ID-t használj worker, tool, retrieval és state transition között.
Layerenként evaluálj a regresszió lokalizálásához.
Deterministic propertyhez deterministic grader, semantic propertyhez calibrated model/human grader.
Trajectory efficiencyt is mérj final outcome mellett.
Production change safety, quality, cost és latency regression gate-en menjen át.
Replay, shadow testing és failure injection hasznos model/runtime upgrade-nél.
Figyeld a giant prompt, God-agent, hidden state, provider leakage, unrestricted tool és unjustified multi-agent anti-patternöket.
Observability tartsa tiszteletben privacy és secret boundarykat.
Jó agent architecture felismerhetően jó software architecture explicit probabilisztikus komponensekkel.