Agent Architecture

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 Type	Description	Example
`on_success`	Execute when node completes successfully	LLM response received
`on_failure`	Execute when node fails	API error, timeout
`conditional`	Execute based on output conditions	`when: "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
  }
}

Overview

Core Concepts

Agent Graph Overview

Node Types

LLM Node

Router Node

Function Node

Human-in-the-Loop Node

Edge Types

SDK-Wrapped Nodes

Shared Memory

LLM Access

Tool Registry

Observability

Node Context

Agent Specification

Next Steps

Build Your First Agent

Node Reference

Overview

Core Concepts

​Agent Graph Overview

​Node Types

​LLM Node

​Router Node

​Function Node

​Human-in-the-Loop Node

​Edge Types

​SDK-Wrapped Nodes

Shared Memory

LLM Access

Tool Registry

Observability

​Node Context

​Agent Specification

​Next Steps

Build Your First Agent

Node Reference

Agent Graph Overview

Node Types

LLM Node

Router Node

Function Node

Human-in-the-Loop Node

Edge Types

SDK-Wrapped Nodes

Node Context

Agent Specification

Next Steps