Tubeless agents
Agents are pipelines.
An agent is a pipeline of LLM turns and tool calls. The model chooses what runs next. Tubeless runs the steps and keeps track of what happened.
Tool calls are steps. Subagents are child pipelines. You can trace the whole run, reuse a pipeline as a tool, or put an agent in the middle of a larger workflow.
verifierSubagent / child pipeline
Each model turn can choose a new batch of tools or finish. The graph grows as the agent works; the turns above show one possible run.
Prompt an agent in your terminal.
Use your own agent with bunx tubeless agent <agent-id|file>. Select a project with --project or a file export with --export. Chat retains its model, tools, environment, and conversation. Read the agent selection guide.
Export OPENAI_API_KEY to child processes, then start the prompt loop from your workspace:
bunx tubeless agent --model gpt-5.4-mini For Anthropic, export ANTHROPIC_API_KEY and run bunx tubeless agent --provider anthropic. Set ANTHROPIC_MODEL or pass --model to choose a model; /model stays within the selected provider.
Or keep the key in a local dotenv file and run bunx tubeless agent --env-file .env.agent. Existing environment values take precedence over the file. If the key is already set in your shell, export OPENAI_API_KEY makes it available to Tubeless.
Enter a task, watch its pipeline execution, read the answer, and prompt again. Agent mode uses the same reporter as tubeless run: shimmer, colors, spinners, elapsed time, and logs alongside nested model turns and tool calls. Wide terminals show a separate log pane; redirected output uses plain pipeline logs.
Tool activity shows what is happening: file paths for reads, writes, and edits; command previews for bash; paths and queries for listing and searching. The tree and logs include completion summaries such as bytes written, lines read, and command exit codes.
The bike-inspired ◯╱◯ ❯ prompt has cyan accents. Press Tab to complete a slash command, or Tab twice after / to list commands. Completed prompts retain conversation, answers, and tool history. Use /model <name> to change models, /clear to start fresh, or /quit to exit. Ctrl-C cancels active work and returns to the prompt.
Other pipelines can use createSteps().waitForInput to wait for terminal, web, or application input through a pluggable read callback. Read the input-step guide.
Configure named services with --model-module ./agent-models.ts --provider baseten. Each entry chooses its API adapter, endpoint, credentials, and model. A single model factory also works with --model-module ./model.ts. Run one task with --prompt. Read the provider configuration guide.
Use agents wherever you use pipelines.
A pipeline can ask an agent to investigate a problem, then pass its answer to the next step. An agent can call an existing pipeline as a tool, or delegate work to another agent.
It is the same execution model in both directions. Inputs and outputs are validated. Each child agent has its own state, and its work counts toward the parent’s execution limits.
pipeline → agent → next stepUse fromPipeline to run an agent inside a workflow and consume its answer.
agent → tool → pipeline or subagentUse pipelineTool to give an agent a capability you have already built.
Example: use an agent’s answer in the next pipeline step
import { createSteps, definePipeline } from "tubeless";
import { definePipelineCommand } from "tubeless/cli";
import { DelegatingAgent } from "./agent-delegation.js";
import { textOptions } from "./agent.js";
const { step, fromPipeline } = createSteps(textOptions);
// Agents compose like any other child pipeline; the validated options are forwarded.
const answer = fromPipeline("answer", { pipeline: DelegatingAgent });
const report = step("report", {
dependsOn: [answer],
description: "Consume the agent's validated answer in ordinary pipeline work.",
run: ({ answer }) => answer.answer,
});
export const AgentPipeline = definePipeline({
id: "agent-pipeline",
description: "Embed a delegating agent in an ordinary pipeline, including dry-run previews.",
steps: [answer, report],
finalize: report,
});
export const AgentPipelineCommand = definePipelineCommand(AgentPipeline, {
summarize: (result) => [result],
});Start with a model and a task.
Save this as agent.ts. It gives the model a coding prompt, project instructions from AGENTS.md, conversation history, and six workspace tools.
readeditwritebashlistsearch
Add your own tools and instructions as needed. The core is provider-independent: use the OpenAI adapter shown here, swap in anthropicModel() from tubeless/agent/anthropic, point either adapter at a compatible API with baseUrl, supply another model callback, or write your own decision logic with defineAgentLoop.
import { defineAgent } from "tubeless/agent";
import { openaiModel } from "tubeless/agent/openai";
/** Run from the workspace the agent should inspect and edit; live runs make paid API requests. */
export const CodingAgent = defineAgent({
id: "coding-agent",
name: "Workspace coding agent",
description: "Investigate a task, edit the workspace, and verify the result with a model.",
implementationVersion: "coding-agent-v6",
// Native history stays reusable until 768 KiB; --trace retains model token/cache usage.
model: openaiModel({ reasoningEffort: "high" }),
});Install Tubeless and set OPENAI_API_KEY in your environment. From a disposable workspace, run with Bun 1.3.14+:
npm install tubeless
bunx tubeless run --trace agent.ndjson ./agent.ts -- \
--task "Find and fix the failing test, then verify the change."
bunx tubeless history --trace agent.ndjson This makes paid model calls and uses your machine’s file and shell permissions. Run it in a workspace you are comfortable letting it change.
Runs in your process.
Set limits on turns, calls, nesting, and concurrency. Cancel with an AbortSignal. Record history to NDJSON or SQLite. The runtime has no dependencies, and you do not need a separate service to run an agent.
Inspect which tools were called, what failed, and which subagent did the work. Parent and child runs stay connected in the history.
Opt into durable execution with a checkpoint store, execution key and implementation version. Saved conversations, tool outcomes, child state and budgets survive a restart. Completed calls are reused; interrupted mutations return an uncertain outcome for the agent to inspect. Try the credential-free SQLite recipe ↗
Supply an execution environment to put guidance, files and commands in a remote workspace. Children inherit it. Try the environment recipe ↗ The default workspace uses host permissions; isolation belongs to the environment backend. Read the contracts.