---
title: Agent client
description: Go SDK - Low-level agentd client reference
---
Low-level raw CBOR transport for communicating with `agentd` through a sandbox relay.
## Constants
#### FlagTerminal
```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
```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
```go
const FlagShutdown uint8 = 0b0000_0100
```
Frame flag: this message requests sandbox shutdown. Also available as `FLAG_SHUTDOWN`.
## Functions
#### m.ConnectAgentSandbox()
Local-only
```go
func ConnectAgentSandbox(ctx context.Context, name string) (*AgentClient, error)
```
```go
client, err := m.ConnectAgentSandbox(ctx, "dev")
if err != nil {
return err
}
defer client.Close()
```
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.
#### m.ConnectAgentPath()
Local-only
```go
func ConnectAgentPath(ctx context.Context, path string) (*AgentClient, 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()
```
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.
#### m.AgentSocketPath()
Local-only
```go
func AgentSocketPath(name string) (string, error)
```
```go
path, err := m.AgentSocketPath("dev")
if err != nil {
return err
}
fmt.Println(path)
```
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.
## AgentClient
Returned by ConnectAgentSandbox() · ConnectAgentPath()
Low-level client for raw agent frames.
#### c.Request()
```go
func (c *AgentClient) Request(ctx context.Context, flags uint8, body []byte) (*RawFrame, 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
}
```
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.
#### c.Stream()
```go
func (c *AgentClient) Stream(ctx context.Context, flags uint8, body []byte) (*AgentStream, 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
}
}
```
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.
#### c.Send()
```go
func (c *AgentClient) Send(ctx context.Context, id uint32, flags uint8, body []byte) error
```
```go
if err := client.Send(ctx, stream.ID(), 0, stdinBytes); err != nil {
return err
}
```
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.
#### c.ReadyBytes()
```go
func (c *AgentClient) ReadyBytes() ([]byte, 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
}
```
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.
#### c.Close()
```go
func (c *AgentClient) Close() error
```
```go
defer client.Close()
```
Release the client handle. Idempotent: calling it more than once is safe.
Returns
error
Typed microsandbox error.
#### c.CloseCtx()
```go
func (c *AgentClient) CloseCtx(ctx context.Context) error
```
```go
if err := client.CloseCtx(ctx); err != nil {
return err
}
```
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.
## AgentStream
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.
#### s.Next()
```go
func (s *AgentStream) Next(ctx context.Context) (*RawFrame, error)
```
```go
for {
frame, err := stream.Next(ctx)
if err != nil {
return err
}
if frame == nil {
break
}
}
```
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.
#### s.ID()
```go
func (s *AgentStream) ID() uint32
```
```go
id := stream.ID()
if err := client.Send(ctx, id, 0, stdinBytes); err != nil {
return err
}
```
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.
#### s.Close()
```go
func (s *AgentStream) Close(ctx context.Context) error
```
```go
defer stream.Close(ctx)
```
Release the stream handle.
Parameters
ctxcontext.Context
Cancels the close.
Returns
error
Typed microsandbox error.
## Types
### RawFrame
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 |