Repository navigation
Embedding
var agent = try pa.Agent.init(allocator, io, "./package", "entry", .{});
defer agent.deinit();
const output = try agent.call(allocator, input, config, &.{.{
.name = "peer",
.agent = &peer,
.config = peer_config,
}});
defer allocator.free(output);The initialization allocator backs the Image and HTTP client and must be
thread-safe. The call allocator must support concurrent batch Eval. Agents may
be called concurrently, but all calls must finish before deinit.
agent check <source> <entry>
agent call
check compiles and resolves an Image. call reads one protocol request from
stdin and writes newline-delimited protocol frames to stdout.
const agent = yield* Agent.make({
sourceDir: "./package",
entryModule: "entry",
cwd: "/srv/agent",
environment: { HOME: "/srv/agent" },
});
const output = yield* agent.call(input, config, [{
name: "peer",
agent: peer,
config: peerConfig,
}]);
const events = agent.stream(input, config);
yield* events.pipe(Stream.runForEach((event) =>
Effect.sync(() => {
if (event.type === "emit") consume(event.output);
if (event.type === "append") append(event.output);
if (event.type === "log") recordStage(event.stage);
if (event.type === "result") complete(event.output);
})
));Provide the Effect ChildProcessSpawner for the host runtime around the call;
for example, Node-compatible runtimes can provide NodeServices.layer from
@effect/platform-node.
Each call starts one scoped agent call child process. cwd sets its working
directory. Supplying environment replaces the inherited environment exactly;
omitting it inherits the SDK process environment. Scope interruption terminates
the process group and forces it down after one second. Choose the wall-clock
timeout in the surrounding Effect program.
The CLI protocol is version 1. It carries an emission flag, source directories,
entry modules, limits, flat Import records, and padded-base64 input/config
bytes. The root Agent executes the request; Import records refer to other Agent
records by index. Responses are newline-delimited JSON frames containing
padded-base64 message and append bytes, operator diagnostics, and exactly one padded-base64 result or named error. The SDK preserves the most recent bounded Lua traceback in AgentError.detail; never surface it to an untrusted user.
A granted Import is accessed with require("peer").member(arg1, arg2). Its member implementation receives its private opaque config first, then those native Lua arguments; the caller cannot pass or replace the private config. The byte-oriented module __call remains the external Agent boundary. Trusted package code can inspect grant names with require("pa").imports().
Trusted package code may call pa.emit(bytes) to start a message or pa.emit(bytes, "append") to extend its editable tail. Emissions are synchronous and ordered across root, Import, nested, and Eval runtimes. They are delivered when Agent.stream enables them and are otherwise discarded. pa.log(stage) emits a bounded alphanumeric stage name as an operator-only diagnostic. Portable Agents does not interpret emitted bytes or label model reasoning. The CLI reads one complete request envelope from stdin.
pa.http(origin, method, path, body?, headers?, maximum_bytes?, on_chunk?) retains its buffered (status, body) result without on_chunk. With a positive maximum_bytes and callback, it invokes on_chunk(status, bytes) for each bounded response chunk and returns status after EOF. Cancellation interrupts reads; the byte limit applies to buffered and streamed responses.
The default build links Lua statically. -Dsystem-lua=true uses a dynamic ABI-
compatible Lua 5.5 installation. The OS loader must be able to find the ABI-compatible dynamic Lua library before PA starts. PA compiles package-local pure Lua modules into its Image and resolves native modules from the opened source directory's absolute native/ path (.so on Unix, .dll on Windows). It clears package.path and restricts package.cpath to that one pattern; Lua search-path environment variables cannot add modules. PA Import members transfer positional native Lua values, and pa.imports() lists the names granted to the current call.