Download the PHP package blundergoat/strands-php-client without Composer

Strands PHP Client

PHP client library for consuming Strands AI agents via HTTP. Invoke agents, stream responses via SSE, manage sessions -without running an agentic loop in PHP.

Works with any PHP framework -Laravel, Symfony, Slim, or vanilla PHP.

"Your PHP app doesn't need to become an AI platform. It just needs to talk to one."

Why This Exists

Strands Agents is an open-source Python SDK from AWS for building autonomous AI agents. It handles the hard parts -reasoning loops, tool orchestration, model routing (Claude, Nova, GPT, Ollama) -and exposes agents over HTTP.

But most web applications aren't written in Python. If your product runs on Symfony or any PHP framework, you need a way to consume those agents without reimplementing the agentic loop in PHP. That's what this library does.

Your Python agents handle the AI. Your PHP app handles the product. This client is the bridge.

For a full walkthrough with real-world examples, see the Usage Guide.

Quick Start

Symfony (with auto-detection)

If symfony/http-client is installed, the transport is auto-detected -just create a client and go:

For Symfony projects, the bundle adds YAML config and autowiring -see Symfony Bundle Integration below.

PSR-18 (Guzzle, Buzz, etc.)

Any PSR-18 client works via PsrHttpTransport (invoke only, no streaming):

Features

Rich Input (AgentInput)

Send multi-modal content to agents - images, documents, S3 locations - alongside your text message:

When no content blocks are attached, AgentInput::text() serializes as a plain string - fully backward compatible. See docs/rich-input.md for the full API reference.

Invoke (blocking)

Stream (SSE)

Real-time token-by-token streaming via Server-Sent Events. Requires symfony/http-client.

stream() returns a StreamResult with the accumulated text, session info, and usage stats:

Note: SSE streaming requires symfony/http-client via SymfonyHttpTransport. PSR-18 clients only support invoke() -this is a limitation of the PSR-18 spec, not this library.

Custom Endpoints (postJson / streamSse)

For agent endpoints with custom request/response schemas, use postJson() and streamSse(). These bypass the standard invoke/stream contract and work with arbitrary payloads:

Both methods accept optional timeout: overrides and stream callbacks can return false to cancel.

Error Handling

AgentErrorException carries the full response body for debugging structured errors:

Sessions & Context

Pass sessionId for multi-turn conversations -the server manages all state:

Use the immutable AgentContext builder to pass application context:

Retries, Timeouts & Logging

Retries apply to invoke() and postJson(). Streaming requests are not retried. The Symfony bundle injects Monolog automatically.

Transport

Auto-detection: If no transport is passed to the constructor, the client checks for symfony/http-client and uses SymfonyHttpTransport automatically. If Symfony isn't available, it throws with guidance to pass a PsrHttpTransport.

Timeout: SymfonyHttpTransport uses the timeout from StrandsConfig (default 120s). connectTimeout (default 10s) controls how long to wait for the initial TCP connection -separate from the read timeout so a down server fails fast without affecting slow LLM generation. For PsrHttpTransport, configure timeout on your PSR-18 client directly (e.g. new GuzzleHttp\Client(['timeout' => 120])).

Auth Strategies

For details on writing custom auth strategies, see docs/auth.md.

Symfony Bundle Integration

The Symfony bundle adds YAML config, autowired named agents, and automatic PSR-3 logging:

Bundle registration:

For the full configuration reference, see docs/symfony-config.md.

Laravel Integration

The Laravel service provider adds config-driven agent registration, dependency injection, and a facade:

Inject by type-hint or resolve named agents:

Use the facade for quick calls:

Auto-discovery is configured via composer.json -no manual provider registration needed.

For the full configuration reference, see docs/laravel-config.md.

Requirements

• PHP 8.2+
• One of:
  • symfony/http-client ^6.4 or ^7.0 -for full support (invoke + streaming), auto-detected
  • Any PSR-18 HTTP client (e.g. guzzlehttp/guzzle) -for invoke only, via PsrHttpTransport

Installation

Laravel projects:

Symfony projects:

PSR-18 / Guzzle projects:

Want streaming too?

Documentation

Testing

All tests use mocked HTTP responses -no Docker, no API keys, no network calls.

Related

Maintained by Matthew Hansen.