neuron-agent-builder

name

neuron-agent-builder

description

Create and configure Neuron AI agents with providers, tools, instructions, and memory. Use this skill whenever the user mentions building agents, creating AI assistants, setting up LLM-powered chat bots, configuring chat agents, or wants to create an agent that can talk, use tools, or handle conversations. Also trigger for any task involving agent configuration, provider setup, tool integration, or chat history management in Neuron AI.

Neuron AI Agent Builder

This skill helps you create and configure Neuron AI agents for building agentic applications in PHP.

Core Agent Structure

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

use NeuronAI\Agent;
use NeuronAI\Agent\SystemPrompt;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\Anthropic\Anthropic;

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

    protected function instructions(): string
    {
        return (string) new SystemPrompt(
            background: [
                "You are a helpful AI assistant."
            ]
        );
    }
}

Agent Execution Methods

Chat Mode (Synchronous)

For standard back-and-forth conversations:

$agent = MyAgent::make();

$response = $agent->chat(
    new UserMessage("Hello!")
)->getMessage();

echo $response->getContent();

Stream Mode (Real-time)

For streaming responses as chunks arrive. Chunks represents pieces of context that are generated by the model. The TextChunk class is used to represent a piece of text, but there are other chunk types available:

• NeuronAI\Chat\Messages\Chunks\TextChunk
• NeuronAI\Chat\Messages\Chunks\ImageChunk
• NeuronAI\Chat\Messages\Chunks\AudioChunk
• NeuronAI\Chat\Messages\Chunks\ToolCallChunk
• NeuronAI\Chat\Messages\Chunks\ToolResultChunk

$handler = $agent->stream(new UserMessage("Hello"));

foreach ($handler->events() as $event) {
    if ($event instanceof TextChunk) {
        echo $event->content;
    }
}

Streaming Adapters for UI Integration

When connecting a frontend UI to an agent, use streaming adapters to format the response for specific protocols. This enables seamless integration with popular AI UI libraries.

When to use:

• Building a chat interface with React/Vue/Next.js
• Using Vercel AI SDK's useChat hook
• Implementing AG-UI protocol for agent-frontend communication
• Any SSE-based real-time UI updates

Available adapters:

• VercelAIAdapter - Compatible with Vercel AI SDK (useChat, useCompletion)
• AGUIAdapter - AG-UI protocol for agent interactions

Laravel example:

use NeuronAI\Chat\Messages\Stream\Adapters\VercelAIAdapter;

Route::post('/chat', function (Request $request) {
    $handler = MyAgent::make()->stream(
        new UserMessage($request->input('message'))
    );

    $stream = $handler->events(new VercelAIAdapter());

    return response()->stream(
        function () use ($stream) {
            foreach ($stream as $line) {
                echo $line;
                ob_flush();
                flush();
            }
        },
        200,
        $adapter->getHeaders()
    );
});

Structured Output Mode

For extracting structured data from a natural language:

class Person
{
    #[SchemaProperty(description: 'The user name', required: true)]
    public string $name;

    #[SchemaProperty(description: 'What the user loves to eat')]
    public string $preference;
}

$person = $agent->structured(
    new UserMessage("I'm John and I like pizza!"),
    Person::class
);

Providers Configuration

Anthropic

new Anthropic(
    key: $_ENV['ANTHROPIC_API_KEY'],
    model: 'claude-3-5-sonnet-20241022',
)

OpenAI

new OpenAI(
    key: $_ENV['OPENAI_API_KEY'],
    model: 'gpt-4',
)

Ollama (Local)

new Ollama(
    baseUrl: 'http://localhost:11434',
    model: 'llama3',
)

Other Providers

• Gemini - Google AI models
• VertexAI - Google Vertex AI platform
• Mistral - Mistral AI models
• HuggingFace - Open models via HuggingFace
• Deepseek - DeepSeek models
• Grok - XAI models
• AWSBedrockRuntime - AWS Bedrock inference platform
• Cohere - Cohere models
• AzureOpenAI - Use OpenAI models on the Azure platform
• ZAI - ZAI for GLM models

Tools Integration

Adding Built-in Toolkits

use NeuronAI\Tools\Toolkits\MySQL\MySQLToolkit;
use NeuronAI\Tools\Toolkits\Calculator\CalculatorToolkit;

