Multi-agent system: ability to exchange StructuredOutput Objects

[mayestik1]

Hello,
I think it would be nice to have native-implemented ability to share objects between Agent Tools.

Or perhaps the description of the StructuredOutput properties could be adjusted to match the format expected by the Symfony Serializer.

Use case:

Imagine that you have "Main Agent" with defined tools

1. read_invoice_from_file - tool where "InvoiceAgent" is invoked to read a file, parse it to StructuredOutput, validates readed data with database for example with companies table. This "InvoiceAgent" has tools needed to process invoice files, validate them, checking database, etc.
2. save_invoice - simple tool, where Main Agent can pass Invoice readed from "read_invoice_from_file" tool

<?php

$tool_1 =Tool::make('read_invoice_from_file', 'Analyze invoice from passed file.
After invoice is analysed, propose user to save this invoice',
)->addProperty(
	new ToolProperty(name: 'file_id', type: 'string', description: 'ID', required: true)
)->addProperty(
	new ToolProperty(name: 'file_name', type: 'string', description: 'File name', required: true)
)->addProperty(
	new ToolProperty(name: 'mimeType', type: 'string', description: 'mimeType', required: true)
)->addProperty(
	new ToolProperty(name: 'file_url', type: 'string', description: 'URL', required: true)
)->setCallable(new ReadInvoiceTool($this->inspector));

$tool_2 = Tool::make('save_invoice', 'Save invoice to database',
)->addProperty(
	new ToolProperty(
		name: 'invoice_json',
		type: 'string',
		description: 'Invoice object in JSON format returned from read_invoice_from_file tool',
		required: true
	)
)->setCallable(new SaveInvoiceTool($this->getUserId()));
?>

At the moment, I’m manually transforming the StructuredOutput produced by the read_invoice_from_file tool into JSON. And when I ask "MainAgent" to save the invoice, it passes this json to "save_invoice" tool, where I must deserialize this object.

My example Mapper code:

class InvoiceMapper
{
    /**
     * @param  array<string,mixed>  $data
     *
     * @throws InvalidArgumentException if required sections are missing
     */
    public static function map(array $data): Invoice
    {
        $invoice = new Invoice;

        $invoice->companyId = isset($data['companyId']) ? (string) $data['companyId'] : '';
        $invoice->customerId = isset($data['customerId']) ? (string) $data['customerId'] : '';
        $invoice->description = $data['description'] ?? '';
        $invoice->originalNumber = $data['originalNumber'] ?? '';

        // --- seller
        if (! isset($data['seller']) || ! is_array($data['seller'])) {
            throw new InvalidArgumentException('Missing or invalid seller data');
        }
        $invoice->seller = self::mapContractor($data['seller']);

        // --- payments
        $invoice->payments = [];
        foreach ($data['payments'] ?? [] as $p) {
            if (! is_array($p)) continue;
            $pay = new InvoicePayment;
            // ...
            $invoice->payments[] = $pay;
        }

        // --- positions
        $invoice->positions = [];
        foreach ($data['positions'] ?? [] as $pos) {
            if (! is_array($pos)) continue;
            $item = new PurchaseInvoicePosition;
            $item->productName = $pos['productName'] ?? '';
            $item->amount = $pos['amount'] ?? 0;
            $item->unit = $pos['unit'] ?? '';
            $item->price= $pos['price'] ?? 0.0;
            // ...
            $invoice->positions[] = $item;
        }

        // --- Tax summary
        $invoice->vatSummary = [];
        foreach ($data['vatSummary'] ?? [] as $v) {
            if (! is_array($v)) {
                continue;
            }
            $vs = new InvoiceVatSummary;
            $vs->netSum = $v['netSum'] ?? 0.0;
            // ...
            $invoice->vatSummary[] = $vs;
        }

        return $invoice;
    }

    private static function mapContractor(array $data): InvoiceContractor
    {
        $c = new InvoiceContractor;
       // ....
        return $c;
    }
}

As you can see, there’s a ton of code written just to pass objects between tools (agents).
I have tried implementing Symfony Serializer, but with no luck, because of incompatible PHPDoc in StructuredOutput Classes.

I found that the Symfony Serializer requires the following structure:

    /**
     * @var InvoicePosition[]
     */
    #[SchemaProperty(description: 'List of positions.', required: true)]
    #[Valid]
    #[NotBlank]
    public array $positions;

While Neuron library is using different phpdoc:

  /**
     * @var array<\App\Neuron\Structures\InvoicePosition>
     */
    #[SchemaProperty(description: 'List of positions.', required: true)]
    #[Valid]
    #[NotBlank]
    public array $positions;