debug_pipeline
Set breakpoints, resume snapshots, or trace full runs to debug pipeline configurations. Dry-run enables side-effect-free testing.
Instructions
Runs a pipeline configuration in debug mode: pin a breakpoint, resume a snapshot, or trace a full run.
Debugs a pipeline configuration directly (not a saved pipeline by name) -- pass the YAML you want to test, e.g. from get_pipeline_version, create_pipeline_version, or a local draft. The inline run trace is always returned, so a failure is visible even for a run that never reaches a breakpoint.
One call carries at most one of:
break_at_component_name (with break_at_visit_count) -- run from inputs until the breakpoint is hit, then stop and return a resumable snapshot in the 'snapshot' field. Pass that back as resume_from to continue the run.
resume_from -- replay a snapshot returned by a previous debug run to completion; inputs are ignored, they come from the snapshot.
neither -- run the pipeline from inputs to completion as a plain debug run. :param yaml_configuration: The pipeline YAML configuration to debug. :param inputs: Named pipeline inputs keyed by the input name declared under the pipeline config's 'inputs' mapping (e.g. {"query": "What is love?"}). Ignored when resume_from is set. :param break_at_component_name: Name of the component to break at. Mutually exclusive with resume_from; omit both to run to completion as a plain debug run. :param break_at_visit_count: Break when the target has been visited this many times (0 breaks before the first visit; relevant for loops/cycles). Only used if break_at_component_name is set. :param resume_from: A snapshot returned by a previous debug run (its 'snapshot' field), replayed to completion. Mutually exclusive with break_at_component_name. :param files: File IDs to download and inject into the inputs declared under the pipeline config's 'inputs.files' mapping. :param pipeline_id: Optional ID of the pipeline this debug run is associated with. :param pipeline_version_id: Optional ID of the pipeline version to associate the run with (requires pipeline_id). :param dry_run: Best-effort stateless run: state-modifying components (e.g. DocumentWriter) are replaced with no-op equivalents so the pipeline can be inspected without side effects. Required for indexing pipelines (their document store carries no index until deploy time); harmless for query pipelines. Set it on resume too if the original run used dry_run, otherwise the run is rejected.
:returns: PipelineDebugResult with status, result/snapshot, and the run trace, or an error message.
All parameters accept object references in the form @obj_id or @obj_id.path.to.value.
Examples::
# Direct call with values
debug_pipeline(data={'key': 'value'}, threshold=10)
# Call with references
debug_pipeline(data='@obj_123', threshold='@obj_456.config.threshold')
# Mixed call
debug_pipeline(data='@obj_123.items', threshold=10)The output is automatically stored and can be referenced in other functions.
Returns a formatted preview with an object ID (e.g., @obj_123).
Use the object store tools in combination with the object ID to view nested properties of the object.
Use the returned object ID to pass this result to other functions.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| files | No | ||
| inputs | No | ||
| dry_run | No | ||
| pipeline_id | No | ||
| resume_from | No | ||
| yaml_configuration | Yes | ||
| pipeline_version_id | No | ||
| break_at_visit_count | No | ||
| break_at_component_name | No |