feature #509 [Agent] Add getName() method to AgentInterface (OskarStark)

This PR was squashed before being merged into the main branch.

Discussion
----------

[Agent] Add `getName()` method to `AgentInterface`

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | yes
| Docs?         | no
| Issues        | Follows #19 (comment) and #19 (comment)
| License       | MIT

shall we make it non-nullable an return a uuid if not provided or do you want to make it real mandatory? `@chr`-hertel

Commits
-------

bb1ef23 [Agent] Add `getName()` method to `AgentInterface`

Author: OskarStark

src/agent/src/Agent.php

@@ -48,6 +48,7 @@ public function __construct(
         private Model $model,
         iterable $inputProcessors = [],
         iterable $outputProcessors = [],
+        private string $name = 'agent',
         private LoggerInterface $logger = new NullLogger(),
     ) {
         $this->inputProcessors = $this->initializeProcessors($inputProcessors, InputProcessorInterface::class);
@@ -59,6 +60,11 @@ public function getModel(): Model
         return $this->model;
     }
 
+    public function getName(): string
+    {
+        return $this->name;
+    }
+
     /**
      * @param array<string, mixed> $options
      *

src/agent/src/AgentInterface.php

@@ -26,4 +26,9 @@ interface AgentInterface
      * @throws ExceptionInterface When the agent encounters an error (e.g., unsupported model capabilities, invalid arguments, network failures, or processor errors)
      */
     public function call(MessageBag $messages, array $options = []): ResultInterface;
+
+    /**
+     * Get the agent's name, which can be used for debugging or multi-agent configuration.
+     */
+    public function getName(): string;
 }

src/agent/src/MockAgent.php

@@ -46,8 +46,10 @@ final class MockAgent implements AgentInterface
     /**
      * @param array<string, string|MockResponse|\Closure> $responses Predefined responses for specific inputs
      */
-    public function __construct(array $responses = [])
-    {
+    public function __construct(
+        array $responses = [],
+        private string $name = 'mock',
+    ) {
         $this->responses = $responses;
     }
 
@@ -241,4 +243,9 @@ public function reset(): self
 
         return $this;
     }
+
+    public function getName(): string
+    {
+        return $this->name;
+    }
 }

src/agent/tests/AgentTest.php

@@ -307,7 +307,7 @@ public function getResponse(): HttpResponseInterface
         $this->expectException(InvalidArgumentException::class);
         $this->expectExceptionMessage('Client error');
 
-        $agent = new Agent($platform, $model, [], [], $logger);
+        $agent = new Agent($platform, $model, logger: $logger);
         $agent->call($messages);
     }
 
@@ -405,4 +405,25 @@ public function testConstructorAcceptsTraversableProcessors()
 
         $this->assertInstanceOf(AgentInterface::class, $agent);
     }
+
+    public function testGetNameReturnsDefaultName()
+    {
+        $platform = $this->createMock(PlatformInterface::class);
+        $model = $this->createMock(Model::class);
+
+        $agent = new Agent($platform, $model);
+
+        $this->assertSame('agent', $agent->getName());
+    }
+
+    public function testGetNameReturnsProvidedName()
+    {
+        $platform = $this->createMock(PlatformInterface::class);
+        $model = $this->createMock(Model::class);
+        $name = 'test';
+
+        $agent = new Agent($platform, $model, [], [], $name);
+
+        $this->assertSame($name, $agent->getName());
+    }
 }

src/agent/tests/MockAgentTest.php

@@ -410,4 +410,18 @@ public function testCallableTrackingInCalls()
         $this->assertSame('tracked', $calls[0]['input']);
         $this->assertSame('Tracked: tracked', $calls[0]['response']);
     }
+
+    public function testGetNameReturnsDefaultName()
+    {
+        $agent = new MockAgent();
+
+        $this->assertSame('mock', $agent->getName());
+    }
+
+    public function testGetNameReturnsProvidedName()
+    {
+        $agent = new MockAgent(name: 'custom');
+
+        $this->assertSame('custom', $agent->getName());
+    }
 }