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:
| Type | Description | Example |
|---|---|---|
| Resident | A locally managed agent. | too eve chat |
| Visiting | An agent loaded from a remote source. | too gh:briceyan/gus chat |
| Roaming | An 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:
| Type | Example root |
|---|---|
| Resident | ~/.toolang/ |
| Visiting | /tmp/toolang/... |
| Roaming | DIR/.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:
- Preparation — Resolve agent definitions, configuration, and caps, and initialize the required state and resources.
- Sandboxing — Set up the selected sandbox, either on the host or inside a Docker container with the required dependencies.
- Serving — Start the runtime and activate its configured drivers to handle interactive sessions, scheduled tasks, and agent-to-agent communication.
- 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.