Download the PHP package helgesverre/pagent without Composer

Pagent

A fluent LLM agent framework for PHP, inspired by Pest.

Pagent provides a compact API for building stateful AI agents with tool calling, streaming, multiple model providers, safety guards, evaluation, and multi-agent workflows.

Features

• Fluent, named agent configuration
• Anthropic, OpenAI, OpenCode Zen/Go, Ollama, and deterministic mock providers
• Automatic tool schemas generated from typed PHP closures
• Reusable class-based tools for files, search, shell commands, PDFs, and HTTP
• Streaming responses and Server-Sent Events support
• File and SQLite conversation persistence
• Guards, middleware, lifecycle events, and fallbacks
• Pipelines, handoffs, delegation, and multi-agent workflows
• Dataset-based evaluation with built-in and custom metrics
• Token and cost tracking
• OpenTelemetry tracing for agents, providers, tools, guards, and workflows
• Model Context Protocol (MCP) client support over stdio and HTTP/SSE

Requirements

• PHP 8.4.1 or later
• Composer 2
• The PHP cURL extension
• A provider API key, unless you use Ollama or the mock provider

Installation

The core package intentionally has a small runtime footprint. Telemetry exporters, the Bash tool, full-text search, and JSON-schema evaluation are optional; Composer lists their packages under suggest. Install only the integrations your application uses (for example, composer require open-telemetry/sdk for telemetry or composer require symfony/process for Bash).

Set the environment variable for the provider you plan to use:

For local development in this repository, copy the supplied environment file and add your credentials:

Quick start

Composer loads Pagent's helper functions automatically. Define a named agent and send it a prompt:

agent() always returns and immediately registers an Agent; it never depends on builder destruction. Use getAgent() when a missing name must remain missing, or defineAgent() when you want an explicit configuration boundary. build() remains a harmless compatibility no-op on Agent.

Named agents are registered for reuse, so application code can retrieve the same configured agent later:

See the vanilla PHP guide for a complete application layout, or choose one of the framework integration guides.

Providers

Use a provider name for standard configuration:

Pass configuration options with the provider name or supply a provider instance when you need more control:

Custom adapters should implement IdentifiedProvider and return a Pagent\ProviderCapabilities value instead of relying on their class name. Implement StreamingProvider when the adapter can produce incremental StreamResponses. This makes provider identity, tools, system-message support, and streaming explicit for both built-ins and third-party adapters.

Provider-specific request options can be passed to prompt():

Retry transient API and connection failures with the capability-preserving decorator factory. Completed requests and stream establishment failures are retried; once a StreamResponse has been returned, consumption failures are never replayed, so partially emitted output cannot be duplicated:

Framework-defined failures share one catch boundary while retaining their standard PHP parents (RuntimeException, InvalidArgumentException, and so on):

Exceptions thrown by application callbacks or third-party dependencies are not rewritten and may propagate unchanged.

OpenCode supports chat-completions, Responses, and Messages model protocols. The provider defaults to chat-completions; choose a protocol globally, per model, or per prompt when the selected OpenCode model requires it. The default model ID depends on the selected gateway:

For local inference setup and model selection, see the Ollama integration guide.

Tool calling

Pagent derives a JSON schema from a closure's parameter names, type declarations, and default values. The agent can then select and execute the tool during a model conversation.

For reusable tools, implement a class or use the included tools:

Pagent includes DataExtract, FileRead, FileWrite, Glob, Grep, PdfReader, and WebFetch; Bash and SearchTool additionally require their suggested Composer packages. Scope tools such as file and shell tools to the narrowest directory and permissions your application requires.

Custom and MCP tools share one provider-neutral Pagent\Contracts\Tool contract (getName(), getDescription(), getInputSchema(), and execute()). Pagent serializes that JSON Schema at the provider boundary, so tool implementations do not contain Anthropic- or OpenAI-specific wire formats.

Runnable examples: closure tools and MCP-provided tools.

Streaming

Use streamTo() for a callback-based interface:

Use stream() when you need to inspect start, text, tool, and end chunks or collect the final response yourself:

