<?php

declare(strict_types=1);

namespace Drupal\flowdrop_runtime\Service\Orchestrator;

use Drupal\flowdrop_runtime\DTO\Compiler\DependencyGraph;
use Drupal\flowdrop_runtime\DTO\Runtime\NodeExecutionContext;
use Drupal\flowdrop_workflow\DTO\WorkflowDTO;

/**
 * Interface for agent node executors.
 *
 * Implementations handle the execution of agent nodes, which perform
 * agentic workflows with iterative tool use and LLM reasoning.
 *
 * @internal This interface is not part of the public API and may change without notice.
 */
interface AgentExecutorInterface {

  /**
   * Executes an agent node.
   *
   * @param string $executionId
   *   The execution ID.
   * @param string $nodeId
   *   The agent node ID.
   * @param array<string, mixed> $inputData
   *   The input data for the agent.
   * @param array<string, mixed> $config
   *   The agent configuration.
   * @param \Drupal\flowdrop_workflow\DTO\WorkflowDTO $workflow
   *   The workflow DTO.
   * @param string $pipelineId
   *   The parent pipeline ID.
   * @param \Drupal\flowdrop_runtime\DTO\Compiler\DependencyGraph $dependencyGraph
   *   The dependency graph for tool discovery and data resolution.
   * @param \Drupal\flowdrop_runtime\DTO\Runtime\NodeExecutionContext $context
   *   The execution context.
   *
   * @return \Drupal\flowdrop_runtime\Service\Orchestrator\AgentTraceInterface
   *   The agent execution trace.
   */
  public function execute(
    string $executionId,
    string $nodeId,
    array $inputData,
    array $config,
    WorkflowDTO $workflow,
    string $pipelineId,
    DependencyGraph $dependencyGraph,
    NodeExecutionContext $context,
  ): AgentTraceInterface;

}
