Runnables

A runnable is callable work with an input/output contract. Toolang has two authored kinds: agics and flows. An agent can expose several runnables and reuse them across scripts and drivers.

Agics and flows

An agic runs a model/tool loop: the model follows instructions, calls permitted tools, and produces a result. An agic can make several model calls before it finishes.

A flow executes explicit operations that call runnables, transform collections, repeat work, or transfer control. The flow determines the order of operations; its agics supply model-driven decisions within those operations.

Instructions and context

instruct supplies behavioral instructions; context supplies runtime data. Bare agic text is user-message content; user: and assistant: define explicit message templates. Templates such as {{_}} insert bound input values.

Selected caps contribute guidance and reusable input. Historical context comes from recall. These sources have distinct roles even though they contribute to one model call.

Inputs and outputs

Signatures

A signature declares primary input _, named arguments, and the result type after ->.

struct Summary:
  headline: Text
  points: Text[]
 
agic summarize(_: Text, audience: Text) -> Summary:
  Summarize {{_}} for {{audience}}.

Here, _ carries source text, audience is a separate argument, and Summary requires a structured result.

Input values

Templates such as {{_}} insert bound values into messages.

Types include Text, Number, Boolean, Json, arrays, and structs. ? marks an optional argument or field. An untyped _ accepts Part[]: text, images, audio, or documents. Omitting the parameter list implies primary input; () declares no inputs.

A content line starting with @file includes content; $prompt expands a prompt. File inclusion and workspace access are separate.

Return values

An agic's default output is Text. A flow returns its final _; results normally replace _, while let name = ... binds a named local instead.

Composition

A .too module can group runnables, types, caps, instructions, and context:

agic summarize(_) -> Text:
  Summarize {{_}} in three bullets.
 
flow brief(_) -> Text:
  run summarize
  run -> Text:
    Rewrite {{_}} for a general audience.

brief calls summarize, then passes its result to an inline agic. Definitions are reusable; runs record their executions.

Delegation and handoffs

Operation	Relationship
`run`	Call a child runnable, then continue with its result
`async run` and `await`	Start a child, continue other work, then wait for its result
`exec`	Transfer the current run to another runnable, which owns its result
`spawn`	Start independent work with its own root run

An agic's hands selects targets it may call or spawn; handoffs selects targets it may transfer to. A handoff changes the runnable within the same run rather than creating another agent. Flow statements express these operations directly.

Unfinished child calls are canceled when their caller ends or transfers control. Independent spawned work has its own lifetime. Flow spawn starts a new thread; the runtime tool can also use an inspected idle local thread.

See Run agent scripts for invocation and Grammar for syntax.