Skip to content
LogoLogo

Agents

A Toolang agent is defined in files containing its runnables, caps, and runtime configuration. The Toolang runtime prepares and executes the agent in a managed environment.

Agent types

Toolang supports three types of agents:

TypeDescriptionExample
ResidentA locally managed agent.too eve chat
VisitingAn agent loaded from a remote source.too gh:briceyan/gus chat
RoamingAn agent running from a local script.too aid.too chat

All three share the same filesystem structure and execution model.

Agent files

Each agent has an agent home under an agent root.

AGENT_ROOT/
├── config.toml
├── {runnables,psyches,skills,services,prompts}/
├── .state/
├── .runtime/
└── agents/
    └── AGENT/
        ├── agent.too
        ├── config.toml
        ├── {runnables,psyches,skills,services,prompts}/
        ├── .state/
        └── .runtime/

The agent root location depends on the agent type:

TypeExample root
Resident~/.toolang/
Visiting/tmp/toolang/...
RoamingDIR/.toolang/

The agent root provides shared configuration and resources, while each agent home contains its own definitions, configuration, and data.

The .state/ directories hold cached data that can be rebuilt, while .runtime/ stores persistent execution records and history.

Agent runtime

The runtime operates in four stages:

  1. Preparation — Resolve agent definitions, configuration, and caps, and initialize the required state and resources.
  2. Sandboxing — Set up the selected sandbox, either on the host or inside a Docker container with the required dependencies.
  3. Serving — Start the runtime and activate its configured drivers to handle interactive sessions, scheduled tasks, and agent-to-agent communication.
  4. Shutdown — Stop the runtime and its drivers, ending active execution.

While serving, an agent can handle multiple clients and independent runs. After shutdown, its execution records remain available for future sessions.

See Create and run agents and Run agent scripts for usage.