Registered tools work in streaming mode too. Pagent assembles argument deltas, executes each completed call, and continues streaming the follow-up response. Use ['tool_mode' => 'manual'] to inspect normalized calls with $stream->getToolCalls() without executing them, then pass externally produced results to $assistant->continueToolCalls($stream, $resultsByCallId). Use $assistant->discardToolCalls($stream) to abandon the pending turn, or tool_mode => 'none' to omit tool schemas for that request.

Ordinary streams are incremental. Pagent intentionally quarantines a stream before calling your callback when it has an output policy that needs the complete response (such as PII/content guards), a legacy two-argument guard, or response-transforming middleware. This prevents unsafe prefixes from being delivered; use phase-aware incremental OutputGuards only when their policy is safe across chunk boundaries.

See the streaming guide for SSE endpoints, client code, error handling, and streaming tool calls. The repository also contains a basic streaming example and a complete SSE endpoint.

Conversation memory

Agents retain context in memory during a process. Add a storage adapter and session identifier to continue conversations across requests or application restarts:

File and SQLite adapters are included. The memory and persistence guide covers session isolation, custom adapters, context windows, and production usage. See also the runnable file, SQLite, and multi-session examples.

Changing sessionId() clears the in-memory conversation and loads only that session on the next turn. Failed turns are rolled back, so retries do not replay a partial user message.

Guards and middleware

Guards validate agent interactions and can return a controlled fallback when a rule is violated. PromptInjectionGuard is an input guard and runs before any provider or tool call; PII and content guards are output guards:

Middleware wraps requests and responses for cross-cutting behavior:

Read the middleware, and events guides for custom implementations and lifecycle hooks. Runnable demonstrations are available for guards and middleware.

Multi-agent workflows

Pipelines pass one agent's response to the next agent:

Pagent also supports named workflow steps, transforms, handoffs, and supervised delegation. See the orchestration and workflows guide and the multi-agent, simple chain, and named pipeline examples.

Testing and evaluation

The mock provider makes application tests deterministic and requires no network access:

The evaluation framework runs datasets against an agent and scores responses with built-in or custom metrics:

Each dataset row uses a fresh conversation by default and the registered agent definition is never mutated. For datasets that intentionally model a multi-turn conversation, opt in with ->stateful().

See the evaluation example, the progressive evaluation example, and the evaluation tutorial for datasets, metrics, and HTML, Markdown, and JSON reports.

Usage tracking and observability

Enable per-agent token and cost tracking:

For tracing during development, send OpenTelemetry spans to the console:

Jaeger, Zipkin, and generic OTLP exporters are supported. The observability guide documents configuration, captured attributes, sampling, and production backends. Additional runnable examples cover console traces, Jaeger, workflow traces, and custom OTLP configuration.

Model Context Protocol

Pagent can discover tools from MCP servers, adapt them to Pagent tools, and attach them to an agent. Both local stdio servers and remote HTTP/SSE servers are supported.

See the MCP integration guide for connection lifecycle, tool discovery, transport configuration, error handling, and security guidance. The MCP client example demonstrates both transports.

Examples

The examples directory contains runnable programs organized by feature:

Run an example from the repository root after installing dependencies:

Examples using OpenAI or Anthropic require the corresponding API key. Mock examples run without credentials. See the examples index for prerequisites and notes.

Documentation

Feature guides

• Documentation index
• Streaming
• Memory and persistence
• Guards
• Middleware
• Events
• Orchestration and workflows
• Observability
• MCP integration
• Ollama integration

Framework integration

• Vanilla PHP
• Laravel
• Symfony
• Slim

For a longer, structured introduction, read the complete Pagent guide or choose a learning path in the guide index.

Development

Install dependencies and run the standard checks:

If just is installed, the repository also provides shortcuts:

composer test excludes live-provider and external-service tests. Run live provider coverage explicitly with credentials in .env:

See CONTRIBUTING.md for the development workflow and pull request guidelines. Security issues should be reported according to SECURITY.md.

Changelog

See CHANGELOG.md for release history and notable changes.

License

Pagent is open-source software licensed under the MIT license.

Credits

Created by Helge Sverre. The fluent API is inspired by Pest.