Download the PHP package errogaht/neuron-ai-bundle without Composer

Neuron AI Bundle

Symfony-native integration for Neuron AI: configure providers, agents, RAG and workflow infrastructure in YAML, inject named runtimes through autowiring, attach ordinary Symfony services or a configured Doctrine MCP server as tools, and optionally run agents or workflows through Messenger.

The bundle does not replace Neuron AI. It removes repetitive construction and configuration while leaving the complete Neuron API available for streaming, structured output, RAG, workflows, persistence, human-in-the-loop, MCP and observability.

Requirements

• PHP 8.1 or newer
• Symfony 6.4, 7.4 or 8.x
• Neuron AI 3.15

Installation

If Symfony Flex does not enable the bundle automatically, add it to config/bundles.php:

Quick start

Store credentials in .env.local or your deployment secret manager:

Create config/packages/neuron_ai.yaml:

Use the default configured agent directly:

Or use the stable Symfony-facing runner, which dispatches bundle events and returns a serializable result:

For low-latency HTTP or console output, consume typed Neuron stream chunks and read the normalized final result from the generator return value:

The generator must be consumed to completion. stream() uses the same fresh agent factory, tool loop, completion/failure events and normalized AgentRunResult contract as chat().

Named autowiring

Each configured provider, agent, workflow, embedding provider, and vector store receives a Symfony named-autowiring alias. Stateful agents, workflows, and vector-search filters are isolated according to their runtime boundary:

This is intentional: Neuron providers, agents and tools accumulate run state. Fresh services prevent prompts, tool inputs or history from leaking into another request.

Symfony services as tools

Create any Neuron ToolInterface or toolkit as a normal autowired Symfony service:

Attach its service ID to an agent:

Autoconfiguration is not magic discovery: only tools explicitly listed on an agent are exposed to that model. This keeps the capability boundary reviewable.

Multiple tools in one service

For a cohesive group of operations, extend AbstractToolGroup and expose selected public methods with attributes. Constructor dependencies are autowired exactly like any other Symfony service:

Connect the whole group with one service ID:

The group is a native Neuron toolkit. Method names become snake_case unless name is provided. Schema types and required fields are inferred from PHP scalar/array types, nullable/default parameters, and backed enums. Use #[ToolParameter] for descriptions, explicit PropertyType, enum values or a required override. Complex DTO schemas should use a native Neuron Tool class.

Doctrine MCP Bundle bridge

When the application also uses Doctrine MCP Bundle, a configured MCP server can be attached to an agent without publishing an HTTP endpoint or specifying an MCP URL:

Configure entities, fields, actor resolution, query scopes and custom MCP tools in doctrine_mcp as usual. Then enable the bridge on the required Neuron agent:

That is the complete connection configuration: there is no URL, port, SSE transport, HTTP request or duplicated tool registration. The bundle opens an isolated in-process MCP protocol session against the application's existing doctrine_mcp.server. All built-in Doctrine tools and custom tools discovered by Doctrine MCP Bundle are available by default.

Reduce the model-visible capability set per agent with only and exclude:

exclude takes precedence when a name appears in both lists. These lists control which tools the model can see; they are not authorization rules. The same Doctrine MCP handlers still resolve the current actor and execute configured entity scopes, validation, audit and dry-run behavior.

For synchronous HTTP requests, the usual Symfony security context remains available to the Doctrine MCP actor provider. Messenger workers have no authenticated browser session by default: configure a worker-safe ActorProviderInterface and restore identity from trusted, validated job context before exposing tenant or user data. Never accept a tenant or actor identifier merely because the model supplied it.

The bridge exposes MCP tools, matching Neuron's McpConnector. MCP resources and prompts are not converted into tools. No bridge services are registered when doctrine_mcp.enabled is false, so Doctrine MCP Bundle remains an optional dependency.

Class-first reusable agents

An agent can own its prompt and tools entirely in one application class. Mark an autoconfigured Symfony service with #[AsNeuronAgent]; it becomes available both by its concrete class and by a stable registry name used by AgentRunner, console commands and Messenger:

$mainProvider uses the named provider autowiring configured under neuron_ai.providers.main. Tool constructor dependencies are ordinary Symfony services. No neuron_ai.agents entry is required.

Use the concrete service directly:

Or use its registered name wherever the bundle lifecycle is useful:

Named autowiring also works with AgentInterface $orderManagerAgent. The attribute makes every instance non-shared because Neuron agents contain mutable workflow state. If no name is supplied, OrderManagerAgent becomes order_manager. The class must be covered by Symfony's normal services.yaml resource with autoconfigure: true.

Class-owned agents preserve their own provider, instructions() and tools(). Creating them through AgentFactory or AgentRunner additionally applies bundle configurators and observers. Direct concrete-class injection intentionally gives the native service without request-specific AgentContext processing.

An attributed agent may also be the default without duplicating it in agents:

RAG and vector stores

RAG needs two separate model-facing components: an embedding provider converts text into vectors, and a vector store persists and searches those vectors. The chat provider still generates the final answer. The bundle makes all three named Symfony services and wires them into Neuron's native RAG class.

The embedding dimensions must match the vector collection dimensions. Changing the embedding model or dimensions normally requires rebuilding that collection.

Data loaders and indexing

A loader is an ordinary autowired Symfony service implementing Neuron's DataLoaderInterface. It can read Doctrine entities, APIs, CMS content, files or any application data:

Run a pipeline manually, during deployment, or from Scheduler/cron:

--reindex deletes each returned sourceType/sourceName once before inserting its new chunks. Stable source identifiers are therefore important. Deletion and remote embedding/upsert cannot be made transactionally portable across every engine, so schedule retries and backups according to the selected store. Pipelines are also callable from application code through RagIndexer::index().

