Create and run agents

Learn how to create, run, and inspect agents with the Toolang CLI.

Create agents

Create an agent named eve:

too new eve

You can also clone an existing agent or a shared definition:

too clone eve bob
too clone gh:briceyan/gus gus

Each agent has its own home. Inspect an agent or open a shell in its home:

too eve info
too eve cd

By default, Eve's home is ~/.toolang/agents/eve/. Edit agent.too to customize its instructions and runnables.

Agent names must start with a lowercase letter and contain only lowercase letters, digits, and underscores.

To remove an agent, stop it first if it's running, then run:

too remove eve

Removal deletes the agent's home and history but preserves its managed lab workspace.

Start an interactive chat with Eve:

too eve chat

Chat automatically prepares and starts the agent's server when needed. See Chat in the terminal for working with threads and instances.

To start the server explicitly in the background:

too eve start

The server remains available after Chat exits. Stop it with:

too eve stop

Stopping preserves the agent's home and execution history.

Drivers determine how an agent receives work. The available drivers are chat, chore, and talk.

By default, start enables all three drivers for a stopped resident agent. Automatic startup through Chat enables only chat.

Use --enable to specify the complete set of drivers:

too eve start --enable chat
too eve start --enable chat,chore

Calling start on an already running server preserves its current drivers. Stop the server before changing them.

See Drivers for details.

Toolang supports two sandbox types: host (default) and docker.

Use --sandbox to run an agent in Docker with a specified image:

too eve start --sandbox docker:python:3.12

Toolang automatically installs the runtime dependencies needed to run the agent in the selected image.

Changing the sandbox or workspace mounts requires restarting the server.

See Sandboxes for details.

List local agents and their status:

too ls

To see active agents, including visiting agents, and the Hub:

too ps

Both commands show agent status, while ps includes running agents beyond those stored in the local Toolang root.