---
title: Agent client
description: Go SDK - Low-level agentd client reference
---
`AgentClient` is the low-level raw transport for talking to `agentd` through a running sandbox's relay socket. Most applications should use [`Sandbox`](/sdk/go/sandbox), [`Exec`](/sdk/go/execution), 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.
Typical flow
```go
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
```
## Constants
---
#### FlagTerminal
const
```go
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.
---
#### FlagSessionStart
const
```go
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`.
---
#### FlagShutdown
const
```go
const FlagShutdown uint8 = 0b0000_0100
```
Frame flag: this message requests sandbox shutdown. Also available as `FLAG_SHUTDOWN`.
## Functions
---
#### m.ConnectAgentSandbox()
function
```go
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.
Parameters
ctxcontext.Context
Bounds the handshake; defaults to a 10s timeout if none is set.
namestring
Sandbox name, up to 128 UTF-8 bytes.
Returns
error
Typed microsandbox error.
```go
client, err := m.ConnectAgentSandbox(ctx, "dev")
if err != nil {
return err
}
defer client.Close()
```
---
#### m.ConnectAgentPath()
function
```go
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()`](#m-agentsocketpath). Use `context.WithTimeout` to override the default 10s handshake timeout.
Parameters
ctxcontext.Context
Bounds the handshake; defaults to a 10s timeout if none is set.
pathstring
Filesystem path of the relay socket.
Returns
error
Typed microsandbox error.
```go
path, err := m.AgentSocketPath("dev")
if err != nil {
return err
}
client, err := m.ConnectAgentPath(ctx, path)
if err != nil {
return err
}
defer client.Close()
```
---
#### m.AgentSocketPath()
function
```go
func AgentSocketPath(name string) (string, error)
```
Resolve a sandbox's `agentd` relay socket path **without connecting**. Returns the same path [`ConnectAgentSandbox()`](#m-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.
Parameters
namestring
Sandbox name, up to 128 UTF-8 bytes.
Returns
string
Relay socket path.
error
Typed microsandbox error.
```go
path, err := m.AgentSocketPath("dev")
if err != nil {
return err
}
fmt.Println(path)
```
## AgentClient methods
---
#### c.Request()
method
```go
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`).
Parameters
ctxcontext.Context
Cancels the request.
flagsuint8
Frame flag byte, e.g. FlagSessionStart.
body[]byte
CBOR-encoded protocol message body.
Returns
The single response frame.
error
Typed microsandbox error.
```go
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
}
```
---
#### c.Stream()
method
```go
func (c *AgentClient) Stream(ctx context.Context, flags uint8, body []byte) (*AgentStream, error)
```
Open a streaming session. The returned [`AgentStream`](#agentstream) carries the protocol correlation id (read it with [`ID()`](#s-id) and pass it to [`Send()`](#c-send) for follow-up frames), and yields frames one at a time via [`Next()`](#s-next).
Parameters
ctxcontext.Context
Cancels opening the stream.
flagsuint8
Frame flag byte for the opening frame, e.g. FlagSessionStart.
body[]byte
CBOR-encoded protocol message body.
Returns
Open stream of raw frames.
error
Typed microsandbox error.
```go
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
}
}
```
---
#### c.Send()
method
```go
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()`](#s-id).
Parameters
ctxcontext.Context
Cancels the send.
iduint32
Correlation id of an open session.
flagsuint8
Frame flag byte.
body[]byte
CBOR-encoded protocol message body.
Returns
error
Typed microsandbox error.
```go
if err := client.Send(ctx, stream.ID(), 0, stdinBytes); err != nil {
return err
}
```
---
#### c.ReadyBytes()
method
```go
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.
Returns
[]byte
CBOR-encoded core.ready frame body.
error
Typed microsandbox error.
```go
ready, err := client.ReadyBytes()
if err != nil {
return err
}
var msg map[string]any
if err := cbor.Unmarshal(ready, &msg); err != nil {
return err
}
```
---
#### c.Close()
method
```go
func (c *AgentClient) Close() error
```
Release the client handle. Idempotent: calling it more than once is safe.
Returns
error
Typed microsandbox error.
```go
defer client.Close()
```
---
#### c.CloseCtx()
method
```go
func (c *AgentClient) CloseCtx(ctx context.Context) error
```
Release the client handle with a caller-controlled context. Like [`Close()`](#c-close), but lets you bound or cancel the teardown.
Parameters
ctxcontext.Context
Cancels the close.
Returns
error
Typed microsandbox error.
```go
if err := client.CloseCtx(ctx); err != nil {
return err
}
```
## AgentStream methods
---
#### s.Next()
method
```go
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`](#flagterminal).
Parameters
ctxcontext.Context
Cancels waiting for the next frame.
Returns
Next frame, or nil at EOF.
error
Typed microsandbox error.
```go
for {
frame, err := stream.Next(ctx)
if err != nil {
return err
}
if frame == nil {
break
}
}
```
---
#### s.ID()
method
```go
func (s *AgentStream) ID() uint32
```
Return the protocol correlation id for this stream. Pass it to [`AgentClient.Send()`](#c-send) for follow-up frames in the session.
Returns
uint32
Correlation id for this session.
```go
id := stream.ID()
if err := client.Send(ctx, id, 0, stdinBytes); err != nil {
return err
}
```
---
#### s.Close()
method
```go
func (s *AgentStream) Close(ctx context.Context) error
```
Release the stream handle.
Parameters
ctxcontext.Context
Cancels the close.
Returns
error
Typed microsandbox error.
```go
defer stream.Close(ctx)
```
## Types
### AgentClient
struct
Returned by ConnectAgentSandbox() · ConnectAgentPath()
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)`](#c-request) | `(`[`*RawFrame`](#rawframe)`, error)` | Send one frame, await one response |
| [`Stream(ctx, flags, body)`](#c-stream) | `(`[`*AgentStream`](#agentstream)`, error)` | Open a streaming session |
| [`Send(ctx, id, flags, body)`](#c-send) | `error` | Send a follow-up frame on a correlation id |
| [`ReadyBytes()`](#c-readybytes) | `([]byte, error)` | Cached `core.ready` handshake frame body |
| [`Close()`](#c-close) | `error` | Release the handle (idempotent) |
| [`CloseCtx(ctx)`](#c-closectx) | `error` | Release the handle with a context |
### AgentStream
struct
Returned by Stream()
An open raw agent streaming session. Drive it by calling [`Next()`](#s-next) until it returns `nil`, which happens after a frame carrying [`FlagTerminal`](#flagterminal) or when the underlying stream is exhausted.
| Method | Returns | Description |
|--------|---------|-------------|
| [`Next(ctx)`](#s-next) | `(`[`*RawFrame`](#rawframe)`, error)` | Pull the next frame; `nil` at EOF |
| [`ID()`](#s-id) | `uint32` | Protocol correlation id; pass to [`Send()`](#c-send) for follow-up frames |
| [`Close(ctx)`](#s-close) | `error` | Release the stream handle |
### RawFrame
struct
Returned by Request() · yielded by Next()
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 |