Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.microsandbox.dev/llms.txt

Use this file to discover all available pages before exploring further.

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 fs instead. Use this API when you are building protocol-level tools or higher-level SDK helpers. All request bodies 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. The raw body is the full CBOR-encoded protocol Message body: v, t, and p. It is not just the inner payload. 
from microsandbox import AgentClient

client = await AgentClient.connect_sandbox("dev")
ready = client.ready_bytes()
await client.close()

​
Constants

NameValueDescription
FLAG_TERMINAL0b0000_0001Last frame for a correlation id
FLAG_SESSION_START0b0000_0010First frame of a streaming session
FLAG_SHUTDOWN0b0000_0100Shutdown frame

​
AgentClient.connect_sandbox()

@classmethod
async def connect_sandbox(cls, name: str) -> AgentClient
Connect to a running sandbox by name.

​
AgentClient.connect()

@classmethod
async def connect(cls, path: str) -> AgentClient
Connect to an agent relay socket by path.

​
request()

async def request(self, flags: int, body: bytes) -> RawFrame
Send one raw frame and wait for one response frame.

​
stream()

async def stream(self, flags: int, body: bytes) -> AgentStream
Open a raw streaming session. The returned stream carries the protocol correlation id and is also an async iterator of raw frames. 
stream = await client.stream(FLAG_SESSION_START, body)
async for frame in stream:
    if frame["flags"] & FLAG_TERMINAL:
        break

​
send()

async def send(self, id: int, flags: int, body: bytes) -> None
Send a follow-up frame on an existing correlation id. Use this with the id on the AgentStream returned by stream().

​
ready_bytes()

def ready_bytes(self) -> bytes
Return the cached handshake core.ready frame body as CBOR bytes.

​
close()

async def close(self) -> None
Close the client. Calling it more than once is safe.

​
RawFrame

class RawFrame(TypedDict):
    id: int
    flags: int
    body: bytes
id is the protocol correlation id, flags is the frame flag byte, and body is the CBOR-encoded protocol message body.

​
AgentStream

class AgentStream:
    id: int
    async def next(self) -> RawFrame | None: ...
    async def close(self) -> None: ...
id is the protocol correlation id. Pass it to AgentClient.send() for follow-up frames in the same session. close() releases the stream handle early. next() returns None at EOF.