Job inspector agent

warning

This feature is in private preview

job-inspector is an agent definition shipped with the dlthub-platform toolkit. It runs when a job fails, reads the run record, the logs, and the job definition, follows the traceback into the workspace source and a missing input back to the job that produces it, and reports a classification of the failure with evidence and a fix naming the target and the change. It inspects any batch job and doesn't change code or data.

Point its trigger at as much of the workspace as you want watched: one job, every job in a module, every job carrying a tag, or every job in the workspace. You declare the inspector once whichever you pick, and it inspects whatever fails. See Triggers for agents.

You declare it like any other agent job. Background agents covers the mechanics this page builds on.

Install the toolkit

Meet the prerequisites for agent jobs, then install the toolkit:

dlthub ai toolkit install dlthub-platform

Quick start: inspect failed jobs

Declare the job-inspector agent as a job in __deployment__.py and point its trigger at the jobs you want it to watch:

"""GitHub ingest workspace with a failure inspector."""
from dlt.hub import run
from github_pipeline import load_commits

inspector = run.agent(
    "dlthub-platform:job-inspector",
    trigger="job.fail:tag:ingest",
    require={"profile": "access"},
)

__all__ = ["load_commits", "inspector"]

The job is named after the agent definition, job_inspector. require={"profile": "access"} keeps the production credentials out of the job's environment. See Profile of an agent job. Run it locally against a run that already failed, then deploy:

# a single manual run, on a failed run id from `dlthub job runs list`
dlthub local run job_inspector -c failed_run_id=<run-id>

# push the job graph; every failed job tagged "ingest" now starts an inspector run
dlthub deploy

The run log streams to your terminal as the agent works: its reasoning, each tool call, and what each tool returned. When the run ends you get a job result with a status, a Markdown summary, and the inspector's own fields (classification, confidence, evidence, proposed_fix, fix_target, fix_change, open_points, requires_human). On the platform the result appears on the failed run's page, because the agent reported that run as the entity it acted on.

Agent inputs

Input	Meaning
failed_run_id	Run id of the failed job run to inspect
failed_job_ref	Job ref of the failed job. Its latest failed run is inspected when no run id is given

Both are optional, and a run resolves them in order:

1. With a run id, that run is inspected.
2. With a job ref, its latest failed run is inspected.
3. With a job.fail:<job ref> trigger, the latest failed run of that job is inspected.
4. With none of them, the run ends with status: aborted and a summary naming the inputs that were empty.

A run started from a job.fail: trigger arrives with both inputs empty. The trigger string names the failed job, and the agent takes the job ref from {{ run_context.trigger }} in step 3. A run you start manually takes the inputs you give it on the command line or in configuration.

Only job.fail: resolves in step 3. A run started from a job.success: trigger reaches step 4 and ends aborted, because the trigger names a job but no failed run.

Inspect a run that succeeded

Hand the inspector a run id and it reads that run whatever its status, so a green run is inspectable:

dlthub local run job_inspector -c failed_run_id=<run-id>

A green run that loaded nothing gets a description of the anomaly. The inspector reports the zero-row load in summary and leaves fix_target and fix_change empty, because a run that completed carries no error to trace back to a setting. Catch a silent shortfall with a data quality check on the loaded row count, and let that check's failed run be what starts the inspector.

What it reports

Field	Meaning
status	succeeded, failed, or aborted
summary	Markdown, in three sections: Diagnosis, Recommendation, Confidence. See Summary format
failed_run_id	The run it inspected, reported as an entity
failed_job_ref	The job whose run it inspected, reported as an entity
classification	config, credentials, upstream_data, code, resources, transient, or unknown
confidence	high, medium, or low. It's low whenever the classification is unknown
evidence	A source, an excerpt, and a provenance per item. The source carries the line the excerpt sits on
proposed_fix	What a person should do next, naming the target and the change. The agent never applies it
fix_target	The one thing the fix changes: a file path, a config key, a table or resource name, a secret name, or a job ref
fix_change	The exact value or code change to apply to fix_target, such as cursor_path="ordered_at". Empty when unestablished
open_points	What the agent couldn't verify, one entry each: a tool that failed, a file it didn't find, a value it inferred
requires_human	Whether the fix needs a person to act

provenance says what kind of artifact an excerpt is: run_log, run_record, trace, job_definition, workspace_file, secrets_redacted, destination_query, repository_comment, job_description, or inference. The first seven are facts and the last three are claims, so confidence: high rests on at least one fact.

On the platform the result appears on the failed run's page, because the agent reports that run as the entity it acted on. Read the agent run result shows the full result envelope and an inspector result in it.

Summary format

summary holds three headings, each over short bullets:

Heading	What the bullets answer
## Diagnosis	The root cause: what failed, where, and why. One bullet quotes the evidence line carrying it. For a pipeline job the first bullet names the failing step
## Recommendation	The next action, written as the instruction itself and starting with its verb (Set, Change, Unpause), one action per bullet
## Confidence	The limits of the diagnosis: every entry of open_points, and why this confidence

The format is meant to be pasted whole into a coding agent, so the Recommendation names the target and the value rather than asking the reader to investigate.

Defaults and overrides

The definition ships these defaults. The agent job and the individual run override them.

Setting	Default
trigger	job.fail:*, every failed job in the workspace
limits	max_turns: 30, max_tokens: 1000000
loop_run_args	retries: 2, the number of times pydantic-ai lets the model correct a failing tool call

The definition names no model, so the model comes from the job or the workspace. Give it one at least as capable as Claude Sonnet 5.

warning

Narrow the trigger as soon as a second agent job is deployed. job.fail:* matches every batch job in the workspace, agent jobs included. The declaring job is excluded, so the inspector never triggers on its own failures, but two agents both watching job.fail:* do trigger each other: a failed run of A starts B, a failed run of B starts A, and the pair keeps going. A tag or section selector such as job.fail:tag:ingest scopes the inspector to the jobs you want watched. Excluding agent jobs from wide selectors is planned.

Narrow the trigger and change the settings on the job:

inspector = run.agent(
    "dlthub-platform:job-inspector",
    trigger="job.fail:tag:ingest",
    require={"profile": "access"},
    model="sonnet",
    limits={"max_turns": 20},
    instructions="focus on the loader step",
)

Or for a single run:

dlthub local run job_inspector -c failed_run_id=<run-id> -c agent.model=sonnet

Triggers for agents lists the selectors a job.fail: trigger accepts.

Guardrails

• Reads, never writes. The definition grants local: [read] and context: [read]: Read, Glob, and Grep over workspace files, and runs, logs, job definitions, and telemetry through the dltHub MCP server.
• No shell, by design. The credential deny rules cover the file tools only, so execute would be a way around them and a way to rerun the job under inspection.
• No destination access. The definition declares no data axis, so the agent can't query your data. A diagnosis is built from run records, logs, job definitions, the dlt trace, and workspace source. When the cause turns on what a table holds, the agent puts that in open_points and names the query that would settle it.
• No changes to your workspace. The body rules it read-only on top of the grants: it doesn't edit code, deploy, cancel, or rerun a job. A person applies the proposed fix.
• Read-only credentials. The job runs on the access profile, which an agent job takes by default, so the production credentials stay out of its environment. Pin require={"profile": "access"} to state it in the code. See Profile of an agent job.

Next steps

• Background agents covers declaring, running, and deploying agent jobs
• Toolkits shows the rest of the dlthub-platform toolkit
• Triggers and scheduling covers the triggers available to all jobs
• Monitoring and debugging shows how to list runs and read their results