Skills, spawnable, reply

Three optional fields available only on kind: llm agents. Each exposes a different runtime capability to the model — mid-run skill loading, concurrent sub-agents, and streaming intermediate messages.

Skills

Named skill bundles the agent may load mid-run via the synthetic use_skill tool. The model decides when (and whether) to load them, based on the task at hand.

skills:
  - citation-style
  - markdown-rendering

Rules:

• Skill names must match ^[a-z][a-z0-9-]*$.
• Names resolve against the runtime's SkillStore — same store you configure in agntz({ skills: ... }) (embedded) or in Settings → Skills (hosted).
• The model sees skill names + descriptions in its tool list; it can call use_skill to pull a skill's full instructions into context.
• Calling a skill twice is a no-op — the runtime tracks what's loaded.

Skills are how you split very large instructions into reusable bundles without inflating every prompt. The model loads only what it actually needs.

Spawnable

Sub-agents the LLM may spawn concurrently at runtime via the synthetic spawn_agent tool. Predefined per agent — the LLM cannot invent agents, only invoke the ones you list.

spawnable:
  - kind: ref
    agentId: fact-checker
  - kind: inline
    definition:
      id: adhoc-helper
      kind: llm
      model: { provider: openai, name: gpt-5.4-mini }
      instruction: "Extract dates from the input"

Rules:

• kind: ref — reference an existing agent by id.
• kind: inline — define the sub-agent inline. Must itself be kind: llm with a static (non-templated) instruction.
• The model sees the spawnable agents in its tool list and calls spawn_agent({ id, input }) to invoke one.
• Spawned agents run in parallel with the parent; each gets its own state and its own trace span nested under the parent.

Use spawnable when you want the model to fan out work it identifies during execution — for example, fact-checking each claim in a draft.

Reply

Register a per-invocation reply tool the model can call to deliver intermediate messages. Replies surface as SSE events on streaming endpoints, so your UI can show progress before the final answer.

reply: true                  # defaults: maxPerRun = 50

# or
reply:
  maxPerRun: 5

The model sees a tool called reply with a single string parameter; calling it emits a reply event in the run's stream. Pair with client.agents.stream(...) to surface progress to a user:

for await (const event of client.agents.stream({
  agentId: "long-task",
  input: { ... },
})) {
  if (event.type === "reply") ui.append(event.text);
  if (event.type === "complete") ui.finalize(event.output);
}

Replies are stored on the session alongside messages, so when a session resumes the model can see what it told the user previously.

Compatibility

All three fields work in embedded and hosted mode. spawn_agent and use_skill are synthetic tools — the runtime injects them; you don't need to declare them under tools:.