docs/sdk/go/agent-client.mdx
AgentClient is the low-level raw transport for talking to agentd through a running sandbox's relay socket. Most applications should use Sandbox, Exec, and filesystem helpers instead. Reach for this API when you are building protocol-level tools or higher-level SDK helpers.
All request and response bodies are raw CBOR bytes. The SDK handles framing and correlation ids, but it does not encode or decode the CBOR message body for you: decode it with a library such as fxamacker/cbor. The raw body is the full CBOR-encoded protocol Message body (v, t, p), not just the inner payload.
import (
"context"
"github.com/fxamacker/cbor/v2"
m "github.com/superradcompany/microsandbox/sdk/go"
)
ctx := context.Background()
client, err := m.ConnectAgentSandbox(ctx, "dev") // 1. connect
if err != nil {
return err
}
defer client.Close()
body, err := cbor.Marshal(map[string]any{ // 2. build a CBOR Message
"v": 1,
"t": "core.fs.request",
"p": fsRequestBytes,
})
if err != nil {
return err
}
frame, err := client.Request(ctx, m.FlagSessionStart, body) // 3. request / response
if err != nil {
return err
}
_ = frame.Body
const FlagTerminal uint8 = 0b0000_0001
Frame flag: this is the last message for the given correlation id. When a frame on an open stream carries this bit, no further frames will arrive for that id. Also available as FLAG_TERMINAL, the cross-SDK constant spelling.
const FlagSessionStart uint8 = 0b0000_0010
Frame flag: this is the first message of a new session. Set it on the opening frame of a request/response RPC or a streaming session. Also available as FLAG_SESSION_START.
const FlagShutdown uint8 = 0b0000_0100
Frame flag: this message requests sandbox shutdown. Also available as FLAG_SHUTDOWN.
func ConnectAgentSandbox(ctx context.Context, name string) (*AgentClient, error)
Connect to a running sandbox by name. Resolves the sandbox's relay socket path and performs the core.ready handshake. Sandbox names are limited to 128 UTF-8 bytes. Use context.WithTimeout to override the default 10s handshake timeout.
client, err := m.ConnectAgentSandbox(ctx, "dev")
if err != nil {
return err
}
defer client.Close()
func ConnectAgentPath(ctx context.Context, path string) (*AgentClient, error)
Connect to an agentd relay socket by path. Use this when you already have the socket path, for example one returned by AgentSocketPath(). Use context.WithTimeout to override the default 10s handshake timeout.
path, err := m.AgentSocketPath("dev")
if err != nil {
return err
}
client, err := m.ConnectAgentPath(ctx, path)
if err != nil {
return err
}
defer client.Close()
func AgentSocketPath(name string) (string, error)
Resolve a sandbox's agentd relay socket path without connecting. Returns the same path ConnectAgentSandbox() would dial internally (preferring the hashed path, falling back to the legacy name-derived path), so you can talk to agentd over a raw byte transport (for example a transparent relay that splices bytes between a WebSocket and the socket) instead of this frame client. The sandbox need not be running; the path is derived from the name and the configured home directory.
path, err := m.AgentSocketPath("dev")
if err != nil {
return err
}
fmt.Println(path)
func (c *AgentClient) Request(ctx context.Context, flags uint8, body []byte) (*RawFrame, error)
Send one frame and await a single response frame. Use for request/response RPCs that produce exactly one terminal response (for example a core.fs.request to its core.fs.response).
frame, err := client.Request(ctx, m.FlagSessionStart, body)
if err != nil {
return err
}
var msg map[string]any
if err := cbor.Unmarshal(frame.Body, &msg); err != nil {
return err
}
func (c *AgentClient) Stream(ctx context.Context, flags uint8, body []byte) (*AgentStream, error)
Open a streaming session. The returned AgentStream carries the protocol correlation id (read it with ID() and pass it to Send() for follow-up frames), and yields frames one at a time via Next().
stream, err := client.Stream(ctx, m.FlagSessionStart, body)
if err != nil {
return err
}
defer stream.Close(ctx)
for {
frame, err := stream.Next(ctx)
if err != nil {
return err
}
if frame == nil || frame.Flags&m.FlagTerminal != 0 {
break
}
}
func (c *AgentClient) Send(ctx context.Context, id uint32, flags uint8, body []byte) error
Send a follow-up frame on an existing correlation id (for example stdin, a signal, a resize, or data chunks on an open session). Use the id returned by AgentStream.ID().
if err := client.Send(ctx, stream.ID(), 0, stdinBytes); err != nil {
return err
}
func (c *AgentClient) ReadyBytes() ([]byte, error)
Return the cached handshake core.ready frame body as CBOR bytes. Captured during connect, so this reads from the cached handshake rather than producing protocol traffic.
ready, err := client.ReadyBytes()
if err != nil {
return err
}
var msg map[string]any
if err := cbor.Unmarshal(ready, &msg); err != nil {
return err
}
func (c *AgentClient) Close() error
Release the client handle. Idempotent: calling it more than once is safe.
<p className="msb-label">Returns</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><span className="msb-type">error</span></div> <div className="msb-param-desc">Typed microsandbox error.</div> </div> </div> <Accordion title="Example">defer client.Close()
func (c *AgentClient) CloseCtx(ctx context.Context) error
Release the client handle with a caller-controlled context. Like Close(), but lets you bound or cancel the teardown.
if err := client.CloseCtx(ctx); err != nil {
return err
}
func (s *AgentStream) Next(ctx context.Context) (*RawFrame, error)
Pull the next frame from the stream. Returns nil, nil at EOF, so loop until the frame is nil or carries FlagTerminal.
for {
frame, err := stream.Next(ctx)
if err != nil {
return err
}
if frame == nil {
break
}
}
func (s *AgentStream) ID() uint32
Return the protocol correlation id for this stream. Pass it to AgentClient.Send() for follow-up frames in the session.
id := stream.ID()
if err := client.Send(ctx, id, 0, stdinBytes); err != nil {
return err
}
func (s *AgentStream) Close(ctx context.Context) error
Release the stream handle.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>ctx</code><span className="msb-type">context.Context</span></div> <div className="msb-param-desc">Cancels the close.</div> </div> </div> <p className="msb-label">Returns</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><span className="msb-type">error</span></div> <div className="msb-param-desc">Typed microsandbox error.</div> </div> </div> <Accordion title="Example">defer stream.Close(ctx)
Low-level client for talking to agentd through the sandbox relay socket. All bodies are raw CBOR bytes: encode and decode them in your code with a library like fxamacker/cbor, and build typed convenience methods on top of this client. Construct it with one of the package-level connect functions.
| Method | Returns | Description |
|---|---|---|
Request(ctx, flags, body) | (*RawFrame, error) | Send one frame, await one response |
Stream(ctx, flags, body) | (*AgentStream, error) | Open a streaming session |
Send(ctx, id, flags, body) | error | Send a follow-up frame on a correlation id |
ReadyBytes() | ([]byte, error) | Cached core.ready handshake frame body |
Close() | error | Release the handle (idempotent) |
CloseCtx(ctx) | error | Release the handle with a context |
An open raw agent streaming session. Drive it by calling Next() until it returns nil, which happens after a frame carrying FlagTerminal or when the underlying stream is exhausted.
| Method | Returns | Description |
|---|---|---|
Next(ctx) | (*RawFrame, error) | Pull the next frame; nil at EOF |
ID() | uint32 | Protocol correlation id; pass to Send() for follow-up frames |
Close(ctx) | error | Release the stream handle |
A raw protocol frame. Body is the CBOR-encoded Message body (v, t, p) as it appeared on the wire; decode it with a CBOR library such as fxamacker/cbor.
| Field | Type | Description |
|---|---|---|
| ID | uint32 | Correlation id from the frame header |
| Flags | uint8 | Frame flags (FlagTerminal, FlagSessionStart, ...) |
| Body | []byte | Raw CBOR-encoded body bytes |