Prism Harness

composer require particle-academy/prism-harness
php artisan migrate

npm install @particle-academy/prism-harness

pip install prism-ai-harness

use Prism\Harness\Facades\PrismHarness;
use Prism\Harness\Tools\ToolRegistry;
use Prism\Prism\Facades\Tool;

// In a service provider: make a tool available to modes that list it.
app(ToolRegistry::class)->register(
    Tool::as('lookup_order')
        ->for('Look up an order by its id.')
        ->withStringParameter('id', 'The order id')
        ->using(fn (string $id): string => json_encode(Order::findOrFail($id)->only('id', 'status')))
);

// Anywhere: resolve a session through the facade, or inject Prism\Harness\PrismHarness.
$session = PrismHarness::for($user)->session('support');

import {
  AgentRuntime,
  FileSessionStore,
  MemorySessionStore,
  ModeRegistry,
  PrismHarness,
  ToolRegistry,
  type LlmClient,
} from '@particle-academy/prism-harness';

const harness = new PrismHarness({
  drivers: {
    memory: () => new MemorySessionStore(),
    files: () => new FileSessionStore('./storage/harness'),
  },
  stores: { ephemeral: 'memory', durable: 'files' },
});

const modes = new ModeRegistry({
  default: 'support',
  modes: {
    support: { system_prompt: 'You help customers with their orders.', tools: ['lookup_order'], max_steps: 8 },
  },
});

const tools = new ToolRegistry().register({
  name: 'lookup_order',
  description: 'Look up an order by its id.',
  handle: async (args) => JSON.stringify(await orders.find(String(args.id))),
});

// Your model call. It receives the system prompt, the thread as messages, the
// offered tools, provider, model and provider options, and returns one step.
const client: LlmClient = async (request) => {
  const reply = await callYourModel(request);
  return { text: reply.text, finishReason: reply.finishReason, toolCalls: reply.toolCalls, costUsd: reply.costUsd };
};

const runtime = new AgentRuntime({ client, modes, tools });

const session = harness.for({ type: 'User', id: user.id }).session('support');

import json

from prism_harness import (
    AgentRuntime,
    FileSessionStore,
    LlmRequest,
    LlmResponse,
    MemorySessionStore,
    ModeRegistry,
    Participant,
    PrismHarness,
    ToolRegistry,
)

harness = PrismHarness(
    drivers={
        "memory": MemorySessionStore,
        "files": lambda: FileSessionStore("./storage/harness"),
    },
    stores={"ephemeral": "memory", "durable": "files"},
)

modes = ModeRegistry({
    "default": "support",
    "modes": {
        "support": {
            "system_prompt": "You help customers with their orders.",
            "tools": ["lookup_order"],
            "max_steps": 8,
        }
    },
})


class LookupOrder:
    name = "lookup_order"

    def handle(self, args):
        return json.dumps(orders.find(str(args["id"])))


tools = ToolRegistry().register(LookupOrder())


# Your model call. It receives the system prompt, the thread as messages, the
# offered tools, provider, model and provider options, and returns one step.
def client(request: LlmRequest) -> LlmResponse:
    reply = call_your_model(request)
    return LlmResponse(text=reply.text, finish_reason=reply.finish_reason, cost_usd=reply.cost_usd)


runtime = AgentRuntime(client=client, modes=modes, tools=tools)

session = harness.for_(Participant("User", user.id)).session("support")

use Prism\Harness\Models\Thread;
use Prism\Prism\Facades\Prism;

$thread = Thread::forParticipant($user, 'support');

$response = Prism::text()
    ->using('anthropic', 'claude-sonnet-4-5')
    ->withThread($thread)               // everything said so far
    ->withPrompt('And after that?')     // the turn being taken now
    ->asText();

$thread->record($response->messages);   // the full exchange, tool steps included

const response = await runtime.send(session, 'And after that?');

// runtime.send records the full exchange, including tool steps.
const messages = await session.thread().messages();

response = runtime.send(session, "And after that?")

# runtime.send records the full exchange, including tool steps.
messages = session.thread().messages()

$session = PrismHarness::for($user)->session('support');

$session->usingProvider('anthropic')->usingModel('claude-sonnet-4-5')->usingMode('support');

await session.usingProvider('anthropic');
await session.usingModel('claude-sonnet-4-5');
await session.usingMode('support');

session.using_provider("anthropic").using_model("claude-sonnet-4-5").using_mode("support")

