orka.nodes.graph_scout_agent module

🧭 GraphScout Agent - Intelligent Path Discovery and Selection

The GraphScoutAgent is an intelligent routing agent that automatically inspects the workflow graph, evaluates possible paths, and selects the optimal next steps based on the current question and context.

Core Capabilities: - Graph Introspection: Automatically discovers available paths from current position - Smart Path Evaluation: Uses LLM evaluation combined with heuristics for scoring - Dry-Run Simulation: Safely previews path outcomes without side effects - Budget-Aware Decisions: Considers cost and latency constraints - Safety Guardrails: Enforces safety policies and risk assessment

Key Features: - Modular architecture with pluggable components - Global graph visibility with local planning horizon - Intelligent scoring with multiple evaluation criteria - Comprehensive trace logging for debugging - Fallback strategies for edge cases

Use Cases: - Dynamic routing in complex workflows - Multi-path decision points - Conditional branching based on content analysis - Intelligent fallback selection - Cost-optimized path selection

class orka.nodes.graph_scout_agent.GraphScoutConfig(k_beam: int = 3, max_depth: int = 2, commit_margin: float = 0.15, score_weights: Dict[str, float] | None = None, cost_budget_tokens: int = 800, latency_budget_ms: int = 1200, safety_profile: str = 'default', safety_threshold: float = 0.2, max_preview_tokens: int = 192, tool_policy: str = 'mock_all', use_priors: bool = True, ttl_days: int = 21, log_previews: str = 'head64', log_components: bool = True)

Bases: object

Configuration for GraphScout agent behavior.

k_beam: int = 3

max_depth: int = 2

commit_margin: float = 0.15

score_weights: Dict[str, float] | None = None

cost_budget_tokens: int = 800

latency_budget_ms: int = 1200

safety_profile: str = 'default'

safety_threshold: float = 0.2

max_preview_tokens: int = 192

tool_policy: str = 'mock_all'

use_priors: bool = True

ttl_days: int = 21

log_previews: str = 'head64'

log_components: bool = True

__post_init__() → None

Set default score weights if not provided.

class orka.nodes.graph_scout_agent.PathCandidate(node_id: str, path: List[str], score: float, components: Dict[str, float], preview: str, rationale: str, expected_cost: float, expected_latency: float, safety_score: float, confidence: float)

Bases: object

Represents a candidate path for evaluation.

node_id: str

path: List[str]

score: float

components: Dict[str, float]

preview: str

rationale: str

expected_cost: float

expected_latency: float

safety_score: float

confidence: float

class orka.nodes.graph_scout_agent.ScoutDecision(decision_type: str, target: Any, confidence: float, trace: Dict[str, Any], reasoning: str)

Bases: object

Represents the final decision made by GraphScout.

decision_type: str

target: Any

confidence: float

trace: Dict[str, Any]

reasoning: str

class orka.nodes.graph_scout_agent.GraphScoutAgent(node_id: str, **kwargs: Any)

Bases: BaseNode

🧭 Intelligent Path Discovery Agent

The GraphScoutAgent automatically inspects the workflow graph and selects the optimal next path based on the current question and context.

Architecture: - Modular Design: Pluggable components for each responsibility - Graph Introspection: Discovers available paths from current position - Multi-Criteria Scoring: LLM evaluation + heuristics + priors + budget - Safety-First: Comprehensive safety checks and guardrails - Trace-Enabled: Full observability for debugging and optimization

Configuration Example:

- id: graph_scout_0
  type: graph-scout
  params:
    k_beam: 3
    max_depth: 2
    commit_margin: 0.15
    score_weights:
      llm: 0.45
      heuristics: 0.20
      prior: 0.20
      cost: 0.10
      latency: 0.05
    safety_profile: default
    cost_budget_tokens: 800
    latency_budget_ms: 1200
  prompt: |
    You are GraphScout. Analyze the question and available paths.
    Select the best next step based on relevance, safety, and efficiency.
    Return your decision as JSON only.

Decision Types: - commit_next: Single next node with high confidence - commit_path: Multi-step path when evidence is strong - shortlist: Multiple options when margin is thin

__init__(node_id: str, **kwargs: Any) → None

Initialize GraphScout with modular components.

async initialize() → None

Initialize all modular components.

async run(context: Dict[str, Any]) → Dict[str, Any]

Main execution method for GraphScout agent.

Parameters:

context – Execution context containing input, previous_outputs, orchestrator

Returns:

Decision result with selected path and trace information