Dependency Graph Construction Prompt for Agent Workflows

This prompt is for platform engineers and AI infrastructure teams orchestrating complex agent workflows where multiple tools must be invoked, and the order of execution is non-trivial. The core job-to-be-done is to transform a user objective, a set of available tool definitions, and known data dependencies into a machine-readable, directed acyclic graph (DAG) of tool calls. Use this prompt when you need an explicit execution plan that defines dependency edges, a topological ordering, and groups of calls that can safely run in parallel. The ideal user is someone building an agent harness or execution engine who needs a reliable planning step before any tool is invoked, not someone building a simple, single-step chatbot.

This prompt is a planning-only step. It does not execute tools, manage runtime state, handle errors from tool calls, or make decisions based on the results of a tool's execution. It assumes you have already defined your tool schemas, including their input and output signatures, and can provide them as structured input. You should not use this prompt when the execution order is already statically known, when there is only a single tool call, or when the dependencies are so simple that a topological sort is over-engineering. It is also inappropriate for workflows where the next tool depends on the dynamic content of a previous tool's output, rather than just its schema-defined fields; in that case, a sequential chaining prompt with intermediate results is a better fit.

Before using this prompt, ensure you have a clear, structured representation of each tool: its name, a description of its function, its required and optional input parameters with types, and its output schema. The prompt's effectiveness depends on the quality of these tool definitions. After generating the DAG, you must validate it programmatically: check for cycles, confirm that all declared input dependencies are produced by a preceding tool, and verify that parallel execution groups do not contain conflicting write operations on shared resources. For high-risk workflows, such as those mutating production infrastructure or financial data, the generated plan should be treated as a draft and reviewed by a human operator before execution. The next step is to feed this validated DAG into your execution engine, which will handle invocation, retries, and error propagation according to the plan's constraints.

This prompt template is designed to be dropped into an agent orchestration layer. It instructs the model to analyze a set of available tool signatures and a user's high-level objective, then output a structured execution plan. The plan is not just a list of calls; it's a dependency graph that your executor can use to maximize parallelism while respecting data flow. The output includes explicit depends_on edges, a valid topological sort, and labeled parallel execution groups, which are essential for preventing race conditions and ensuring that downstream tools receive the correct, fully-resolved inputs from their upstream dependencies.

textCopy
You are an agent execution planner. Your task is to construct a dependency graph for a set of tool calls required to fulfill a user objective.

## Available Tools
[TOOLS]

## User Objective
[OBJECTIVE]

## Constraints
- Identify all tool calls needed to achieve the objective.
- For each tool call, specify its required arguments. Use the output of a previous call as an argument by referencing its `call_id`.
- Declare explicit dependencies using a `depends_on` field containing a list of `call_id`s. A call can only depend on calls that produce its required inputs.
- The final graph must be a directed acyclic graph (DAG). Cyclic dependencies are invalid.
- Group calls into parallel execution groups. Calls within the same group have no dependencies on each other and can run concurrently.
- Calls in later groups depend on at least one call from a prior group.
- If the objective cannot be fulfilled with the available tools, output an empty plan with a `feasibility` field set to `false` and a `reason`.
- If the objective is ambiguous, output a `clarification_needed` field with specific questions before constructing a plan.

## Output Schema
Respond with a single JSON object conforming to this structure:
{
  "plan": {
    "feasibility": boolean,
    "clarification_needed": ["string"],
    "execution_groups": [
      {
        "group_id": "string",
        "calls": [
          {
            "call_id": "string",
            "tool_name": "string",
            "arguments": {},
            "depends_on": ["call_id"],
            "reasoning": "string"
          }
        ]
      }
    ]
  }
}

## Validation Rules (Self-Check Before Output)
1.  Every `call_id` in a `depends_on` list must exist in a prior execution group.
2.  No cycles: trace all `depends_on` paths; no call can ultimately depend on itself.
3.  All required arguments for a tool must be provided, either as static values or as a reference to a prior call's output.
4.  Parallel groups must be maximized: if two calls have no direct or transitive dependency, they should be in the same group.

## Examples
[EXAMPLES]

## Risk Level
[RISK_LEVEL]

To adapt this template, start by populating the [TOOLS] placeholder with a JSON array of your tool schemas, including names, descriptions, and parameter types. The [OBJECTIVE] is the user's natural language request. The [EXAMPLES] section is critical for teaching the model the expected output format and edge-case handling; include at least one example of a simple linear chain, one of a complex fork-join, and one where the objective is infeasible. The [RISK_LEVEL] placeholder should be set to "high", "medium", or "low" to adjust the model's caution. For high-risk workflows (e.g., database writes, financial transactions), the prompt should be followed by a strict validation layer in your application code that checks for cycles and missing dependencies before any tool is executed.

The dependency graph prompt is not a standalone artifact—it is a planning step inside a larger agent execution loop. The typical integration pattern places this prompt after the agent has identified a set of candidate tool calls but before any tool executes. The prompt receives the proposed tool calls with their declared input requirements and output signatures, and it returns a directed acyclic graph (DAG) with topological ordering and parallel execution groups. The orchestration engine then consumes this DAG to schedule execution, respecting the dependency edges and parallelism constraints the prompt produces.

Validation is mandatory before execution. The output DAG must pass structural checks before any tool runs: (1) cycle detection—if the graph contains a cycle, reject the plan and re-prompt with the cycle explicitly called out; (2) missing dependency resolution—every input referenced by a tool must appear as an output of a preceding tool or be available from the initial context; (3) staleness propagation—if tool C depends on tool B's output, and tool B is in a parallel group with tool A that also writes to the same resource, flag the read-after-write hazard. Implement these checks as deterministic code in the harness, not as additional LLM calls. A failed validation should trigger a structured error payload back to the prompt with the specific violation, requesting a corrected graph. Limit re-prompt attempts to a configurable retry budget (typically 2–3) before escalating to a human operator or falling back to a safe sequential execution mode.

Model choice and tool integration. This prompt benefits from models with strong reasoning capabilities and structured output support. Use a model that supports JSON mode or function calling to enforce the DAG schema directly, reducing post-hoc parsing errors. The prompt's [TOOLS] placeholder should be populated from your tool registry's canonical schemas—never hand-write tool descriptions for this prompt; use the same schemas the model will see at execution time to avoid signature mismatches. Wire the prompt output into your execution engine's scheduler: parallel groups map to concurrent execution with a Promise.all or equivalent fan-out, while sequential edges map to await chains. Instrument each tool call with the DAG's node ID so trace logs can reconstruct whether a failure was a planning error (wrong dependency edge) or an execution error (tool returned unexpected shape). For high-stakes workflows, insert a human approval gate after graph generation but before execution, displaying the planned DAG as a visual or tabular summary for operator review.