Your first agent¶

<?php

declare(strict_types=1);

use A2A\Server\AgentExecution\AgentExecutor;
use A2A\Server\AgentExecution\RequestContext;
use A2A\Server\Events\EventQueue;
use A2A\Server\Tasks\TaskUpdater;
use A2A\Types\Part;
use A2A\Types\Task;
use A2A\Types\TaskState;
use A2A\Types\TaskStatus;

/**
 * The hello-world agent, ported line for line from the A2A Python SDK's
 * samples/hello_world_agent.py (SampleAgentExecutor).
 */
final class HelloExecutor implements AgentExecutor
{
    public function execute(RequestContext $context, EventQueue $eventQueue): void
    {
        $userMessage = $context->message();
        $taskId = $context->taskId();
        $contextId = $context->contextId();
        if ($userMessage === null || $taskId === null || $contextId === null) {
            return;
        }

        $eventQueue->enqueueEvent(new Task([
            'id' => $taskId,
            'context_id' => $contextId,
            'status' => new TaskStatus(['state' => TaskState::TASK_STATE_SUBMITTED]),
            'history' => [$userMessage],
        ]));

        $updater = new TaskUpdater($eventQueue, $taskId, $contextId);
        $updater->startWork($updater->newAgentMessage([new Part(['text' => 'Processing your question...'])]));

        $reply = $this->parseInput($context->getUserInput());
        sleep(1);

        // Python tracks running tasks in a set; a PHP request can be
        // cancelled from another process, so ask the context instead.
        if ($context->isCancelled()) {
            return;
        }

        $updater->addArtifact([new Part(['text' => $reply])], name: 'response', lastChunk: true);
        $updater->complete();
    }

    public function cancel(RequestContext $context, EventQueue $eventQueue): void
    {
        (new TaskUpdater($eventQueue, (string) $context->taskId(), (string) $context->contextId()))->cancel();
    }

    private function parseInput(string $query): string
    {
        if ($query === '') {
            return 'Hello! Please provide a message for me to respond to.';
        }
        $q = strtolower($query);
        if (str_contains($q, 'hello') || str_contains($q, 'hi')) {
            return 'Hello World! Nice to meet you!';
        }
        if (str_contains($q, 'how are you')) {
            return "I'm doing great! Thanks for asking. How can I help you today?";
        }
        if (str_contains($q, 'goodbye') || str_contains($q, 'bye')) {
            return 'Goodbye! Have a wonderful day!';
        }

        return "Hello World! You said: '{$query}'. Thanks for your message!";
    }
}

// What `php artisan a2a:make-executor Hello` generates, with a reply filled in.
final class HelloExecutor implements AgentExecutor
{
    public function execute(RequestContext $context, EventQueue $eventQueue): void
    {
        $message = $context->message();
        if ($context->currentTask() === null && $message !== null) {
            $eventQueue->enqueueEvent(ProtoHelpers::newTaskFromUserMessage($message));
        }

        $updater = new TaskUpdater($eventQueue, (string) $context->taskId(), (string) $context->contextId());
        $updater->startWork();
        $updater->addArtifact([new Part(['text' => 'Hello, ' . $context->getUserInput()])], name: 'response', lastChunk: true);
        $updater->complete();
    }

    public function cancel(RequestContext $context, EventQueue $eventQueue): void
    {
        (new TaskUpdater($eventQueue, (string) $context->taskId(), (string) $context->contextId()))->cancel();
    }
}

$agentCard = new AgentCard([
    'name' => 'Sample Agent',
    'description' => 'A sample agent to test the stream functionality.',
    'provider' => new AgentProvider(['organization' => 'A2A Samples', 'url' => 'https://example.com']),
    'version' => '1.0.0',
    'capabilities' => new AgentCapabilities(['streaming' => true, 'push_notifications' => false]),
    'default_input_modes' => ['text'],
    'default_output_modes' => ['text', 'task-status'],
    'skills' => [new AgentSkill([
        'id' => 'sample_agent',
        'name' => 'Sample Agent',
        'description' => 'Say hi.',
        'tags' => ['sample'],
        'examples' => ['hi'],
        'input_modes' => ['text'],
        'output_modes' => ['text', 'task-status'],
    ])],
    'supported_interfaces' => [
        new AgentInterface(['protocol_binding' => 'JSONRPC', 'protocol_version' => '1.0', 'url' => $baseUrl . '/a2a/jsonrpc']),
        new AgentInterface(['protocol_binding' => 'HTTP+JSON', 'protocol_version' => '1.0', 'url' => $baseUrl . '/a2a/rest']),
    ],
]);

final class HelloAgentCard implements AgentCardProvider
{
    public function agentCard(): AgentCard
    {
        // No supported_interfaces: Route::a2a() fills them in from your routes.
        return new AgentCard([
            'name' => 'Hello Agent',
            'description' => 'Says hello.',
            'version' => '1.0.0',
            'capabilities' => new AgentCapabilities(['streaming' => true]),
            'default_input_modes' => ['text/plain'],
            'default_output_modes' => ['text/plain'],
            'skills' => [new AgentSkill([
                'id' => 'hello',
                'name' => 'Hello',
                'description' => 'Say hi.',
                'tags' => ['demo'],
            ])],
        ]);
    }
}

$pdo = new PDO('sqlite:' . (getenv('A2A_DB') ?: sys_get_temp_dir() . '/a2a-php-hello-world.sqlite'));
$handler = new DefaultRequestHandler(
    agentExecutor: new HelloExecutor(),
    taskStore: new PdoTaskStore($pdo),
    agentCard: $agentCard,
    queueManager: new PdoQueueManager($pdo),
);

$router = Routes::router($handler, $agentCard, jsonRpcPath: '/a2a/jsonrpc', restPrefix: '/a2a/rest');
(new ResponseEmitter($handler))->emit($router->handle($request));

Route::a2a('/a2a', agentCard: HelloAgentCard::class, executor: HelloExecutor::class);