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, AgentResources $resources) receives one exact routed event type; the third parameter is optional. 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, and run options. Events route execution; the segment's provider, chat history, instructions and tools arrive in AgentResources, built once per segment, so nodes take no collaborators in their constructors. getMessage() reads the provider response, while extra artifacts can use state keys.