{"slug":"platform/23-agent-runtime","title":"23 — Agent Runtime","section":"platform","sectionLabel":"Platform","status":"unclassified","type":"document","path":"platform/23-agent-runtime.mdx","bytes":3503,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n> **Extracted from:** IntegrateWise Platform Specification Suite\n> **Region:** third_region\n> **Original line:** 3085\n> **Lines:** 54 | **Chars:** 3,220\n> **Status:** Raw extraction — requires review and canonicalization\n\n23 — Agent Runtime\n23.1 Responsibilities\nOwn the Agent Registry, lifecycle, memory, permissions, scheduling, communication, supervision, and failure handling for automated agents beyond the Twin (Twin is itself an Agent, but is documented in 06 with persona-fit specialization).\n23.2 Agent kinds (canonical)\nTwin (inherits 06, persona-bound).\nWorker Agent — runs inside a Workflow step (11), no persona-fit, transactional.\nSupervisor Agent — watches Worker Agents and Twin health, can pause/restart.\nBackground Agent — runs from a cron or Event, e.g., TwinAgent (morning brief), TenantBrainDO (approvals).\nCommunity Agent — contributed via Marketplace (13); sandboxed.\n23.3 Inputs\nWorkflow step launch, cron schedule, Event Bus trigger, Manual admin launch.\nContinuity context (25).\n23.4 Outputs\nCapability invocations (05), Memory intakes (07), Signals (10), Workflow handoffs (11).\n23.5 Events produced\nAgentRegistered, AgentScheduled, AgentStarted, AgentPaused, AgentResumed, AgentStopped, AgentFailed, AgentSupervisedAction, AgentCommunicationSent, AgentCommunicationReceived.\n23.6 Events consumed\nWorkflowStarted, WorkflowStepDue, CronTick, EventBus\\*, TwinRoutedRequest.\n23.7 APIs\nPOST /agents, POST /agents/{ag_id}/schedule, POST /agents/{ag_id}/pause, POST /agents/{ag_id}/resume, POST /agents/{ag_id}/invoke, GET /agents/{ag_id}/runs.\n23.8 State transitions\ndeclared → registered → scheduled → running → paused → resumed → stopped → failed → archived. Health watch: healthy → degrading → critical → quarantined.\n\n23.9 Agent lifecycle specification\nMandatory metadata: id, kind, capabilities[], permissions[], memory_scope, owner, contacts[].\nPermissions inherit from capability-level requiredScopes + agent-level overrides.\nRun traces appended to Observability (16); supervision emits AgentSupervisedAction.\n23.10 Agent registry\nPersistent in D1 (agents.agents, agents.runs, agents.permissions).\nDiscoverable per workspace via Projection Engine (04).\n23.11 Agent memory\nmemory_scope chooses: Twin-meaning (07/L1) for ephemeral, Organizational Memory (07/L7) for durable.\nAgents may not write directly to Spine (02) — only via Capability Fabric (05).\n23.12 Agent permissions\nEach agent declares requiredScopes[] evaluated through 09 Governance.\nCross-workspace calls require gov.cross_workspace token.\n23.13 Agent scheduling\nTrigger types: cron, Event Bus (filter), Time-window, Manual, Chain.\nTime windows enforced in DO durable alarms.\n23.14 Agent communication\nTwo patterns: (a) Capability invocation through 05; (b) Async envelope through Event Bus.\nAll envelopes signed; recipient validates.\n23.15 Agent supervision\nSupervisor Agent checks HealthSnapshot (08.7-style), run success rate, drift metrics.\nAllowed actions: pause, restart, route to fallback model (22), quarantine.\n23.16 Failure handling\nPer Agent kind: restart policy varies.\nTwin: rehydrate context from 25; do not lose conversation state.\nWorker Agent: idempotent retry, max N=3.\nCommunity Agent: quarantine + admin notify.\nCross-agent failure cascade: Supervisor Agent breaks the loop.\n23.17 Extension points\nNew Agent kinds via registry; reviewed for sandbox if kind=community.\nCustom runners (e.g., remote executor) via AGENT_RUNNER(name).\n"}