Agentic

@startuml
!include <agentic/core>

title Research analyst — capability matrix

' VIEWPOINT: Capability matrix — which agent has which tools, knowledge and
' model tier? Nest them: braces are containment, so everything inside the agent
' below IS the agent's surface. With no edges among them there is no sequence,
' so a solo agent with ten unordered tools draws as one node with capability
' strips rather than a fake pipeline.
'
' There is no attachment macro. Braces are the only thing that means
' containment, so a capability two agents SHARE is declared in each of them —
' which is honest about the fact that each carries its own copy of that
' contract.
' A skill is the third kind, and the conditional one:
'   Skill_Context  instructions only, folds into the agent as a chip
'   Skill_Actions  has a procedure — modelled with steps, like a sub-agent
' Unlike a sub-agent it runs in the CALLING agent's context, so it costs that
' agent's window rather than opening its own.
' Say where each tool LIVES, because it decides who can change it:
'   Tool      external — someone else's contract, versioned with them
'   CodeTool  a function in this repo, shipped and changed with the agent
' There is no binding to declare: a tool in the flow is called on the way
' through, one in a strip is called at the model's discretion.
' DONE WHEN: no agent has a capability nobody can explain, every skill states
' when it loads, and every tool says whether it is ours.

Actor(researcher, "Analyst")
Channel(req, "Research request", "chat · carries question, deadline")

Agent(analyst, "Research analyst", "opus-5 · effort xhigh · adaptive thinking") {
  Tool(t_search, "Web search")
  Tool(t_fetch, "Fetch page")
  ' In our code, not behind a service: a function that ships with the agent and
  ' changes in the same pull request. Same binding question, very different cost
  ' to change and very different failure mode — an external tool can break while
  ' nothing in this repo does.
  CodeTool(ct_run, "run_analysis", "agent/tools/analysis.py")
  CodeTool(ct_ask, "ask_the_user", "agent/tools/interrupt.py")
  Knowledge(kb, "Internal reports", "vector · 8 chunks · max distance 0.6")
  Knowledge(graph, "Entity graph", "graph · company -> filing -> person")
  ' A skill is capability that is only PRESENT sometimes — loaded when its
  ' trigger matches, which is what separates it from more system prompt. The
  ' trigger is the description argument, and it is the defining property: one
  ' without it either always loads (so it is instructions) or never does, while
  ' still costing description budget.
  Skill_Context(sk_cite, "House citation style", "always — every figure needs a source")
}

' The one container other than a Zone whose children may be wired to each
' other, and it earns it rather than being exempt: a skill runs in the CALLING
' agent's context, so these steps are the caller's own steps and the order is
' the caller's to keep. A SubAgent is the opposite case — its contents are
' capability, unordered, because it decides internally in a window of its own.
Skill_Actions(sk_dive, "Deep-dive a filing", "when the question turns on a specific filing") {
  Tool(sd1, "Fetch the filing")
  Tool(sd2, "Extract the tables")
  State(sd3, "Reconcile against prior years")
  Rel(sd1, sd2)
  Rel(sd2, sd3)
}

Exit_Complete(done, "Report delivered")
Exit_Human(human, "Handed to a human")

Rel(researcher, req)
Rel(req, analyst)

Rel_LLM(analyst, sk_dive, "a filing needs reading in full")

Rel_LLM(analyst, done, "question fully answered")
Rel_LLM(analyst, human, "needs a judgement call")
@enduml