$result = $session->send('Help with my order');

echo $result->text();
$result->runId;              // the run that produced it
$result->awaitingApproval(); // true when a tool is waiting for a person
$session->run();             // id, status, mode, provider, model, finish_reason, tool_calls

const result = await runtime.send(session, 'Help with my order');

console.log(result.text);
result.runId;            // the run that produced it
result.finishReason;     // 'awaiting_approval' when a tool is waiting for a person
result.stoppedBecause;   // why a budget stopped the run, or null
await session.run();     // id, status, mode, provider, model, finish_reason, tool_calls

result = runtime.send(session, "Help with my order")

print(result.text)
result.run_id           # the run that produced it
result.finish_reason    # "awaiting_approval" when a tool is waiting for a person
result.stopped_because  # why a budget stopped the run, or None
session.run()           # id, status, mode, provider, model, finish_reason, tool_calls

use Prism\Harness\Exceptions\StructuredSchemaViolation;
use Prism\Prism\Schema\ArraySchema;
use Prism\Prism\Schema\ObjectSchema;
use Prism\Prism\Schema\StringSchema;

$schema = new ObjectSchema('plan', 'A proposed plan', [
    new StringSchema('title', 'What the plan is called'),
    new ArraySchema('steps', 'What to do', new StringSchema('step', 'One step')),
], requiredFields: ['title', 'steps']);

try {
    $plan = $session->sendStructured('Plan the release', $schema)->structured();
} catch (StructuredSchemaViolation $violation) {
    $violation->code();      // structured_schema_violation or structured_unreadable
    $violation->problems();  // every way it missed
    $violation->document();  // what the model actually said
}

import { HarnessError } from '@particle-academy/prism-harness';

const schema = {
  name: 'plan',
  type: 'object',
  properties: { title: { type: 'string' }, steps: { type: 'array', items: { type: 'string' } } },
  required: ['title', 'steps'],
};

try {
  const plan = (await runtime.sendStructured(session, 'Plan the release', schema)).structured;
} catch (error) {
  if (error instanceof HarnessError) {
    error.code;     // structured_schema_violation or structured_unreadable
    error.problems; // every way it missed
    error.document; // what the model actually said
  }
}

from prism_harness import HarnessError

schema = {
    "name": "plan",
    "type": "object",
    "properties": {"title": {"type": "string"}, "steps": {"type": "array", "items": {"type": "string"}}},
    "required": ["title", "steps"],
}

try:
    plan = runtime.send_structured(session, "Plan the release", schema).structured
except HarnessError as error:
    error.code      # structured_schema_violation or structured_unreadable
    error.problems  # every way it missed
    error.document  # what the model actually said

foreach ($session->stream('Refactor the billing job') as $event) {
    // Prism's stream events — render them as you already do
}
// the turn is recorded and the run closed out when the stream ends

// The TypeScript runtime has no streaming turn. Use runtime.send().

# The Python runtime has no streaming turn. Use runtime.send().

use Prism\Prism\ValueObjects\ToolApprovalRequest;
use Prism\Prism\ValueObjects\ToolApprovalResponse;

$response = $session->send('Clean up the failed run');

if ($response->awaitingApproval()) {
    $response = $session->decide(array_map(
        fn (ToolApprovalRequest $pending) => new ToolApprovalResponse($pending->approvalId, approved: true),
        $response->pendingApprovals(),
    ));
}

import { recordApproval } from '@particle-academy/prism-harness';

let response = await runtime.send(session, 'Clean up the failed run');

if (response.finishReason === 'awaiting_approval') {
  for (const pending of response.pendingApprovals) {
    await recordApproval(session, pending.id, true); // or false, 'not on production'
  }
  response = await runtime.send(session, '');
}

from prism_harness import record_approval

response = runtime.send(session, "Clean up the failed run")

if response.finish_reason == "awaiting_approval":
    for pending in response.pending_approvals:
        record_approval(session, pending.id, True)  # or False, "not on production"
    response = runtime.send(session, "")

use Illuminate\Support\Facades\Event;
use Prism\Harness\Events\RunFailed;
use Prism\Harness\Events\RunFinished;
use Prism\Harness\Events\RunStarted;

Event::listen(function (RunFinished $event): void {
    $event->runId;
    $event->finishReason;
    $event->steps;
    $event->awaitingApproval;   // the one end state that needs a person to act
    $event->correlation();      // session_key, run_id, parent_run_id, root_run_id
});

