# 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.

Each model turn can choose a new batch of registered tools or finish. [Watch an illustrated run](https://tubeless.io/agent-harness) to see tool calls branch, a subagent run its own pipeline, and results feed the next model turn.

## 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.

- Use fromPipeline to run an agent inside a workflow and consume its answer: [composition example](https://github.com/chetmancini/tubeless/blob/main/examples/agent-pipeline.ts).
- Use pipelineTool to give an agent a capability you have already built: [delegation example](https://github.com/chetmancini/tubeless/blob/main/examples/agent-delegation.ts).
- Add your own tool handlers with defineTool: [custom tool example](https://github.com/chetmancini/tubeless/blob/main/examples/agent-workspace.ts).

## Start with a model and a task

Save this as agent.ts:

```ts
import { defineModelAgent } 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 = defineModelAgent({
  id: "coding-agent",
  name: "Workspace coding agent",
  description: "Investigate a task, edit the workspace, and verify the result with a model.",
  implementationVersion: "coding-agent-v5",
  model: openaiModel({ reasoningEffort: "high" }),
});
```

It gives the model a coding prompt, project instructions from AGENTS.md, conversation history, and six workspace tools: read, edit, write, bash, list, and search.

Add your own tools and instructions as needed. The core is provider-independent: use the OpenAI adapter shown here, supply another model callback, or write your own decision logic with defineAgent.

Install tubeless, set OPENAI_API_KEY in your environment, then run from a disposable workspace with Bun 1.3.14+:

```sh
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.

Execution is in process; crash-safe resume is not supported yet. Workspace tools use host permissions and are not sandboxed.

- [Agent documentation](https://tubeless.io/docs/agents.md)
- [Examples and recorded runs](https://tubeless.io/agent-examples.md)