Documentation Index

Fetch the complete documentation index at: https://docs.ursahealth.com/llms.txt

Use this file to discover all available pages before exploring further.

Dependencies

  • Updated on Aug 11, 2026
  • Published on Mar 6, 2026
  • 5 minute(s) read
Prev Next

Sessions within a diagnostic can declare dependencies on other sessions in the same diagnostic. Dependencies enable multi-stage investigation workflows where downstream sessions build on the findings of upstream sessions.

Types of Dependencies

There are two types of dependencies:

  • Unconditional — The downstream session waits until the upstream session has completed (produced at least one finding).
  • Conditional — The downstream session waits until the upstream session's disposition meets a condition on an enumerated or numeric field.

When a session has dependencies, the system checks whether they are satisfied before allowing the session to start. If all dependencies are satisfied, the upstream sessions' findings and dispositions are discoverable by downstream sessions.

Unconditional Dependencies

An unconditional dependency means "wait until this session is done." A session counts as complete once it produces its first finding via the PROMOTE_FINDING tool, or once it has set a disposition.

Use unconditional dependencies when the downstream session just needs the upstream session to have finished its investigation, regardless of what it found.

Conditional Dependencies

A conditional dependency means "wait until this session's disposition meets a condition on a specific field." Conditional dependencies support two field types:

  • Enumerated fields (pipe-separated values like HIGH|MEDIUM|LOW) — The condition checks for exact equality, e.g. risk_level = HIGH.
  • Numeric fields (Number type) — The condition uses a comparison operator (=, !=, <, <=, >, >=) and a threshold, e.g. score >= 50.

Conditional dependencies require that:

  • The upstream session has a disposition schema with at least one enumerated list or numeric field. Freeform string fields are not supported for conditional dependencies.
  • The condition specifies exactly one key-value pair from the schema's eligible fields.

Use conditional dependencies to create branching workflows — for example, only running a deep-dive investigation when an initial triage session classifies risk as HIGH, or when a scoring session produces a value above a threshold.

Adding Dependencies

Dependencies can be added in two places:

  1. When creating a new session — A "Dependencies" editor appears on the new session form, if the diagnostic has other sessions to depend on.

  2. When editing an existing session — The session edit panel on the diagnostic detail page includes the same editor.

Dependency Satisfaction

Dependencies are checked when a session starts — an unsatisfied dependency prevents the session from starting and shows an error — and are displayed on each session card on the diagnostic detail page, as tags below the session name naming what it depends on.

Once a downstream session has started (has a conversation log), dependencies are not re-validated. This means that if an upstream session's disposition changes after the downstream session has already started, the downstream session is not affected.

Blocked Sessions

When you navigate to a session that has unsatisfied dependencies, the session workspace shows a blocked state instead of the starting request form. The blocked state displays:

  • A "Dependencies Not Satisfied" heading.
  • A list of specific issues explaining why each dependency is not met:
    • "Session Name" has not completed yet — for unconditional dependencies where the upstream session hasn't promoted a finding.
    • "Session Name" disposition key is not "value" — for enum conditional dependencies where the upstream session's disposition doesn't match.
    • "Session Name" disposition does not satisfy key >= value — for numeric conditional dependencies where the upstream session's disposition doesn't meet the threshold.
    • Upstream session has been deleted — when a depended-on session has been deleted.
    • Schema key "key" no longer exists on "Session Name" — when the upstream session's disposition schema has been edited and no longer contains the expected field.

Revisit the session after the upstream sessions have completed or been resolved.

Upstream Context Injection

When a session with satisfied dependencies starts, the system automatically queries the upstream sessions' findings and injects a summary into the AI's prompt. The summary includes, for each upstream session:

  • The upstream session's name.
  • The upstream session's disposition (if set).
  • A list of each finding's title and UUID.

The AI can then use the GET_UPSTREAM_FINDINGS tool to retrieve the full details (description, SQL query, and data) of any finding by UUID. This tool accepts one or more finding UUIDs separated by commas:

GET_UPSTREAM_FINDINGS <finding_uuid>
GET_UPSTREAM_FINDINGS <uuid1>,<uuid2>,<uuid3>

This tool is automatically available in any session that has dependencies — it does not need to be enabled at the diagnostic definition level. It is scoped to findings from the session's upstream dependencies and cannot access findings from unrelated sessions.

The AI can also use the COPY_UPSTREAM_FINDING tool to bring an upstream finding directly into the current session without re-querying the database. This copies the finding's SQL, results, chart configuration, and display type exactly as they were in the upstream session. The AI may optionally override the title and/or description:

COPY_UPSTREAM_FINDING --uuid <upstream_finding_uuid>
COPY_UPSTREAM_FINDING --uuid <upstream_finding_uuid> --title "New title" --description "New description"

This is useful for synthesis sessions that curate findings from multiple upstream investigations — the AI can surface upstream results instantly without the latency and redundancy of re-executing queries.

This approach keeps the initial prompt concise while still giving the AI full access to upstream findings on demand.

Warnings and Deleted Sessions

The diagnostic detail page displays warnings for structural dependency issues:

  • Deleted upstream session — If an upstream session that other sessions depend on is deleted, a yellow warning appears on the dependent sessions.
  • Schema changed — If an upstream session's disposition schema is edited to remove a field that a conditional dependency references, a warning appears on the dependent sessions.

These warnings indicate that the dependency configuration may need to be updated. The dependent session will be blocked from starting until the issue is resolved (by editing the dependency or restoring/recreating the upstream session).

When deleting a session that other sessions depend on, the confirmation dialog warns you about the dependent sessions and shows how many would be affected.

Example Workflow

Scenario: A team is investigating pharmacy cost anomalies. They want an initial triage session to classify risk, and then a deep-dive session that only runs for high-risk anomalies.

Session A ("Triage") is given a disposition schema with risk_level as a custom list of LOW|MEDIUM|HIGH. It runs, finds a significant anomaly, promotes findings showing the evidence, and — with the team's agreement — sets risk_level: HIGH.

Session B ("Deep Dive") carries a conditional dependency on Session A of risk_level = HIGH, so it can start immediately. It receives a summary of Session A's findings and can call GET_UPSTREAM_FINDINGS for the full details of any of them.

Session C ("Low Risk Review") carries the opposite condition, risk_level = LOW, so it shows a blocked state instead. That is the branch working as intended: only one of B and C proceeds, decided by what the triage actually concluded.

A numeric condition behaves the same way. A "Scoring" session with confidence: Number in its schema can gate a downstream "Action" session on confidence >= 80 — satisfied at confidence: 92, and blocked at confidence: 65 with "does not satisfy confidence >= 80".