Skip to content

Tell Harness: Stateless PHP Run

Overview

The smallest Tell SDK integration is a stateless, request/response call. It is appropriate for a queue worker, controller action, or command that does not intend to retain a conversation. No .tell directory is created.

This example uses a new temporary project, so it cannot affect the repository from which it is run. It needs a normal Tell connection and credential.

Example

<?php
require 'examples/boot.php';
require_once dirname(__DIR__).'/Support.php';

use Cognesy\Tell\Composition\Standalone\StandaloneTellBuilder;
use Cognesy\Tell\Data\TellRequest;

$project = TellHarnessExample::project();

try {
    $result = StandaloneTellBuilder::in($project)->build()->run(
        TellRequest::prompt('In one sentence, explain why stateless jobs are useful.'),
    );

    echo "=== Tell Result ===\n";
    echo 'Completed: '.($result->isCompleted() ? 'yes' : 'no')."\n";
    echo 'Published: '.($result->isPublished() ? 'yes' : 'no')."\n";
    echo 'Response: '.$result->text()."\n";

    assert($result->isCompleted(), 'Expected a completed Tell result.');
    assert(
        ! $result->isPublished(),
        'Stateless Tell execution must not publish history.',
    );
    assert(
        ! is_dir($project.'/.tell'),
        'Stateless Tell execution must not create a workspace.',
    );
} finally {
    TellHarnessExample::remove($project);
}
?>

Key Points

  • StandaloneTellBuilder::in()->build() binds a reusable Tell instance to a working directory.
  • TellRequest::prompt() is immutable; add model, connection, tools, or a step budget only when the caller needs them.
  • A TellResult exposes final text, execution status, usage, warnings, and durable/transient state without parsing CLI output.