Supported RAG drivers

Embedding types: openai, openai_like, ollama, gemini, mistral, voyage, cohere, and service.

For compatibility with Neuron 3.15, the built-in openai_like embedding driver cannot receive custom HTTP headers or Guzzle options. Select type: service when that transport customization is required.

Vector-store types: memory, file, qdrant, pinecone, chroma, meilisearch, weaviate, and service. Use service for every Neuron adapter that requires its own client object, including Elasticsearch, OpenSearch, MariaDB, Typesense and third-party packages:

Named autowiring follows the same convention as providers and agents:

The default entries autowire without a named argument. Vector stores injected into agents are query-scoped clones, preventing mutable metadata filters from leaking between users; ingestion uses the canonical store. Custom vector-store services must therefore be cloneable. For an in-memory store, index before creating the agent because each agent receives a snapshot. Persistent stores share their external collection normally.

Class-first RAG agent

#[AsNeuronAgent] also works on a Neuron RAG subclass. Inject the named components and keep retrieval rules next to the prompt:

For YAML-owned RAG agents, rag.pre_processors, rag.post_processors, and rag.retrieval accept Symfony service IDs implementing the corresponding native Neuron interfaces.

Metadata filters are part of the authorization boundary. Derive tenant/user filters from trusted Symfony security context, never from model arguments, and apply them before similarity search. A vector database must not become a cross-tenant side channel.

Workflows, persistence, and human-in-the-loop

Neuron workflows keep their typed node/event graph in PHP. Symfony owns construction, named discovery, persistence, middleware, observers, lifecycle events, console execution, and optional Messenger dispatch:

Configured Workflow, Node, and middleware classes are ordinary autowired services. The factory returns a new Workflow and cloned node/middleware instances for every execution; only the persistence backend is deliberately shared so a later request or worker can resume an interruption.

Named autowiring follows Symfony's argument convention:

Class-first workflow

Keep graphs that inject agents or domain services entirely in their class:

No workflow.workflows entry is required for an attributed class. Use WorkflowRunner, WorkflowFactory, or named WorkflowInterface autowiring when the attribute's persistence and global observers must be applied. Direct concrete-class injection intentionally returns the native class-owned service without factory configuration.

Run, stream, interrupt, and resume

Streaming yields Neuron's native events and returns the normalized result from the Generator:

After the application validates human feedback and reconstructs the concrete InterruptRequest, resume through a fresh workflow instance:

The runner dispatches WorkflowRunStarted, WorkflowRunCompleted, WorkflowRunInterrupted, and WorkflowRunFailed. It logs identifiers, duration, and exception metadata, never workflow state by default.

Persistence backends

For PostgreSQL, distributed locks, encryption, tenant partitioning, or a custom schema, prefer type: service. The built-in database adapter follows the SQL behavior of the installed Neuron version.

File and database persistence serialize workflow state, nodes, events, and interrupt requests. Never use a public directory, keep secrets out of state, restrict permitted classes when crossing trust boundaries, and treat resume tokens as application credentials. Always resolve the workflow name and token from an authorized server-side record instead of accepting an arbitrary pair from a client. The runner accepts only portable alphanumeric, underscore, and hyphen tokens, preventing path syntax from reaching file persistence.

Workflow console and Messenger

The generic Messenger message starts workflows using the default StartEvent and JSON-safe state. Custom start Events and resume requests are application types, so dispatch those through an application-owned Messenger message and call WorkflowRunner in its handler.

Custom agents and all Neuron features

For configuration-owned agents, set class in YAML. Symfony autowires its constructor, then the bundle applies the configured provider, instructions, tools, configurators and observers:

Because the injected object is the real Neuron agent, its native APIs remain available:

RAG agents, workflow subclasses, persistence, MCP connectors and custom middleware remain ordinary Symfony services. Inject their dependencies in the constructor and select the class in neuron_ai.agents or neuron_ai.workflow.workflows. See Advanced integration.

Request-specific configuration

Use a configurator when history, tenant, locale, authorization or persistence depends on the current request or queued message:

The interface is autoconfigured. Pass context through AgentFactory::create() or AgentRunner::chat().

Console commands

neuron-ai:models understands OpenAI-compatible data[].id, Ollama models[].name, and configurable model-list paths.

Messenger

Install Messenger only when async execution is needed:

Run the worker and inspect the cache-backed result:

Messenger retries remain controlled by the host application's transport configuration. Prompts are carried in Messenger envelopes but are never stored in the bundle's result cache. See Messenger integration.

Provider types

See the complete configuration reference.

Events and observability

The runner dispatches:

• AgentRunStarted
• AgentRunCompleted
• AgentRunFailed
• WorkflowRunStarted
• WorkflowRunCompleted
• WorkflowRunInterrupted
• WorkflowRunFailed

Implement Neuron's ObserverInterface as an autoconfigured Symfony service to receive native Neuron events. The bundle deliberately logs metadata only and does not log prompts or responses by default.

Security model

• Keep API keys in environment secrets, never committed YAML.
• Treat tools as capabilities. Expose only the services required by each agent.
• Enforce user, tenant and object authorization inside application services/repositories. A system prompt is not an access-control mechanism.
• With Doctrine MCP, keep authorization in its actor provider and query scopes; only/exclude are defense-in-depth capability filters, not access control.
• Validate tool inputs and structured output before causing side effects.
• Configure Messenger encryption or an appropriate protected transport when prompts contain sensitive data.
• Use a dedicated cache pool with the required retention policy for async results.

Documentation

• Configuration reference
• Advanced Neuron integration
• Messenger integration
• Neuron AI documentation
• Neuron providers
• Neuron tools
• Neuron structured output
• Neuron RAG
• Neuron workflows

Development

License

MIT