Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Plugin Model

This page defines the plugin boundary for Toolang runtime integrations.

Toolang currently treats these areas as pluggable:

  • memory
  • channel
  • sandbox

Design goal

Plugins make Toolang open to:

  • local implementations
  • remote managed implementations
  • first-party integrations
  • third-party integrations

The boundary should remain:

  • small
  • explicit
  • easy to diagnose
  • easy to replace

Core principle

Toolang core owns:

  • execution lifecycle
  • scheduling
  • local truth-layer state
  • prompt and run traces
  • shared bus projection

Plugins own only their domain-specific input and output operations.

Rules:

  • plugins return structured data
  • plugins do not mutate Toolang core state directly
  • plugins do not decide scheduling policy
  • plugins do not become the primary execution truth

Plugin families

Memory

Memory plugins provide:

  • recall
  • remember
  • health

Channel

Channel plugins handle message ingress and egress. They may support:

  • polling
  • hook decoding
  • outbound delivery
  • health checks

Sandbox

Sandbox plugins provide execution environments. They may support:

  • one-shot invoke execution
  • long-lived runtime spawning
  • liveness probing
  • stop and cleanup

Loading model

Plugins should be selected by explicit config and loaded by name.

Recommended discovery mechanism:

  • Python package entry points
    • toolang.memory
    • toolang.channel
    • toolang.sandbox

Recommended loading flow:

  1. read source config
  2. resolve environment variables and relative paths at the call site
  3. build an explicit plugin spec
  4. load the named plugin factory
  5. construct the plugin instance with explicit config

Configuration

Each plugin family should use one plugin name and one config object.

Examples:

[memory]
plugin = "sqlite"
 
[memory.config]
path = ".toolang/agents/alice/memory.db"
[channels.telegram]
plugin = "telegram"
 
[channels.telegram.config]
token_env = "TELEGRAM_BOT_TOKEN"
chat_id = "12345678"
owner_chat_id = "87654321"
[sandbox]
plugin = "docker"
 
[sandbox.config]
image = "python:3.13"
network = "bridge"

Runtime boundary

Responsibility split:

  • runtime loop receives or generates input
  • runtime converts that input into Message and turn requests
  • scheduler admits work
  • execution strategy completes the turn
  • runtime persists local state
  • runtime appends bus events
  • plugins perform only their domain-specific operations

Diagnostics and replaceability

Every plugin interaction should be traceable. Useful fields include:

  • plugin family
  • plugin name
  • request summary
  • provider response summary
  • degraded mode details
  • error details

Replaceability should happen by selecting another plugin or config, not by adding a new runtime architecture mode.

Read next

© 2026 Toolang