Agentic

@startuml
!include <agentic/core>

title Order refund — L3 Flow

' VIEWPOINT: Flow — what happens step by step, and where does it branch?
'
' A SubAgent is an AGENT, not a boundary drawn round some steps. It has its own
' model, its own tools and its own hooks, exactly like a leaf agent — the only
' difference is that it also contains the steps it runs internally.
'
' So the WORKFLOW LINKS AGENT TO AGENT: Rel(entry, orchestrator), not
' Rel(entry, welcome). Reaching into a sub-agent to wire up one of its steps
' says the caller knows how that agent is built, which is exactly the coupling
' a sub-agent exists to prevent. Internal steps connect to each other; exits may
' leave from inside, because giving up is a fact about the step that gave up.
'
' Rel_Expr is a deterministic guard, Rel_LLM is the model's judgement.
'
' Whether reaching a tool RUNS the call is not something you type — it follows
' from where the tool sits. A tool in the flow is reached, so the call happens;
' a tool folded into a capability strip has no position, so nothing guarantees
' it. The renderer reads that off the diagram.
' DONE WHEN: every branch carries a typed guard, and no edge reaches past an
' agent's boundary into its internals.

Channel(entry, "Handoff from triage", "api · carries order_id, verified_customer, intent")

SubAgent(orchestrator, "Orchestrator", "haiku-4-5 · effort low") {
  ' Say is prompted — the model writes the words. Say_Explicit is fixed text,
  ' emitted verbatim: the AI disclosure has to be the sentence legal approved,
  ' not a fresh paraphrase of it each call.
  Say_Explicit(welcome, "Welcome + AI disclosure")
  Tool(verify, "Look up the order", "OrderLookup v1.0.0")
  State(idcheck, "Identity check", "writes customer_verified")
  Knowledge(kb, "Returns policy", "vector · 8 chunks · max distance 0.6")
}

SubAgent(specialist, "Refund specialist", "opus-5 · effort high") {
  Say(sp_say, "Apologise + explain")
  Requirement(sp_readback, "Read back the refund figure", "instructed only")
  State(sp_capture, "Capture amount", "writes refund_amount")
  Say_Explicit(sp_confirm, "Confirm + receipt")
  ' Discretionary tools belong to the specialist, in no particular order — the
  ' same capability strip a leaf agent gets.
  Tool(t_calc, "Calculate refund")
  Tool(t_issue, "Issue refund")
  Skill_Context(sk_rules, "Refund eligibility rules", "when a refund amount is being decided")
  Control(gr_pii, "PII redaction", "before-tool · blocking")
}

Exit_Human(human, "Escalate to support")
Exit_Complete(done, "Refunded")

' ── the workflow: agent to agent ──────────────────────────────────────────
Rel(entry, orchestrator)
Rel_LLM(orchestrator, human, "cannot identify the order")
Rel_Expr(orchestrator, specialist, "customer_verified == true")
Rel_Expr(specialist, done, "refund_amount > 0")
Rel_Expr(specialist, human, "refund_amount <= 0")

' ── internals: each agent's own sequence ──────────────────────────────────
Rel(welcome, verify)
Rel(verify, idcheck)
Rel(sp_say, sp_readback)
Rel(sp_readback, sp_capture)
Rel(sp_capture, sp_confirm)
Rel_LLM(sp_say, human, "customer disagrees")
@enduml