Derived Agents

Derived agents compute reusable results from values that other agents have already resolved.

On this page

When to use a derived agent

Use an extraction agent when the answer is written in the documents. Use a derived agent when the answer must be calculated, compared, scored, classified, or combined from existing agent results.

Examples include:

  • Variance between Actual Revenue and Forecast Revenue.
  • A ratio calculated from two financial metrics.
  • A flag when Premium exceeds Policy Limit.
  • A risk rating based on several extracted indicators.
  • A reconciliation result comparing values from separate sources.

For a calculation needed only once, ask Navi to calculate it in chat. Create a derived agent when the value should remain in Results and recompute when its inputs change.

Create one manually

On the Agents page:

  1. Select Create, then Manually.
  2. Open Advanced and choose Derived Agent.
  3. Enter a name, value type, and optional unit.
  4. Write the Derived Task describing the calculation and required output shape.
  5. Type @ or select Reference agent to insert each input agent.
  6. Add dimensions if the calculation should run once per row.
  7. Save and launch the agent.

Referenced agents appear as editable pills in the prompt. A derived agent must have at least one reference.

Create one with Navi

Describe the persistent metric you need, for example:

Create a reusable revenue variance agent from @Actual Revenue and @Forecast Revenue. Return a number in USD.

Navi can propose missing extraction agents and the derived agent that uses them in one set of changes. Review all references and dimensions before selecting Create & Launch.

Navi can edit the task and references of an existing derived agent. It does not convert an existing extraction agent to derived, or a derived agent to extraction; ask it to create a new agent instead.

How dependencies run

References define a dependency graph:

  1. Referenced extraction or derived agents run first.
  2. Their resolved values are supplied to the dependent derived agent.
  3. The derived agent emits one value for each combination of its own dimensions, or one project-wide value when it has no dimensions.

The reference list creates the dependency. Merely typing an agent’s name as ordinary prompt text does not.

Parsewise rejects circular references. Derived agents can depend on other derived agents as long as the graph remains acyclic.

Dimensions and lineage

Dimensions work the same way as on extraction agents. Reuse the dimensions on source agents when the computed value should align with their rows.

For example, if both revenue agents use Company and Year, give the variance agent the same dimensions. It can then calculate one variance per company and year.

Derived results retain references to the upstream values used in the calculation. Open the result to inspect its reasoning and follow the sources back to the underlying documents.

Reruns and destructive changes

When a referenced agent’s results change, dependent derived agents become pending and run after their inputs are ready. Previous derived results may remain visible while the new dependency chain is running.

A derived agent can be skipped when none of its referenced results changed.

Changing an upstream task, value type, dimensions, or other destructive settings can clear its extractions and trigger downstream recomputation. Changing a shared dimension can affect every extraction and derived agent that uses it. Review the full impact shown in the save confirmation.

The manual agent editor and programmatic interfaces can change an agent’s kind when all fields required by the new kind are supplied. This is a destructive operation; creating a new agent is safer when the old results should remain available.

API and MCP fields

Programmatic agent creation uses:

  • agent_type: "derived"
  • derived_prompt for the calculation and output instructions
  • derived_agent_references for the dependency list

References can identify agents by exact name or ID. MCP users can read the parsewise://guides/agent-design resource for the complete workflow. For HTTP request and response shapes, see the generated Agents API reference.