Skip to main content

​
Agent Graph Overview

Every Aden agent is represented as a directed graph consisting of:
  • Nodes - Individual processing units (LLM calls, routers, functions, human intervention)
  • Edges - Connections between nodes that define flow (success, failure, conditional)
  • Context - Shared state passed between nodes (memory, tools, LLM access)

​
Node Types

​
LLM Node

Executes a language model call with a prompt template and context. 
{
  "type": "llm",
  "name": "analyze_request",
  "model": "claude-sonnet-4-5-20250929",
  "prompt": "Analyze this customer request: {{input}}",
  "output_schema": {...}
}
Capabilities:
  • Structured output via JSON schema
  • Tool/function calling
  • Streaming responses
  • Automatic retry with backoff

​
Router Node

Routes execution to different paths based on conditions or LLM decisions. 
{
  "type": "router",
  "name": "urgency_router",
  "conditions": [
    {"path": "urgent_handler", "when": "urgency == 'high'"},
    {"path": "standard_handler", "when": "urgency == 'low'"},
    {"path": "review_handler", "default": true}
  ]
}
Routing Strategies:
  • Conditional - Based on output values
  • LLM-decided - Let the model choose the path
  • Weighted - Probabilistic routing for A/B testing

​
Function Node

Executes custom Python code for business logic, API calls, or data transformation. 
{
  "type": "function",
  "name": "send_email",
  "handler": "tools.send_email",
  "inputs": ["recipient", "subject", "body"]
}

​
Human-in-the-Loop Node

Pauses execution for human input with configurable timeouts and escalation. 
{
  "type": "human",
  "name": "manager_approval",
  "prompt": "Approve refund of ${{amount}}?",
  "timeout": "24h",
  "escalation": "auto_reject"
}
See Human-in-the-Loop for details.

​
Edge Types

Edges connect nodes and define the execution flow:
Edge TypeDescriptionExample
on_successExecute when node completes successfullyLLM response received
on_failureExecute when node failsAPI error, timeout
conditionalExecute based on output conditionswhen: "score > 0.8"
{
  "edges": [
    {"from": "analyze", "to": "approve", "type": "on_success"},
    {"from": "analyze", "to": "retry", "type": "on_failure"},
    {"from": "router", "to": "path_a", "when": "category == 'A'"},
    {"from": "router", "to": "path_b", "when": "category == 'B'"}
  ]
}

​
SDK-Wrapped Nodes

Every node in Aden is wrapped with the SDK, providing:

Shared Memory

Access to global and local memory stores

LLM Access

Built-in access to configured LLM providers

Tool Registry

Access to MCP tools and custom functions

Observability

Automatic logging, tracing, and cost tracking

​
Node Context

Each node receives a context object with: 
class NodeContext:
    memory: MemoryStore      # Shared memory across nodes
    llm: LLMClient           # Configured LLM client
    tools: ToolRegistry      # Available tools
    input: dict              # Input from previous node
    metadata: dict           # Run metadata (trace_id, etc.)

​
Agent Specification

Agents are defined in a JSON specification (agent.json): 
{
  "name": "support-agent",
  "version": "1.0.0",
  "goal": "Handle customer support tickets efficiently",
  "nodes": [...],
  "edges": [...],
  "config": {
    "default_model": "claude-sonnet-4-5-20250929",
    "timeout": "5m",
    "max_retries": 3
  }
}

​
Next Steps

Agent Graph

Dive into graph execution, routing patterns, and shared memory behavior

Worker Agent

Understand sessions, iterations, and headless runtime operations

Build Your First Agent

Create an agent from scratch

Node Reference

Detailed node configuration options