Getting Started

Prerequisites. A Symfony app (6.4/7.x) on PHP 8.2+, a local dev environment with symfony/web-profiler-bundle installed, and an AI Mate client/agent that can connect to your app's tool server. No dependents and a thin README mean you should treat the package as "read the source before trusting the docs."

Minimal steps.

Install as a dev-only dependency, pinned to the release you validated (0.14.0 as of this update):
```
composer require --dev symfony/ai-symfony-mate-extension:0.14.0
```
Confirm the actual package name on Packagist — this bridge lives in the symfony/ai monorepo and may be published as a split package or shipped via the parent.
Register the bundle only in dev/test. In config/bundles.php:
```
return [
    // ...
    Symfony\AI\SymfonyMateExtension\SymfonyMateExtension::class => ['dev' => true, 'test' => true],
];
```
Prefer Flex's when@dev config blocks over unconditional registration.
Enable the capability families independently if config allows — container introspection, .env inspection, and profiler access should be separate flags, since profiler data is optional and often unavailable, and env inspection should be opt-in on shared setups.

Verify registration before wiring the agent:

bin/console debug:container --tag=ai.tool      # tag name may differ — check the source
bin/console list                              # look for an AI Mate / tool-listing command

Connect your AI Mate client and start with symfony-dotenv-check (added in 0.14.0): it is read-only, has no runtime prerequisites, and answers a question you can verify by hand. Then move to container questions.

Where to look first.

The symfony/ai main repository, not just this bridge — the bridge is a thin adapter and the tool abstractions live upstream.
config/services.php / config/services.yaml inside the extension: it tells you exactly what is registered, under which service IDs, and with which tags. This is also where per-tool feature flags live.
The tool classes themselves (one class per capability). Their method signatures are the real documentation for what the agent can call — in particular the argument shape of symfony-service-detail, which grew in 0.14.0.
bin/console debug:config <extension_alias> after registration to see the real alias and defaults.

First use case. Ask the agent to run symfony-dotenv-check: "Compare .env, .env.local, and .env.test, and tell me which keys are defined in one but missing from the others, and which keys look unused." This exercises the newest tool end-to-end, is read-only, and the result is trivially cross-checkable with grep/diff. Then follow with the container smoke test: "List every service tagged kernel.event_subscriber, show the class and the file where it is defined, and flag any that are private or inlined" — and compare against debug:container --tag=kernel.event_subscriber.

Implementation Patterns

Treat the capability families as separate workflows. Container introspection answers "what is wired how"; .env inspection answers "which configuration is even reachable"; profiler access answers "what happened during that request." Mixing them in a single prompt produces vague answers. Sequence the prompts, and use the env tool as the first step of any "why is config wrong" investigation.

Container introspection patterns. In 0.14.0, symfony-service-detail reports definition flags and constructor arguments, which changes what is worth asking:

Definition-flag audits: "For App\Service\Foo, show its definition flags — public/private, lazy, shared, abstract, synthetic, autowired, autoconfigured, deprecated — and explain which of them change behavior at runtime."
Constructor-argument archaeology: "Show the constructor arguments wired into App\Service\Foo and identify which of them are references to other services versus inline scalars."
Interface-to-implementation mapping: "Which service implements App\Contract\PaymentGateway, and is it the one autowired into CheckoutHandler?"
Autowiring failures: "Why can't App\Service\Foo be autowired? List candidate services and their aliases."
Tag auditing: "Which services are tagged app.scheduled_task, and what priority do they have?"
Dead-code sweeps: "List public services that are never referenced by another service definition."

.env inspection patterns.

Drift detection: "Which keys exist in .env but not in .env.example?" — cheap, catches documentation rot on every PR.
Missing-in-CI triage: "Which keys referenced by config/ are absent from .env.test and from the environment variables declared in CI?"
Unused-key sweeps: "List keys in .env that no config file references."
Environment diffing: "Show the key-set difference between .env, .env.local, .env.test, and .env.local.php if present."

Ask about key presence and key sets, not values. If the tool's output ever includes a value, that is a bug worth reporting upstream.

Profiler patterns.

Token-driven investigation: reproduce the bug in the browser, copy the token from the profiler URL, then ask "For token abc123, list every DB query over 50 ms with its caller."
Endpoint triage: "Show the five slowest profiles from today, and for the worst one break down time by collector (DB, cache, HTTP client, events)."
Cross-reference: "For the slowest request, which of the services involved are tagged app.expensive, and what are their constructor arguments?" — now answerable in one hop thanks to service-detail's constructor args.
Regression comparison: profile before and after a change, then ask for a diff of query counts and timings between the two tokens.

Agent-instruction integration. Add a short block to AGENTS.md/system prompt:

Use symfony-dotenv-check for questions about which config keys exist; never
paste .env values into chat. Use container tools for wiring questions and
profiler tools for runtime questions. For a service whose behavior you don't
understand, ask for its definition flags and constructor arguments before
guessing at a file path. Never modify files based on tool output without
confirming with the developer.

This measurably reduces the agent guessing at file paths instead of querying the compiled container.

Extension points. The valuable long-term pattern is contributing your own domain tools alongside the built-ins: a class with an invokable method, registered as a service with the same tool tag the bridge uses. Good candidates are things the agent cannot infer from source alone — feature-flag state, tenant resolution rules, queue depth. Keep them read-only.

Integration with tests. Profiler data is also produced by functional tests using KernelBrowser with the profiler enabled. If your CI agent runs tests, it can inspect profiles from a failing test run rather than requiring a live browser — a useful pattern for "why is this test's query count high." Likewise, run symfony-dotenv-check in CI as a key-set linter rather than as an agent tool.

Gotchas and Tips

symfony-dotenv-check reads files, not resolved configuration.

The runtime value of an env var is resolved through a chain: real process env → .env.local.php (if composer dump-env was run) → .env.$APP_ENV.local → .env.$APP_ENV → .env.local → .env. A file-based checker can report a key "missing" when it is actually baked into .env.local.php or injected by the platform. Always ask which files the tool considers in scope.
%env(bool:FOO)%, %env(json:FOO)%, default: prefixes, and Symfony Secrets vault entries are resolution-time concerns. A checker sees the raw declaration; it cannot tell you whether the value parses.
Do not assume "safe inspection" means "redacted by default" — verify the output shape on a scratch .env before pointing a remote agent at it.

Container introspection reflects the compiled container — and now, also the definition.

symfony-service-detail reports definition flags and constructor arguments from the service definition, which is pre-compilation-pass. A service can be public in the definition and still be removed or inlined in the compiled container. If the flags disagree with what actually resolves, cross-check with debug:container --show-private.
Constructor arguments include env placeholders and, in dev, sometimes resolved values. Assume anything the agent can read can end up in a transcript; redact or disable the argument display if that matters.
In dev, the container is rebuilt on config changes but not always on every request; a stale var/cache/dev container produces stale answers. Clear when in doubt.

Profiler data is fragile and short-lived.

Profiles only exist when the profiler is enabled and the request actually went through the kernel. CLI commands and many test paths produce nothing — the agent will otherwise confidently report "no profiles found" as if it were an app problem.
Storage location and retention are configurable (framework.profiler.dsn, filesystem by default). cache:clear, cache:pool:clear, and container rebuilds can orphan or wipe tokens. Always pass a fresh token.
Tokens are not stable identifiers across restarts. Do not hardcode them into prompts, docs, or agent memory.

Environment and bundling quirks.

Register under when@dev only. A dev-only bridge that leaks into prod can break cache:warmup or add unnecessary compile-time work.
If the bundle hard-depends on web-profiler-bundle, don't install it in prod just to satisfy autoloading — split the profiler capability behind a config flag or a separate install.
symfony-dotenv-check is genuinely useful in CI, but only if it is a dev dependency available there; don't let a "safe inspection" tool become a production autoload requirement.

Version and maturity expectations. This is a pre-1.0 package moving fast: 0.14.0 added two capabilities to an existing tool and introduced a whole new tool in a single minor release. Pin an exact version, read the changelog before bumping, and avoid building workflows that depend on a specific tool name, argument name, or config key without a test that catches breakage. Issues still belong upstream in the main symfony/ai repo (the README redirects there).

Output size and token bloat. Container dumps, constructor arguments, and full query logs are enormous. Always constrain prompts with filters — specific service IDs, tag names, token, time thresholds, limits, and for the env tool a specific key prefix. If the bridge offers pagination or filtering, prefer it over asking for "all services."

Security posture. Profiler payloads routinely contain request bodies, cookies, auth headers, and session data; .env files contain credentials by definition. In a shared or remote-agent setup, treat profiler access as equivalent to granting shell access to logs, and treat env access as equivalent to reading the secrets store. Keep both local, and never commit profiler dumps, .env output, or agent transcripts containing them.

Debugging the bridge itself.

Tools not appearing: confirm the bundle is in config/bundles.php, the tool tag is applied (debug:container --tag=...), the relevant capability flag is on, and the AI Mate client is pointed at the right endpoint.
Tool errors: check var/log/dev.log; argument validation failures from the agent usually surface as a tool-side exception, not a client error.
Name collisions: if you add custom tools, namespace their names — the agent picks by name, and silent shadowing is hard to spot.

Ai Symfony Mate Extension Laravel Package

Getting Started

Implementation Patterns

Gotchas and Tips