protected function tools(): array
{
    return [
        MySQLToolkit::make(\DB::connection()->getPdo()),
        CalculatorToolkit::make(),
    ];
}

Available Toolkits

• MySQLToolkit - Database queries via MySQL
• PostgreSQLToolkit - Database queries via PostgreSQL
• CalculatorToolkit - Math operations (sum, mean, std, etc.)
• TavilyToolkit - Web search with Tavily
• SESToolkit - Email sending via AWS SES
• JinaToolkit - Reranking with Jina

Creating Custom Tools

use the neuron-tool-creator skills for more complex tool creation:

use NeuronAI\Tools\Tool;
use NeuronAI\Tools\ToolProperty;

class WeatherTool extends Tool
{
    public function __construct()
    {
        parent::__construct(
            name: 'get_weather',
            description: 'Get the current weather for a location',
        );
    }

    /**
     * @return ToolProperty[]
     */
    protected function properties(): array
    {
       return [
            new ToolProperty(
                name: 'location',
                type: ToolPropertyType::String,
                description: 'The city name',
                required: true,
            ),
        ];
    }

    public function __invoke(string $location): mixed
    {
        // Call weather API and return result
        return "The weather in {$location} is sunny, 72°F";
    }
}

System Prompt Engineering

Use SystemPrompt for structured agent instructions:

new SystemPrompt(
    background: [
        "You are a data analyst expert in creating reports.",
    ],
    steps: [
        "Analyze the user's request",
        "Query the database",
        "Generate a summary",
    ],
    output: [
        "Always cite your sources",
        "Never make up data",
    ]
)

Chat History

Agents automatically maintain conversation history. For custom components:

use NeuronAI\History\FileChatHistory;

// In agent class
protected function chatHistory(): ChatHistoryInterface
{
    return new FileChatHistory('/path/to/memory.json');
}

Memory Types

• InMemoryChatHistory - Default, session-based
• FileChatHistory - Persist to file
• SQLChatHistory - Database-backed
• EloquentChatHistory - Laravel Eloquent integration

Content Blocks (Multi-modal)

Agents support multiple content types:

use NeuronAI\Chat\Messages\ContentBlocks\TextContent;
use NeuronAI\Chat\Messages\ContentBlocks\ImageContent;
use NeuronAI\Chat\Enums\SourceType;

$message = new UserMessage([
    new TextContent('Analyze this image:'),
    new ImageContent(
        content: 'https://example.com/image.jpg',
        sourceType: SourceType::URL,
        mediaType: 'image/jpeg'
    ),
]);

CLI Generation

Use the Neuron CLI to generate an agent boilerplate:

vendor/bin/neuron make:agent MyCustomAgent

Common Patterns

Tool Approval Middleware

For human oversight of tool execution:

use NeuronAI\Agent\Middleware\ToolApproval;
use NeuronAI\Agent\Nodes\ChatNode;
use NeuronAI\Agent\Nodes\StreamNode;
use NeuronAI\Agent\Nodes\StructuredOutputNode;

// In agent constructor
$this->middleware([
    ChatNode::class,
    StreamNode::class,
    StructuredOutputNode::class
], new ToolApproval());

Observability with Inspector

Monitor agent execution:

# Set environment variable
INSPECTOR_INGESTION_KEY=your_key_here

Parallel Tool Calls

Execute tools in parallel (requires pcntl):

$agent->parallelToolCalls(true);

Key Decisions

When helping users build agents:

1. Choose execution mode based on requirements:

   • chat() for standard conversations
   • stream() for real-time streaming
   • structured() for data extraction

2. Add tools when the agent needs to:

   • Access external systems (databases, APIs)
   • Perform calculations
   • Search the web
   • Send emails

3. Configure chat history when:

   • Long-running conversations need persistence
   • Multiple sessions should share history
   • Conversation context needs to be shared across agents

4. Use middleware for:

   • Context summarization
   • Tool approval workflows
   • Custom pre/post nodes processing

Project Structure Considerations

For Laravel projects:

namespace App\Neuron;

class MyAgent extends Agent { ... }

For Symfony projects:

• Use dependency injection for providers
• Configure a service in services.yaml