Core Agent Runtime and Orchestrator¶
Az agent runtime az a software subsystem, amely egy goalt kontrollált, több lépéses executionné alakít. Az orchestrator ennek központi koordinációs komponense lehet, de nem szabad god objectté válnia, amely minden concernt maga tulajdonol.
Hasznos mental model:
Create Run
↓
Load canonical state
↓
Build context
↓
Ask model for next decision
↓
Validate / authorize
↓
Execute capability
↓
Record observation
↓
Update state + budgets
↓
Continue / wait / stop
A loop lifecycle-t a runtime tulajdonolja, nem a model.
Runtime responsibilityk¶
Production runtime tipikusan koordinálja:
- run creationt és azonosítókat,
- lifecycle state-et,
- canonical execution state-et,
- context assemblyt,
- model invocationt,
- action/skill/tool routingot,
- policy és authorization checkeket,
- budget accountingot,
- retryt és recoveryt,
- checkpointokat,
- cancellationt,
- timeout kezelést,
- observabilityt és auditot.
Ezek több modulban vagy service-ben is élhetnek. A runtime fogalmi subsystem, nem feltétlenül egyetlen class.
Run mint first-class application concept¶
Az agent execution legyen explicit object:
AgentRun
├── run_id
├── tenant_id
├── goal
├── status
├── current_step
├── state_version
├── plan
├── observations
├── approvals
├── budgets
├── artifacts
├── failure_history
├── started_at
└── updated_at
Tipikus statusok:
CREATED
RUNNING
WAITING_FOR_HUMAN
WAITING_FOR_EXTERNAL_EVENT
COMPLETED
FAILED
CANCELLED
BUDGET_EXHAUSTED
Lifecycle status ne a legutolsó chat message-ből legyen visszakövetkeztetve.
Execution ID-k és step ID-k¶
Használj stabil azonosítókat:
run_id = one logical execution
step_id = one state transition / decision step
tool_call_id = one capability invocation
Ezek támogatják:
- tracinget,
- idempotencyt,
- replayt,
- debuggingot,
- tool resultok korrelációját,
- failure utáni resume-ot.
Orchestrator mint coordinator¶
Egy tiszta orchestrator delegálja a specializált concernöket:
AgentOrchestrator
├── RunRepository
├── ContextBuilder
├── DecisionEngine / ModelGateway
├── CapabilityRegistry
├── PolicyService
├── BudgetService
├── ActionExecutor
├── CheckpointService
└── Telemetry
Konceptuális flow:
def execute_step(run_id):
run = run_repository.load(run_id)
policy.assert_runnable(run)
budget.assert_available(run)
context = context_builder.build(run)
decision = decision_engine.decide(context)
validated = action_validator.validate(decision, run)
policy.authorize(validated, run)
result = action_executor.execute(validated)
updated = state_transition.apply(run, validated, result)
budget.record(updated, result)
run_repository.save(updated)
Az explicit ownership fontosabb, mint a konkrét implementation.
State machine mental model¶
A runtime legyen state machine-ként érthető:
RUNNING
├─ model selects tool ─────────→ RUNNING
├─ asks user ──────────────────→ WAITING_FOR_HUMAN
├─ waits for job/event ────────→ WAITING_FOR_EXTERNAL_EVENT
├─ success conditions met ─────→ COMPLETED
├─ terminal failure ───────────→ FAILED
├─ budget exceeded ────────────→ BUDGET_EXHAUSTED
└─ cancellation requested ─────→ CANCELLED
A transitionöket code validálja. A model status=COMPLETED outputja proposal, nem authoritative state change.
Model gateway¶
A provider interaction centralizálható model gateway/port mögött.
A gateway kezelheti:
- provider/model selectiont,
- structured outputot,
- inference timeout/retryt,
- token/cost accountingot,
- provider error normalizationt,
- tracing metadata-t,
- fallback/routing policyt.
Példa interface:
class AgentDecisionPort(Protocol):
def decide(self, request: AgentDecisionRequest) -> AgentDecision: ...
A runtime typed decisiont fogyasszon, ne vendor response objectet.
Capability registry¶
A runtimenak tudnia kell, milyen actionök érhetők el egy run számára.
Registry metadata lehet:
capability id
name
description
input schema
output schema
required permissions
risk level
side-effect classification
handler / adapter
version
A capability setet lehetőleg a model előtt szűrjük:
all registered tools
↓
tenant policy
↓
user permissions
↓
run-specific allow-list
↓
model-visible capabilities
Ez biztonságosabb, mint mindent megmutatni és remélni, hogy a model nem választ tiltott toolt.
Policy coordination¶
Policy a modellen kívül marad.
Az orchestrator policy service-t hívhat például:
- permission checkre,
- action risk classificationre,
- approval requirementre,
- tenant restrictionre,
- data-access rule-ra,
- maximum autonomy levelre.
Decision: SEND_EMAIL
↓
Policy check
↓
low risk internal draft? → execute
external recipient? → approval required
restricted recipient? → reject
Action executor¶
A validated actionből capability invocation lesz.
Responsibilityk:
- input validation,
- idempotency key,
- scoped credential,
- timeout,
- retry policy,
- normalized result envelope,
- audit metadata.
Ne engedd, hogy arbitrary capability name/arguments ellenőrzés nélkül folyjon a model outputból infrastruktúrába.
Long-running runok¶
Az agentic execution gyakran hosszabb egy HTTP requestnél.
API
↓
Create AgentRun
↓
Queue / Scheduler
↓
Worker executes step
↓
Checkpoint
↓
reschedule next step / wait
Előny:
- crash recovery,
- pause/resume,
- human approval,
- external-event waiting,
- controlled concurrency,
- horizontal scaling.
Checkpointing¶
Meaningful state transition után checkpointolj:
- plan accepted,
- external side effect completed,
- approval requested,
- tool observation recorded,
- subtask completed.
A checkpointból a run model message-ek rekonstruálása nélkül folytatható legyen.
Optimistic concurrency¶
Két worker ne írja felül egymást ugyanabból a régi state-ből.
load version 17
compute transition
save WHERE version = 17
↓
version becomes 18
Ha más már írt version 18-at, reload/reconcile kell.
Ez különösen fontos callback, human approval, parallel subtask és queue redelivery mellett.
Cancellation¶
Cancellation runtime feature, nem prompt instruction.
A runtime:
- jelölje a cancellation requestet,
- ne indítson új actiont,
- próbálja cancelálni az interruptible external worköt,
- reconcile-olja az in-flight side effectet,
- persistálja a final state-et.
Irreversible action után cancellation azt jelenti: „ne folytasd tovább”, nem time travel.
Timeout layer-ek¶
Külön timeout lehet:
model call timeout
capability/tool timeout
step timeout
run deadline
human approval expiry
external wait deadline
Egyetlen global timeout gyakran elrejti a valódi failure boundaryt.
Retry ownership¶
A retry ott történjen, ahol a layer érti a failure-t.
- provider HTTP 503 → model gateway retry,
- idempotent API timeout → action executor retry/reconcile,
- invalid business input → repair/replan, nem transport retry,
- rossz stratégia → orchestrator replan.
Kerüld az egymásra rakódó invisible retrykat.
Sync vs async orchestrator¶
Egyszerű runtime lehet synchronous:
request → several bounded steps → response
Fejlettebb runtime lehet durable/asynchronous:
run → queue → worker → checkpoint → event → worker → completion
A rendszer a run duration, reliability és scaling igény szerint fejlődjön.
Anti-patternök¶
- God orchestrator: prompt, SQL, provider SDK, authorization, tool és state update egy classban.
- Stateless loop chat history fölött.
- Model-controlled lifecycle.
- Registry policy filtering nélkül.
- Retry minden layeren shared budget nélkül.
- Non-durable long run, amely process crashnél elveszik.
Minimal architecture progression¶
Stage 1
bounded synchronous orchestrator
+ typed state
+ explicit tools
Stage 2
persistent run state
+ checkpoints
+ approvals
Stage 3
queue/workers
+ durable resume
+ parallel subtasks
Stage 4
specialized scaling / multi-agent only if justified
Takeaways¶
- A runtime tulajdonolja az agent lifecycle-t, nem a model.
- A run legyen explicit object stabil ID-val és canonical state-tel.
- Az orchestration validált state transitionökből álló state machine-ként kezelhető.
- Model gateway, context building, policy, execution és persistence külön responsibility legyen.
- Capabilityket még a model előtt szűrj permission/policy szerint.
- Cancellation, timeout, retry, checkpoint és concurrency deterministic runtime feature.
- Queue/durable worker csak akkor kell, amikor a run karakterisztikája indokolja.