neuron-agent

Neuron AI Agent

Agent is a composition built on Workflow. Extend it when its defaults fit, use its entry/exit hooks for additional stages, or compose a Workflow from the standalone components when control flow differs substantially. This skill covers the current major-version APIs; use the implementation's class names and signatures rather than older examples.

Use Agent::submitApprovalDecisions($decisions) for tool approval and Agent::submitToolResults($results) for deferred tool results. Both accept maps keyed by tool call ID and stage a continuation; finish with run() for an AgentState or events() for a stream.

Core Agent Structure

A Neuron agent extends the Agent class and implements key methods:

use NeuronAI\Agent\Agent;
use NeuronAI\Chat\Messages\SystemMessage;
use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\Anthropic\Anthropic;

class MyAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        return new Anthropic(
            key: $_ENV['ANTHROPIC_API_KEY'],
            model: $_ENV['ANTHROPIC_MODEL'],
        );
    }

    protected function instructions(): SystemMessage|string
    {
        return new SystemMessage("You are a helpful AI assistant.");
    }
}

Workflow Boundaries and Custom Nodes

The default path is:

AgentStartEvent → AgentStartNode → inference ⇄ tools
    final response → AgentOutputEvent → AgentEndNode → StopEvent

ChatNode handles chat and streaming; StructuredOutputNode handles structured inference. Tools may pause for approval or deferred results before returning to inference. AgentOutputEvent means the final answer is available for output processing; it is not a terminal event.

• nodes() rebuilds the graph from the current configuration each execution segment. entryNodes() defaults to AgentStartNode; exitNodes() defaults to AgentEndNode.
• A node's __invoke(EventType $event, AgentState $state) receives one exact routed event type. addNode() registers a handler; array order does not connect nodes, and duplicate handlers are rejected.
• For preprocessing, override startEvent() with an AgentStartEvent subclass, register a node for it in entryNodes(), and return the original AgentStartEvent to retain parent::entryNodes(). This keeps request initialization and tool-run resets in AgentStartNode. Replacing that initialization entirely requires handling those responsibilities yourself.
• For postprocessing, override exitNodes() with a node accepting AgentOutputEvent. Return an application event to continue through another node, or StopEvent to finish. Replace the default ending: including parent::exitNodes() alongside another output handler creates a duplicate.
• AgentState::$request holds instructions, messages, tools, and run options. Events route execution; collaborators such as providers and history remain node dependencies. getMessage() reads the provider response, while extra artifacts can use state keys.