Agent SDK

Embed KosmoKrator's headless agent runtime directly in PHP applications. The SDK lives in the main KosmoKrator package under Kosmokrator\Sdk and uses the same AgentLoop::runHeadless() path as kosmokrator -p.

Quick Start

composer require opencompany/kosmokrator

<?php

require __DIR__.'/vendor/autoload.php';

use Kosmokrator\Sdk\AgentBuilder;

$result = AgentBuilder::create()
    ->forProject('/path/to/project')
    ->withMode('edit')
    ->withPermissionMode('guardian')
    ->withMaxTurns(20)
    ->withTimeout(300)
    ->build()
    ->collect('Fix the failing tests');

echo $result->text;

The SDK is not a separate engine. It builds a normal headless KosmoKrator session, wires the normal tools, permissions, Lua runtime, integrations, MCP runtime, session storage, context management, and subagents, then returns structured PHP results.

Headless CLI Parity

Results

$result = $agent->collect('Explain src/Agent/AgentLoop.php');

$result->text;           // final assistant response
$result->sessionId;      // persisted session id, unless disabled
$result->tokensIn;
$result->tokensOut;
$result->toolCalls;
$result->elapsedSeconds;
$result->success;
$result->exitCode;
$result->events;         // typed SDK events

Long-lived workers should call $agent->close() when they are done with an agent instance. Runs clean up shell sessions and MCP clients automatically, but explicit close is useful after direct $agent->mcp() or $agent->integrations() helper usage.

Streaming And Callbacks

stream() returns the event sequence for a run. For live delivery to a WebSocket, queue worker, or custom UI, use CallbackRenderer; callbacks are invoked while the underlying headless run is executing.

use Kosmokrator\Sdk\AgentBuilder;
use Kosmokrator\Sdk\Renderer\CallbackRenderer;

$agent = AgentBuilder::create()
    ->forProject($repo)
    ->withRenderer(new CallbackRenderer(
        onText: fn (string $text) => $websocket->send($text),
        onToolCall: fn (string $tool, array $args) => logger()->info('tool', compact('tool', 'args')),
        onToolResult: fn (string $tool, string $output, bool $success) => null,
    ))
    ->build();

$result = $agent->collect('Refactor the auth module');

Sessions

$first = AgentBuilder::create()
    ->forProject($repo)
    ->build()
    ->collect('What does the billing service do?');

$followup = AgentBuilder::create()
    ->forProject($repo)
    ->resumeSession($first->sessionId)
    ->build()
    ->collect('Now add tests for the edge cases');

$ephemeral = AgentBuilder::create()
    ->forProject($repo)
    ->withoutSessionPersistence()
    ->build()
    ->collect('Summarize this repository');

Headless Configuration

SDK users can configure credentials and settings programmatically. These helpers write to the same project/global stores used by providers:*, integrations:*, mcp:*, and secrets:*.

use Kosmokrator\Sdk\Config\ProviderConfigurator;
use Kosmokrator\Sdk\Config\IntegrationConfigurator;
use Kosmokrator\Sdk\Config\McpConfigurator;

ProviderConfigurator::forProject($repo)
    ->configure('openai', apiKey: getenv('OPENAI_API_KEY') ?: null, model: 'gpt-5.4-mini');

IntegrationConfigurator::forProject($repo)
    ->configure('plane', account: 'work', credentials: [
        'api_key' => getenv('PLANE_API_KEY') ?: '',
        'workspace_slug' => 'acme',
    ], permissions: [
        'read' => 'allow',
        'write' => 'ask',
    ]);

McpConfigurator::forProject($repo)
    ->addStdioServer('github', 'github-mcp-server',
        env: ['GITHUB_TOKEN' => '@secret:mcp.github.env.GITHUB_TOKEN'],
        permissions: ['read' => 'allow', 'write' => 'ask'],
        trust: true,
    )
    ->setSecret('github', 'env.GITHUB_TOKEN', getenv('GITHUB_TOKEN') ?: '');

Lua, Integrations, And MCP

The SDK exposes the same runtime surfaces as the headless integration and MCP CLIs. Integration permissions and MCP trust/read/write policy are respected by default. Pass force: true only for trusted automation that should bypass those policies.

$agent = AgentBuilder::create()
    ->forProject($repo)
    ->build();

// Direct integration call
$issues = $agent->integrations()->call(
    'plane.list_issues',
    ['workspace_slug' => 'acme'],
    account: 'work',
);

// Integration Lua
$lua = $agent->integrations()->lua(
    'return app.integrations.plane.work.list_issues({workspace_slug="acme"})'
);

// Direct MCP call
$repos = $agent->mcp()->call('github.search_repositories', [
    'query' => 'kosmokrator',
]);

// Runtime-only MCP overlay, not written to .mcp.json
$agent = AgentBuilder::create()
    ->forProject($repo)
    ->withMcpServer('fake', command: 'php', args: ['tests/fixtures/mcp/fake_stdio_server.php'])
    ->build();

Permissions

$agent = AgentBuilder::create()
    ->forProject($repo)
    ->withPermissionMode('guardian')
    ->withPermissionCallback(function (string $tool, array $args): string {
        return str_starts_with($tool, 'file_read') ? 'allow' : 'deny';
    })
    ->build();

Valid callback results are allow, deny, and always. Boolean callbacks are also accepted: true maps to allow, false maps to deny.

Anthropic Agent SDK Comparison

AgentBuilder Reference

AgentBuilder::create(?string $basePath = null)
AgentBuilder::fromContainer(Container $container)

->forProject(string $cwd)
->fromKosmokratorConfig()
->withConfig(array $config)
->withConfigFile(string $path)
->withProvider(string $provider)
->withModel(string $model)
->withApiKey(string $key)
->withBaseUrl(string $url)
->withMode(string|AgentMode $mode)
->withPermissionMode(string|PermissionMode $mode)
->withYolo()
->withMaxTurns(int $turns)
->withTimeout(int $seconds)
->withSystemPrompt(string $prompt)
->appendSystemPrompt(string $suffix)
->resumeSession(string $sessionId)
->resumeLatestSession()
->withoutSessionPersistence()
->withOutputFormat(OutputFormat|string $format)
->withRenderer(RendererInterface $renderer)
->withPermissionCallback(Closure $callback)
->withMcpServer(...)
->build()

$agent->collect(string $prompt): AgentResult
$agent->stream(string $prompt): Generator
$agent->conversation(): AgentConversation
$agent->integrations(): IntegrationClient
$agent->mcp(): McpClient
$agent->cancel(string $reason = 'SDK run cancelled'): void
$agent->close(): void

Stability

The stable public API is Kosmokrator\Sdk\*, Kosmokrator\Sdk\Event\*, Kosmokrator\Sdk\Renderer\*, and Kosmokrator\Sdk\Config\*. Other namespaces are implementation details unless they are documented on this page.