deepAgent

Orchestrates a hierarchical multi-agent workflow. It takes a subgraph of connected subagent, tool, agentInput, and agentOutput nodes — compiled at runtime by DeepAgentCompiler — and executes the resulting agent. The main agent can invoke subagents via a task() tool call.

Cost tracking middleware wraps every LLM call and records per-call token and cost data. Execution runs in streaming mode (astream_events) or non-streaming mode (ainvoke).

Parameters

Param	Type	Required	Description
model	string	Yes	Model identifier for the main agent (e.g. gpt-4o-mini)
system_prompt	string	Yes	System prompt for the main agent
messages	object[]	Yes	Conversation messages, each with role and content keys
response_format	object?	No (default: null)	JSON schema for structured output. When provided, the agent returns a structured_response key
streaming	boolean	No (default: true)	When true, executes via astream_events and tracks call counts

Output

All fields returned by the compiled agent, plus a metadata field:

Field	Type	Description
metadata	object	Execution metadata (see below)
(any agent fields)	any	All fields returned by the compiled agent

metadata object:

Field	Type	Description
total_cost	float	Total API cost in USD
execution_time_seconds	float	Wall-clock time
tool_calls_made	integer	Number of tool calls made
subagent_calls_made	integer	Number of subagent calls made
total_input_tokens	integer	Total input tokens consumed
total_output_tokens	integer	Total output tokens produced
llm_calls	object[]	Per-call breakdown with model, provider, context, tokens, and cost

Example

{
  "id": "deepAgentNode",
  "type": "deepAgent",
  "data": {
    "label": "Deep Agent",
    "isExecuted": false,
    "handles": ["inputs", "outputs"],
    "schema": {},
    "params": {
      "model": { "value": "{{ @agentInput.model }}", "isExpression": true, "isAttachedToInputNode": false },
      "system_prompt": { "value": "{{ @agentInput.system_prompt }}", "isExpression": true, "isAttachedToInputNode": false },
      "messages": { "value": "{{ @agentInput.messages }}", "isExpression": true, "isAttachedToInputNode": false },
      "streaming": { "value": true, "isExpression": false, "isAttachedToInputNode": false }
    },
    "inputs": [], "outputs": [], "errors": []
  },
  "position": { "x": 300, "y": 0 },
  "isSelected": false,
  "isDragging": false
}

Subagents are connected to deepAgent via agent edges. Tools are connected via tool edges. These edges do not affect execution order — they are used by DeepAgentCompiler to wire the agent hierarchy.