# Native Agents and Durable Circuits > Declare typed agents, compose durable multi-agent circuits, fan work out with parallel, and admit dynamic specialists without widening authority. Sema has two multi-agent constructs: - `agent` declares a typed, bounded model actor. - `circuit` declares durable orchestration using ordinary Sema control flow. That is the entire language addition. There is no separate graph DSL, mailbox language, or keyword for every orchestration pattern. Assignments carry values, `parallel` creates fan-out/fan-in, `spawn` creates an owned task, `if` and `match` choose paths, and contracts form gates. :::note[Agent loop or native agent?] Use [Building an Agent Loop](/guides/agent-loops/) when one function owns a bounded reasoning loop. Use native agents and circuits when work needs typed roles, parallel branches, dynamic specialists, durable resume, or governed delegation between actors. ::: ## Mental model | Surface | Meaning | |---|---| | `agent name(input) -> Output by model:` | A typed model/tool loop with a role instruction, hard contracts, and a budget | | `circuit name(input) -> Output !{effects}:` | A durable function whose calls and control flow form a work graph | | `parallel [worker(x) for x in xs]` | Ordered, bounded fan-out followed by fan-in | | `spawn worker(input)` | An owned `Task[Output]` that may run independently | | `task.join()?` | Wait for the task and propagate a typed task failure | | `Agent.build(spec, under=envelope)?` | Validate a dynamically proposed specialist inside fixed authority | `agent` and `circuit` are soft keywords. They are recognized only where a declaration can begin, preserving the wider identifier namespace. ## Declare a typed agent An agent looks like a function, but the runtime owns its bounded model↔tool loop. The declaration fixes its input, output, role, model, tools, budget, and completion contracts: ```sema def search(query: str) -> str !{}: return "source:" + query agent researcher(question: str) -> str by research_model: sem "Collect one attributable finding and separate fact from inference" use tools [search] budget model_calls=2, tokens=512 ensure len(result) >= 1 ``` Tools remain ordinary effect-typed Sema functions. The agent's effect row is derived from its model, selected tools, and delegated child pool; it is not duplicated in the declaration. At `assure silver` or higher, every agent must have an explicit `model_calls` limit. The call completes only when the model output decodes to the declared type and its hard contracts pass. Budget, decode, policy, stall, and contract failures remain typed failures; a model judge cannot overrule them. ## Compose a circuit A circuit is normal Sema with durable agent calls: ```sema agent writer(evidence: list[str]) -> str by writer_model: sem "Synthesize evidence with provenance and explicit uncertainty" budget model_calls=1, tokens=512 ensure len(result) >= 1 circuit synthesize(questions: list[str]) -> str !{model.invoke}: budget agents=8, spawn_depth=0, model_calls=16, tokens=8000 evidence = parallel [researcher(question) for question in questions] return writer(evidence) ``` The comprehension is the topology: ```text ┌─ researcher(question 1) ─┐ questions ── parallel ───├─ researcher(question 2) ─┼── evidence ── writer └─ researcher(question 3) ─┘ ``` `parallel [expression for item in items]` is the canonical ordered comprehension form. There is deliberately no `par` alias; `par` remains an ordinary identifier. Sema may dispatch static read-only or disjoint agents in isolated child sessions. Dynamic agents and work with overlapping or unknown mutation scope are conservatively serialized. ## Decisions, gates, and repair loops Circuits do not need display-oriented syntax. Ordinary constructs carry the meaning: ```sema if issue.failed: specialist = Agent.build(spec, under=envelope)? finding = (spawn specialist(issue)).join()? draft = writer(finding) verification = verifier(draft) ensure verification.passed return draft ``` The runtime derives: | Program construct | Observed graph shape | |---|---| | `parallel` | fork and merge | | value dependency | edge between work units | | `spawn` / `join` | task edge and synchronization point | | `if` / `match` | decision and selected path | | `loop until` / bounded loops | repeated, bounded subgraph | | `ensure`, policy, approval, completion policy | gate with pass, wait, or fail state | This makes generator→reviewer→repair, panels, routing, monitor-triggered intervention, and recursive orchestrator→worker patterns library patterns over one language rather than new syntax. :::note[Circuit visualization] The observation ABI for fork, merge, decision, gate, budget, artifact, stall, and resume events is specified. The interactive viewer is a planned Cortex integration, not a shipped Sema UI. It will extend existing Cortex task-watch and Control surfaces; OMP can consume the same redaction-safe event stream as a thin view adapter. Sema will not add a visualization CLI or a second scheduler. ::: ## Spawn owned work Use `spawn` when the parent should continue before synchronizing: ```sema circuit deliver(request: ChangeRequest) -> PatchArtifact !{agent.spawn, model.invoke}: budget agents=4, spawn_depth=1, model_calls=8, tokens=6000 evidence = explorer(request) implementation = spawn engineer(evidence) patch = implementation.join()? return hardener(patch) ``` `spawn` returns an owned `Task[T]`. A child cannot outlive its circuit: circuit exit joins or cancels outstanding children, and cancellation propagates through the owned subtree. Lifecycle states are `pending`, `running`, `awaiting_signal`, `suspended`, `complete`, `failed`, and `cancelled`. ## Admit a dynamic specialist When the required role depends on runtime evidence, an orchestrator can propose an `AgentSpec`. `Agent.build` admits it only under a typed envelope: ```sema from std.agents import AgentSpec, AgentEnvelope spec = orchestrator(issue) specialist = Agent.build(spec, under=envelope)? finding = (spawn specialist(issue)).join()? ``` The envelope fixes input/output types, allowed models, tool subset, child limits, and sub-budget. Delegated authority is always the intersection of the sealed root, circuit policy, parent policy, envelope, and spawn-site grant: ```text child authority = sealed root ∩ circuit ∩ parent ∩ envelope ∩ spawn grant ``` A child cannot mint a tool, effect, model, policy, child pool, or fresh budget. Every child charge accrues to all enclosing budgets. Data-only `AgentSpec` admission is distinct from staged `Code[Agent[I,O]]`, which additionally needs an explicit envelope plus `code.exec("agent-sandbox")` and `agent.spawn`. ## Durability and resume The outer circuit owns one local run under `.sema/runs//`: - atomic session state; - segmented JSONL events; - content-keyed completed-leaf memos; - content-addressed artifacts. Stable leaf identity includes the circuit symbol, callsite, agent semantic hash, serialized input digest, parent path, and dynamic ordinal. Resume reuses unchanged completed leaves. It may retry an incomplete read-only leaf, but an external mutation without recorded completion suspends as `NeedsReconciliation` instead of guessing. One run's durable life, end to end: ```mermaid flowchart LR R["sema circuit run"] --> J[".sema/runs/<run-id>/\natomic session state\nsegmented JSONL events\nleaf memos + artifacts"] J -->|"crash or interrupt"| S["sema circuit resume\n<run-id>"] S --> M["completed leaves reused\n(content-keyed memos)"] M --> D["unfinished leaves re-run;\nexternal mutation without a\nrecorded completion suspends as\nNeedsReconciliation"] D --> C["run completes"] ``` ```bash sema circuit run examples/agent-research sema circuit list examples/agent-research sema circuit show examples/agent-research sema circuit resume examples/agent-research sema circuit cancel examples/agent-research ``` These commands manage the durable aggregate. They are not a separate orchestration engine; the circuit remains ordinary checked Sema. ## Standard roles and patterns [`std.agents`](/reference/stdlib-api/agents/) provides typed specifications, envelopes, pools, artifacts, work units, and domain-neutral role presets: `Researcher`, `Architect`, `Orchestrator`, `Reviewer`, `Verifier`, `Writer`, and `Monitor`, plus the scoped coding presets `Explorer`, `Engineer`, and `Hardener`. [`std.circuits`](/reference/stdlib-api/circuits/) provides ordinary-library patterns for pipelines, fan-out/fan-in, specialist routing, generator→reviewer→repair, panels, monitor intervention, approval gates, and provenance-preserving artifact aggregation. [`std.completion`](/reference/stdlib-api/completion/) adds contract-first, bounded belief completion. Deterministic contracts and policy denials always take precedence over probabilistic evidence. ## Worked projects - [`agent-research`](/reference/examples-api/agent-research/) — parallel research fan-out, ordered evidence merge, and typed synthesis. - [`agent-software`](/reference/examples-api/agent-software/) — explorer, owned engineer task, and hardener handoff. - [`agent-scientific`](/reference/examples-api/agent-scientific/) — a failed experiment triggers a dynamically admitted proof auditor; publication stays blocked until deterministic verification passes. For the normative details, see [Native agents and durable circuits](/reference/language-spec/05-construct-catalog/#554-native-agents-and-durable-circuits), the [generated grammar](/reference/grammar/), and the [effects catalog](/reference/effects-catalog/).