NeuronAI architecture
NeuronAI architecture
namespace App\Neuron;
use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\MySQL\MySQLSchemaTool;
use NeuronAI\Tools\Toolkits\MySQL\MySQLWriteTool;
class MyAgent extends Agent
{
...
protected function tools(): array
{
return [
MySQLSchemaTool::make(new \PDO(...)),
MySQLWriteTool::make(new \PDO(...)),
];
}
}
### Tavily
This toolkit enable your agent to performs web search, page content extraction, and crawling.
```php
namespace App\Neuron;
use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\Tavily\TavilyToolkit;
class MyAgent extends Agent
{
...
protected function tools(): array
{
return [
TavilyToolkit::make(
key: 'TAVILY_API_KEY'
),
];
}
}
```
#### Tavily Web Search
It makes your Agent able to search the web. It requires access to [Tavily APIs](https://tavily.com/).
```php
namespace App\Neuron;
use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\Tavily\TavilySearchTool;
class MyAgent extends Agent
{
...
protected function tools(): array
{
return [
TavilySearchTool::make(
key: 'TAVILY_API_KEY'
),
];
}
}
```
You can customize the default options to retrieve search results by passing your preference in the `withOptions` method:
```php
TavilySearchTool::make(
key: 'TAVILY_API_KEY'
)->withOptions([
'days' => 30,
'max_results' => 10,
]),
```
#### Tavily Extract
Extract web page content from an URL. It requires access to [Tavily APIs](https://tavily.com/).
```php
namespace App\Neuron;
use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\Tavily\TavilyExtractTool;
class MyAgent extends Agent
{
...
protected function tools(): array
{
return [
TavilyExtractTool::make(
key: 'TAVILY_API_KEY'
),
];
}
}
```
#### Tavily Crawl
Tavily Crawl is a graph-based website traversal tool that can explore hundreds of paths in parallel with built-in extraction and intelligent discovery.
```php
namespace App\Neuron;
use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\Tavily\TavilyCrawlTool;
class MyAgent extends Agent
{
...
protected function tools(): array
{
return [
TavilyCrawlTool::make(
key: 'TAVILY_API_KEY'
),
];
}
}
```
### Jina
This toolkit enable your agent to performs web search, and read the content of a specific URL.
```php
namespace App\Neuron;
use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\Jina\JinaToolkit;
class MyAgent extends Agent
{
...
protected function tools(): array
{
return [
JinaToolkit::make(
key: 'JINA_API_KEY'
),
];
}
}
```
#### Jina Web Search
It makes your Agent able to search the web. It requires access to [Jina API](https://jina.ai/).
```php
namespace App\Neuron;
use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\Jina\JinaWebSearch;
class MyAgent extends Agent
{
...
protected function tools(): array
{
return [
JinaWebSearch::make(
key: 'JINA_API_KEY'
),
];
}
}
```
#### Jina URL Reader
Extract web page content from an URL. It requires access to [Jina API](https://jina.ai/).
```php
namespace App\Neuron;
use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\Jina\JinaUrlReader;
class MyAgent extends Agent
{
...
protected function tools(): array
{
return [
JinaUrlReader::make(
key: 'JINA_API_KEY'
),
];
}
}
```
### Zep Memory
This toolkit connects a NeuronAI Agent to [Zep](https://www.getzep.com/) knowledge graph. This kind of system allows the agent to store relevant facts that may emerge during interactions with the agent over time. It's a long term memory in the sense that is not limited to the current conversation like the [ChatHistory](/v1/components/chat-history-and-memory) component does. It's an external persistent storage the agent will use to store and retrieve single pieces of information that can allow more personalized answers.
To learn more about the capabilities of these kind of system you can visit the Zep website: use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\Observability\AgentMonitoring;
// Talk to the agent requiring the structured output
$person = MyAgent::make()->structured(
new UserMessage("I'm John and I want a pizza at st. James Street 00560!"),
Person::class
);
echo $person->name.' like '.$person->preference.'. Address: '.$person->address->street;
// John like pizza. Address: st.James Street
### Array
If you declare a property as an array Neuron assumes the list of items to be a list of string. Assume we want to add a list of tags to the Person object:
```php
tags;
/*
[
'tag 1',
'tag 2',
...
]
*/
```
### Array of objects
It could be needed to populate the list of tags with another structured data type. To do this you must add the `ArrayOf` attribute for properly validation, and specify the fully qualified class namespace in the doc-block for properly deserialization:
```php
structured(
messages: new UserMessage("I'm John and I like pizza!"),
class: Person::class,
maxRetries: 3
);
```
If you work with a less capable LLM consider to use a number of retries balancing the probability to get e valid answer, and the potential token consumption.
You can disable retry just passing zero. It will be a one shot attempt:
```php
$person = MyAgent::make()->structured(
messages: new UserMessage("I'm John and I like pizza!"),
class: Person::class,
maxRetries: 0
);
```
## Monitoring
To watch inside this workflow you should connect your Agent to the [Inspector monitoring dashboard](https://inspector.dev/) in order to see the tool call execution flow in real-time.
After you sign up at the link above, make sure to set the `INSPECTOR_INGESTION_KEY` variable in the application environment file to start monitoring:
{% code title=".env" %}
```
INSPECTOR_INGESTION_KEY=nwse877auxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```
{% endcode %}
namespace App\Dto;
use NeuronAI\StructuredOutput\Validation\Rules\Length;
class Person
{
#[Length(min: 1, max: 10)]
public string $name;
#[Length(exactly: 5)]
public string $zip_code;
}
namespace App\Dto;
use NeuronAI\StructuredOutput\Validation\Rules\ArrayOf;
class Person
{
/**
* @var \App\Dto\Tag[]
*/
#[ArrayOf(Tag::class)]
public array $tags;
}
Neuron architecture
use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\Observability\AgentMonitoring;
// Talk to the agent requiring the structured output
$person = MyAgent::make()->structured(
new UserMessage("I'm John and I want a pizza at st. James Street 00560!"),
Person::class
);
echo $person->name.' like '.$person->preference.'. Address: '.$person->address->street;
// John like pizza. Address: st.James Street
## Array
If you declare a property as an array Neuron assumes the list of items to be a list of string. Assume we want to add a list of tags to the Person object:
```php
tags;
/*
[
'tag 1',
'tag 2',
...
]
*/
```
### Array of objects
It could be needed to populate the list of tags with another structured data type. To do this you must add the `ArrayOf` attribute for properly validation, and specify the fully qualified class namespace in the doc-block for properly deserialization:
```php
" syntax:
```php
class Person
{
...
/**
* @var array<\App\TextBlock|\App\TableBlock>
*/
#[SchemaProperty(description: 'The list of tag for the user profile.', required: true)]
#[ArrayOf([TextBlock::class, TableBlock::class])]
public array $tags;
}
```
As you can notice from the examples above you can pass an array of class-string to the `ArrayOf` validation rule to ensure the final array will contains only instances of the listed classes.
## Max Retries
Since the LLM are not perfectly deterministic it's mandatory to have a retry mechanism in place if something is missing in the LLM response.
By default Neuron extracts and validates the data from the LLM response and if there is one or more validation errors automatically retry the request just one more time informing the LLM about what went wrong and for what properties.
You can eventually customize the number of times the agent must retry to get a correct answer from the LLM:
```php
$person = MyAgent::make()->structured(
messages: new UserMessage("I'm John and I like pizza!"),
class: Person::class,
maxRetries: 3
);
```
If you work with a less capable LLM consider to use a number of retries balancing the probability to get e valid answer, and the potential token consumption.
You can disable retry just passing zero. It will be a one shot attempt:
```php
$person = MyAgent::make()->structured(
messages: new UserMessage("I'm John and I like pizza!"),
class: Person::class,
maxRetries: 0
);
```
## Monitoring & Debugging
To watch inside this workflow you should connect your Agent to the [Inspector monitoring dashboard](https://inspector.dev/) in order to see the tool call execution flow in real-time.
After you sign up at the link above, make sure to set the `INSPECTOR_INGESTION_KEY` variable in the application environment file to start monitoring:
{% code title=".env" %}
```
INSPECTOR_INGESTION_KEY=nwse877auxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```
{% endcode %}
Neuron architecture
| Control | Transform prompts, tool selection, and output formatting. |
| Guardrails | Add retries, rate limits, implement guardrails, prompt rejection. |
| Monitor | Track agent behavior with logging, analytics, and debugging. |
Neuron architecture