Symfony AI - Mate Component

Installation

1

$ composer require --dev symfony/ai-mate

For a Symfony application, add the two extensions:

1

$ composer require --dev symfony/ai-symfony-mate-extension symfony/ai-monolog-mate-extension

Quick Start

Initialize Mate in your project:

1

$ vendor/bin/mate init

mate init asks which command your coding agent should use to run Mate. If your PHP runs in a container or behind a wrapper, answer with the wrapper, for example ddev exec or symfony php. Otherwise accept the default. Integration has the details. The command then creates:

• mate/config.php for parameters and services
• mate/extensions.php, the list of extensions that mate discover fills
• mate/.env and mate/.gitignore
• mate/src/ for your own tools
• mate/AGENT_INSTRUCTIONS.md, a managed block in AGENTS.md, and a CLAUDE.md that imports AGENTS.md so Claude Code picks the instructions up

It also adds this to your composer.json:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

{
    "autoload-dev": {
        "psr-4": {
            "Mate\\": "mate/src/"
        }
    },
    "extra": {
        "ai-mate": {
            "extension": false,
            "scan-dirs": ["mate/src"],
            "includes": ["mate/config.php"]
        }
    }
}

extension: false keeps your application from being discovered as a Mate extension when it is installed as a dependency elsewhere.

Then register the new namespace and let Mate find the installed extensions:

1
2

$ composer dump-autoload
$ vendor/bin/mate discover

mate discover registers the installed extensions, writes the agent instructions and installs the skills. Check the result:

1

$ vendor/bin/mate tools:list

Then check that your coding agent can run the same command. If it does not pick Mate up on its own afterwards, see Integration.

Using Mate from a Coding Agent

There is nothing to start. The agent learns about Mate from AGENTS.md and the installed skills, and works with four commands:

1
2
3
4

$ vendor/bin/mate tools:list                          # what is available
$ vendor/bin/mate tools:inspect symfony-profiler-list # parameters and JSON input schema
$ vendor/bin/mate tools:call symfony-profiler-list --limit=1
$ vendor/bin/mate resources:read symfony-profiler://profile/

Tool parameters are passed as long options, one per parameter, and cast to the declared type. A boolean may be passed as a bare flag, and a variadic parameter takes the option repeated. Nested values are passed as a JSON object, and so is a parameter whose name collides with a console option like format:

1
2
3

$ vendor/bin/mate tools:call monolog-search --term="^GET" --regex
$ vendor/bin/mate tools:call  --tag=a --tag=b
$ vendor/bin/mate tools:call  --json='{"filters": {"level": "error"}}'

All four commands accept --format. Use --format=json when the result is parsed, and --format=toon (requires helgesverre/toon) for the smallest context footprint. See Command Reference for every command and option.

Adding Custom Tools

Add a class with a public method that carries the #[MateTool] attribute to mate/src/:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

// mate/src/MyTool.php
namespace Mate;

use Symfony\AI\Mate\Attribute\MateTool;

class MyTool
{
    /**
     * @param string $param The value to process
     */
    #[MateTool(name: 'my-tool', title: 'My Tool', description: 'My custom tool')]
    public function execute(string $param): array
    {
        return ['result' => $param];
    }
}

Mate discovers the method by reflection and derives its JSON input schema from the signature plus the @param PHPDoc. The description you write there is what the agent sees in tools:inspect. Constructor dependencies are injected from Mate's DI container.

Two more attributes cover data the agent navigates into:

• #[MateResource] marks a method as a static resource with a fixed uri.
• #[MateResourceTemplate] marks a method as a templated resource. The variables in its uriTemplate are passed to the method.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

// mate/src/MyResources.php
namespace Mate;

use Symfony\AI\Mate\Attribute\MateResource;
use Symfony\AI\Mate\Attribute\MateResourceTemplate;

class MyResources
{
    #[MateResource(uri: 'my-app://config', name: 'config', mimeType: 'application/json')]
    public function config(): string
    {
        return json_encode(['debug' => true]);
    }

    #[MateResourceTemplate(uriTemplate: 'my-app://entity/{id}', name: 'entity')]
    public function entity(string $id): array
    {
        return ['id' => $id];
    }
}

A tool is something the agent calls with arguments. A resource is something it addresses and can drill into, which keeps large payloads out of the context window until they are needed:

1
2

$ vendor/bin/mate tools:call my-tool --param=value
$ vendor/bin/mate resources:read my-app://entity/42

Run composer dump-autoload when the autoloader does not know the new class yet, and verify with vendor/bin/mate tools:list. To share tools between projects, see Creating Mate Extensions.

Configuration

Mate works without further configuration. Come back to this section when a default does not fit.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

// mate/config.php
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

return static function (ContainerConfigurator $container): void {
    $container->parameters()
        ->set('mate.invocation', 'vendor/bin/mate')
        ->set('mate.php_version', '8.3')
        ->set('ai_mate_monolog.log_dir', '%mate.root_dir%/var/log')
    ;

    $container->services()
        ->defaults()
            ->autowire()
            ->autoconfigure()

        // Register your custom services here
    ;
};

1
2
3
4

$container->parameters()
    ->set('mate.env_file', '.env')         // the env files of your application
    // ->set('mate.env_file', 'mate/.env') // or variables that only Mate needs
;

1
2
3
4
5

// mate/extensions.php
return [
    'vendor/package-name' => ['enabled' => true],
    'vendor/another-package' => ['enabled' => false],
];

1
2
3
4
5
6
7
8
9

use Symfony\AI\Mate\Container\MateHelper;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

return static function (ContainerConfigurator $container): void {
    MateHelper::disableFeatures($container, [
        'symfony/ai-mate' => ['server-info'],
        'symfony/ai-monolog-mate-extension' => ['monolog-list-channels'],
    ]);
};

Extensions

The core package ships one tool, server-info. It reports the PHP version, the OS and the loaded PHP extensions of the runtime Mate uses. Everything else comes from extensions:

• The Symfony extension (symfony/ai-symfony-mate-extension) searches the compiled container and reads the profiler.
• The Monolog extension (symfony/ai-monolog-mate-extension) searches the log files.

Both are documented in Mate Extensions. Community extensions, for example for PHPUnit, PHPStan or Rector, are listed in awesome-mate and installed the same way:

1

$ composer require --dev matesofmate/phpunit-extension

The Composer plugin then runs mate discover, which enables the extension and installs its skills. To write your own extension, see Creating Mate Extensions.

Security

Mate runs locally, with the permissions of the user who starts it. Two things deserve attention:

Extensions are code. Every installed package with an extra.ai-mate section is discovered and enabled by default. Its tools run on your machine, and its instructions and skills are read by your agent. Review mate/extensions.php after installing packages, and commit it together with the generated skill folders so that changes show up in code review.

Tool output is data. Logs, profiles and container metadata contain text that end users and third-party packages control. Both extensions mark such output as untrusted and redact known sensitive values. See Mate Extensions. Redaction is best effort, so treat the output of the profiler and log tools as sensitive.

Further Reading