import { AgentRuntime, HarnessEvents } from '@particle-academy/prism-harness';

const events = new HarnessEvents();

const stop = events.listen((event) => {
  if (event.type === 'run.finished') {
    console.log(event.runId, event.finishReason, event.steps, event.costUsd, event.toolCalls);
  }
});

const runtime = new AgentRuntime({ client, modes, tools, events });

from prism_harness import AgentRuntime, HarnessEvents, RunFinished

events = HarnessEvents()


def on_event(event):
    if isinstance(event, RunFinished):
        print(event.run_id, event.finish_reason, event.steps, event.cost_usd, event.tool_calls)


stop = events.listen(on_event)

runtime = AgentRuntime(client=client, modes=modes, tools=tools, events=events)

// config/prism-harness.php
'stores' => [
    'ephemeral' => 'redis',      // recommended in production
    'durable'   => 'database',
],

const harness = new PrismHarness({
  drivers: {
    memory: () => new MemorySessionStore(),
    files: () => new FileSessionStore('./storage/harness'),
  },
  stores: { ephemeral: 'memory', durable: 'files' },
});

harness = PrismHarness(
    drivers={
        "memory": MemorySessionStore,
        "files": lambda: FileSessionStore("./storage/harness"),
    },
    stores={"ephemeral": "memory", "durable": "files"},
)

'drivers' => [
    'redis' => [
        'driver' => 'redis',
        'connection' => env('HARNESS_REDIS_CONNECTION', 'default'),
        'durable' => true,   // an assertion about your infrastructure, made deliberately
    ],
],

const harness = new PrismHarness({
  drivers: { redis: () => durableRedisStore },
  stores: { ephemeral: 'redis', durable: 'redis' },
});

// durableRedisStore.durability() must return 'durable'.

harness = PrismHarness(
    drivers={"redis": lambda: durable_redis_store},
    stores={"ephemeral": "redis", "durable": "redis"},
)

# durable_redis_store.durability() must return "durable".

// config/prism-harness.php
'context' => [
    'keep_recent' => 20,          // a bounded window: free, deterministic
    // 'summarise_with' => 'claude-haiku-4-5-20251001',
    // 'summary_words'  => 200,
],

// No built-in compaction. The full thread reaches your client as request.messages.

# No built-in compaction. The full thread reaches your client as request.messages.

use Prism\Harness\Context\Budget\TruncateTo;
use Prism\Harness\Contracts\SummaryBudget;

$this->app->bind(SummaryBudget::class, fn () => new TruncateTo);

// SummaryBudget is PHP-only.

# SummaryBudget is PHP-only.

use Prism\Harness\Voice\VoiceExchange;
use Prism\Prism\ValueObjects\Media\Audio;

$reply = (new VoiceExchange)->exchange($session, Audio::fromBase64($base64, 'audio/webm'));

$reply->heard;   // the transcript — what the model was asked
$reply->text;    // the answer
$reply->audio;   // the answer spoken (a GeneratedAudio), or null when there was no prose
$reply->empty;   // true when nothing was heard; no turn was spent

// No voice helper. Transcribe with prism-ts, then runtime.send() the transcript.

# No voice helper. Transcribe with prism-ai-core, then runtime.send() the transcript.

// php artisan harness:doctor
//
//   stores ............................................ durable is durable
//   authorization ..... off — every registered tool is offered to every run
//   mode chat ...................... 0 tool(s), 0 subagent(s), 8 step(s)
//
//   INFO  Harness configuration is consistent.

import { SessionStoreManager, ToolAuthorizer, diagnose } from '@particle-academy/prism-harness';

const report = diagnose({
  modes,
  tools,
  stores: new SessionStoreManager({ drivers: { files: () => new FileSessionStore('./storage/harness') }, stores: { ephemeral: 'files', durable: 'files' } }),
  authorizer: new ToolAuthorizer(),
});

console.log(report.summary());
process.exitCode = report.ok ? 0 : 1;

from prism_harness import FileSessionStore, SessionStoreManager, ToolAuthorizer, diagnose

report = diagnose(
    modes=modes,
    tools=tools,
    stores=SessionStoreManager(
        drivers={"files": lambda: FileSessionStore("./storage/harness")},
        stores={"ephemeral": "files", "durable": "files"},
    ),
    authorizer=ToolAuthorizer(),
)

print(report.summary())