Skip to content

agent-api-contracts.md

Latest commit

 

History

History
101 lines (73 loc) · 2.89 KB

agent-api-contracts.md

File metadata and controls

101 lines (73 loc) · 2.89 KB

EasyLibrary Agent API Contracts

This document freezes the intended public integration shape for the stable candidate.

Public namespaces

Plugins should import only these Agent namespaces:

imperazim\agent\api\*
imperazim\agent\constant\*
imperazim\agent\event\*

The old monolithic imperazim\agent\AgentAPI was removed before 1.0. New integrations must use the domain APIs under imperazim\agent\api.

Runtime rule

Always guard network-dependent behavior:

use imperazim\agent\api\AgentRuntimeAPI;

if(!AgentRuntimeAPI::isAvailable()){
    // local fallback
    return;
}

When agent.enabled=false, the Agent Bridge is not loaded. In that mode:

/easyagent is not registered
heartbeat and PubSub polling do not run
Agent placeholders are not registered
AgentRuntimeAPI::isAvailable() returns false

Response conventions

The APIs intentionally return simple arrays or booleans because the transport is JSON-first.

Recommended checks:

$response = AgentFlagsAPI::set('double_xp', true, 300, 'Test');

if(($response['ok'] ?? false) !== true){
    $error = (string) ($response['error'] ?? 'unknown error');
}

For request/response flows, keep the returned ID:

$request = AgentRpcAPI::toServer('lumen-vps', AgentRpcMethods::SERVER_STATUS);
$requestId = (int) ($request['request_id'] ?? 0);

For accepted async-ish compute calls:

$task = AgentComputeAPI::runAsync(AgentComputeMethods::REGION_INTERSECTS, $payload);
$taskId = (int) ($task['task_id'] ?? 0);

Public APIs by domain

AgentRuntimeAPI          availability, health, reports, recent runtime state
AgentPubSubAPI           PubSub and target-aware network events
AgentRegistryAPI         server registry, groups, types, tags and target resolution
AgentDeliveryAPI         ACK/result/retry/recent diagnostics for reliable events
AgentRpcAPI              request/response calls to server/group/type/tag targets
AgentKVAPI               namespaced KV and atomic operations
AgentFlagsAPI            network flags stored in reserved KV namespace
AgentLocksAPI            lightweight owner-aware locks
AgentServerStateAPI      maintenance/draining/admin state
AgentCommandDispatchAPI  protected remote command automation
AgentPlaceholderAPI      bridge metadata helpers for placeholder integration
AgentComputeAPI          safe allowlisted coprocessor calls

Command surface

/easyagent is diagnostic/admin/debug tooling. Production data flow should use the APIs and events, not commands.

Constants

Use constants for standard protocol values:

AgentChannels::NETWORK_NOTICE
AgentTargetTypes::SERVER
AgentRpcMethods::SERVER_STATUS
AgentNetworkFlags::DOUBLE_XP
AgentComputeMethods::REGION_INTERSECTS
AgentComputeStates::COMPLETE

PubSub still supports custom plugin channels. Compute does not: compute methods must be in AgentComputeMethods and must also be allowed by the Agent Go config.