Overview
Orchestration lets you run AI workflows in the Poolside Console, from a single agent session to multi-step pipelines that combine agent reasoning with deterministic logic. You choose what to run and how to trigger it:- What to run: An agent session for self-contained work, or a code-defined pipeline for structured, multi-step workflows.
- How to trigger it: Manually from the Poolside Console, on a cron schedule, or automatically from external events through webhooks.
Workflows and triggers
Orchestration has two layers: what to run and when to run it.What to run
| Workflow type | What it is | When to use it |
|---|---|---|
| Agent session | Runs a managed agent in an isolated sandbox with a prompt you provide. No code required. Set up entirely in the Poolside Console as a task. | Self-contained work that one agent can handle in a single session: daily summaries, periodic scans, initial triage, or ad-hoc investigations. |
| Pipeline | A code-defined workflow with one or more steps arranged as a directed acyclic graph (DAG). Steps can be agent steps or programmatic steps. Defined in Python with the Bridge SDK, version-controlled in Git. | Structured, multi-step work that needs typed data flow between steps, per-step isolation, evaluations, reproducibility, or an audit trail. Code review, incident investigation, data processing, or any workflow where you need to combine agent reasoning with validation and business logic. |
When to run it
| Trigger | What it does |
|---|---|
| Manual | Start a workflow on demand from the Poolside Console. |
| Schedule | Start a workflow on a recurring cron interval. |
| Webhook | Start a workflow in response to an external event from providers such as GitHub, Linear, PagerDuty, Slack, or any system that can send a signed HTTP POST. |
Core concepts
Workflows
| Concept | What it is |
|---|---|
| Managed agent | A reusable agent configuration that bundles a model, instructions, tools, MCP servers, repositories, skills, credentials, and sandbox settings. Used by both tasks and pipeline agent steps. See Managed agents. |
| Task | A reusable automation definition configured in the Poolside Console. Pairs a managed agent with a sandbox and a prompt, independent of when to run it. |
| Pipeline | A versioned set of steps arranged as a directed acyclic graph, defined in Python with the Bridge SDK and backed by a Git commit. |
| Step | One node in a pipeline graph. A step is either an agent step (starts a managed agent session for reasoning) or a programmatic step (runs deterministic code). Steps declare typed inputs and outputs. |
| Dependency | A link between steps declared through type annotations. When step B depends on the output of step A, orchestration runs A first and passes its output to B automatically. |
Execution
| Concept | What it is |
|---|---|
| Build | One execution request that runs one or more selected steps from a pipeline. |
| Step run | The execution record for a single step within a build. Includes the step result, evaluation results, and links to agent sessions. |
| Evaluation | A quality-measurement function bound to a step. Evaluations run automatically after the step completes and produce metrics you can review in the Poolside Console. |
| Sandbox definition | The compute environment for a step or task, including the container image, CPU, memory, and storage limits. See Sandboxes. |
| Credential | A secret value stored in the Poolside Console and injected into the execution environment as an environment variable at runtime. See Credentials. |
Triggers
| Concept | What it is |
|---|---|
| Schedule | A cron-based trigger that starts one or more tasks at defined intervals. |
| Webhook endpoint | An HTTPS endpoint that receives events from external providers and routes matching events to pipeline builds through webhook actions. |
Infrastructure
| Concept | What it is |
|---|---|
| Repository | A Git repository connected to the Poolside Console that orchestration can index. See Repositories. |
| Indexed branch or commit | A branch or exact commit hash that Poolside has indexed. Pipelines appear in the Poolside Console after indexing succeeds. |
Get started
| Goal | Where to start |
|---|---|
| Run an agent session on a schedule | Create a task and attach it to a schedule. No code required. |
| Define a structured, multi-step pipeline | Bridge SDK. Define steps in Python, push to Git. |
| Run a pipeline from the Poolside Console | Pipelines. Select steps, provide inputs, execute. |
| Trigger workflows from external events | Set up a webhook endpoint and define webhook actions in code. |