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

Running Agents

The toolang CLI covers the full lifecycle of an agent: create it, sync it, run it, and keep it available through a local API.

Create or discover an agent

toolang new <name>
toolang clone <agent_ref>
toolang list
toolang remove <agent_selector>

Use new for a fresh local agent. Use clone when the source starts from a local path or a remote reference.

Sync before execution

toolang sync <agent_selector>

sync is the boundary between authored source and runtime state. It resolves cap refs, writes scope-separated synced output, and records the exact runtime inputs that later commands can reuse.

The three run surfaces

toolang invoke <agent_selector>
toolang run <agent_selector>
toolang start <agent_selector>

Choose them this way:

  • invoke run one request in a one-shot process
  • run keep the agent in the foreground and expose its local HTTP API
  • start launch the agent as a long-lived background process

For long-lived runtimes, Toolang separates:

  • runtime loops they decide when work starts
  • execution strategy it decides how one turn completes

That keeps run and start predictable even when agents later gain more runtime loops such as polling or hooks.

In practice:

  • use invoke in scripts, CI, or editors
  • use run when you want the local API and logs in the current shell
  • use start when the agent should keep running after you leave the terminal

Select the same agent in multiple ways

Most commands accept an agent selector. In practice that can be:

  • a simple local name such as ship-docs
  • a home/agent selector
  • a local file path
  • a canonical URI
  • a stable short known-agent identifier

Per-agent and shared APIs

Started agents expose a local HTTP API for:

  • health and runtime metadata
  • synced capability metadata
  • chats and chat streams
  • runs and run traces
  • agent-scoped event streams

Toolang can also expose a shared bus API:

toolang bus serve

That shared API lists known and active agents, surfaces global run and event projections, and can route requests to active agents through one local entry point.

Read next

© 2026 Toolang