---
title: "Creating an AI connector"
manual: "AI Assistant"
version: "main"
source: "Developers/Extending/CreatingAiConnector.rst"
rendered: "2026-10-03T14:54:45+00:00"
---

# Creating an AI connector {#creating-ai-connector}

AI connectors integrate language model and embedding providers into AI
Assistant. They are resolved through the AI connector registry by their
identifier and are configured through AI connection records.

## Responsibilities {#responsibilities}

-   expose a stable connector identifier;
-   accept an AI connection record;
-   create synchronous chat completions from `AiRequest`;
-   stream chat completions to a callback;
-   create embeddings from `EmbeddingRequest`;
-   create batch embeddings for multiple `EmbeddingRequest` objects;
-   map provider responses to `AiResponse` and `EmbeddingResponse`;
-   preserve usage information where available;
-   keep provider-specific authentication and request mapping inside the
    connector.

## Identifier {#identifier}

The identifier is stored in the AI connection record and is used by
`AiConnectorRegistry` to resolve the service.

```php
public function getIdentifier(): string
{
    return 'vendor.my_ai';
}
```

Use a namespaced identifier to avoid collisions with other extensions.

## Skeleton {#skeleton}

```php
<?php
declare(strict_types=1);

namespace Vendor\Extension\Connection\Ai;

use Madj2k\AiCore\Connection\Ai\AiConnectorInterface;
use Madj2k\AiCore\Connection\Ai\DTO\AiRequest;
use Madj2k\AiCore\Connection\Ai\DTO\AiResponse;
use Madj2k\AiCore\Connection\Ai\DTO\EmbeddingRequest;
use Madj2k\AiCore\Connection\Ai\DTO\EmbeddingResponse;
use Madj2k\AiCore\Connection\Configuration\AiConnectionConfigurationInterface;

final class MyAiConnector implements AiConnectorInterface
{
    public function getIdentifier(): string
    {
        return 'vendor.my_ai';
    }

    public function chat(AiConnectionConfigurationInterface $connection, AiRequest $request): AiResponse
    {
        // Build provider request from the connection and DTO.
        // Return a normalized AiResponse.
    }

    public function streamChat(AiConnectionConfigurationInterface $connection, AiRequest $request, callable $onData): void
    {
        // Build a streaming provider request and call $onData($chunk)
        // for every emitted text chunk.
    }

    public function embed(AiConnectionConfigurationInterface $connection, EmbeddingRequest $request): EmbeddingResponse
    {
        // Build provider embedding request.
        // Return one normalized embedding response.
    }

    public function embedBatch(AiConnectionConfigurationInterface $connection, array $requests): array
    {
        // Return one EmbeddingResponse per EmbeddingRequest.
    }
}
```

## Service registration {#service-registration}

Register the connector as a service and tag it for the registry.

```yaml
services:
  Vendor\Extension\Connection\Ai\MyAiConnector:
    tags:
      - name: 'aiassistant.connection.ai_connector'
```

## Configuration values {#configuration-values}

Provider credentials, model names, temperature values and additional provider
options should come from the AI connection record. Avoid hard-coded credentials
or project-specific defaults in the connector class.