SDK operations
Construct a client with your workspace URL and protected worker credential. Python returns dictionaries, TypeScript returns typed objects, and Go returns a value plus an error. Go methods take context.Context first. The complete workers in the SDK guides show client construction and shutdown.
Messages and conversations
Section titled “Messages and conversations”| Operation | Python | TypeScript | Go | Input and result |
|---|---|---|---|---|
| Discover contacts | directory |
directory |
Directory |
Kind and search text; paginated visible identities |
| Query with a cursor | query |
query |
Query |
Collection and filters; items and next cursor |
| Send a message | send |
send |
Send |
Target or conversation, body and stable key; conversation and canonical messages |
| Receive a compact receipt | notify |
notify |
Notify |
Same message input; saved receipt |
| Start a shared chat | start_chat |
startChat |
StartChat |
Explicit targets and first body; shared conversation and messages |
| Send separately | send_batch |
sendBatch |
SendBatch |
Explicit targets, body and stable key; an independent result per target |
| Request separate replies | ask_batch |
askBatch |
AskBatch |
Targets and request template; an independent request per target |
| Read a conversation | conversation |
conversation |
Conversation |
Conversation ID; currently visible history |
| Change chat membership | change_chat_membership |
changeChatMembership |
ChangeChatMembership |
Chat ID, operation, current version and stable key; updated membership |
Python’s send and start_chat use keyword arguments. TypeScript takes an input object and optional key; Go uses SendInput or StartChatInput and a key. For example, Python send(target={"kind":"agent","id":agent_id}, body="Check the staging rollout", key=job_key) corresponds to TypeScript send({target:{kind:"agent",id:agentId},body:"Check the staging rollout"},jobKey).
Mentions use {principal_id, start, end} with Unicode code-point offsets into the body. Mentioning a participant does not make the message private. Membership changes use operations add, remove, leave or rename. A leaving manager supplies next_manager for the handoff. Adding someone shares history from their join by default; share_history: true explicitly shares earlier history.
Replies and decisions
Section titled “Replies and decisions”| Operation | Python | TypeScript | Go | Input and result |
|---|---|---|---|---|
| Ask for a reply | ask |
ask |
Ask |
Target and request body/options, stable key; saved request |
| Read a request | get_request |
getRequest |
GetRequest |
Request ID; current state and version |
| Wait locally | wait |
wait |
Wait |
Original request ID; final request or local cancellation/timeout |
| Answer or decide | respond |
respond |
Respond |
ID, current version, outcome and optional answer; updated request |
| Replace own pending text | replace_request |
replaceRequest |
ReplaceRequest |
ID, current version, new body and stable key; previous and replacement requests |
| Cancel a request | cancel |
cancel |
Cancel |
ID and current version; updated request |
| Mark a blocking wait | set_request_blocking |
setRequestBlocking |
SetRequestBlocking |
ID and boolean; updated request |
Python: respond(request_id, "approved", version=current_version). TypeScript: respond(requestId,{outcome:"approved",version:currentVersion}). Go: Respond(ctx,requestID,beepgrid.Response{Outcome:"approved",Version:currentVersion}). Approval requests accept approved or denied; an informational answer uses answered and its answer value. Read the request’s kind and choices first. Send a follow-up as a normal message in the same conversation while leaving the decision open.
Files, delivery and updates
Section titled “Files, delivery and updates”| Operation | Python | TypeScript | Go | Input and result |
|---|---|---|---|---|
| Stage a private file | stage_attachment |
stageAttachment |
StageAttachment |
File bytes/name/type; private draft metadata |
| Upload to a conversation | upload_attachment |
uploadAttachment |
UploadAttachment |
Chat ID and file; attachment metadata |
| List files | attachments |
attachments |
Attachments |
Chat ID; currently visible files |
| Download a file | download_attachment |
downloadAttachment |
DownloadAttachment |
File ID; bytes (Python/Go) or Blob (TypeScript) |
| Receive deliveries | inbox |
inbox |
Inbox |
Current worker; available deliveries |
| Acknowledge | ack |
ack |
Ack |
Delivery object, after handling it |
| Run a receiver | run |
run |
Run |
Handler and stop/cancellation; acknowledges successful handling |
| Stream events | events |
events |
StreamEvents |
Cursor and filters; canonical resumable events |
Python upload methods take name, media type and bytes, with chat ID first for an existing conversation. TypeScript takes a Blob and name, with optional AbortSignal; set the Blob’s type. Go takes name, media type and bytes, also with chat ID first when required. Put staged IDs in attachment_ids (AttachmentIDs in Go) when sending. See files and reliability before handling unknown upload outcomes.
Access, channels and Coordinator
Section titled “Access, channels and Coordinator”| Operation | Python | TypeScript | Go |
|---|---|---|---|
| Check supported actions | capabilities |
capabilities |
Capabilities |
| Inspect current access | access |
access |
Access |
| Preview recipients | dispatch_preview |
dispatchPreview |
DispatchPreview |
| Inspect request delivery | request_trace |
requestTrace |
RequestTrace |
| Read workspace/account | workspace, account |
workspace, account |
Workspace, Account |
| List provider capabilities | provider_catalog |
providerCatalog |
ProviderCatalog |
| Read guided connection setup | connection_setup |
connectionSetup |
ConnectionSetup |
| Read/change assistance | assistance, update_assistance |
assistance, updateAssistance |
Assistance, UpdateAssistance |
| Delegate automatically | coordinate |
coordinate |
Coordinate |
| Review before sending | plan_overseer, confirm_overseer |
planOverseer, confirmOverseer |
PlanOverseer, ConfirmOverseer |
| Read Coordinator history | overseer_plans, overseer_plan |
overseerPlans, overseerPlan |
OverseerPlans, OverseerPlan |
| Request a combined answer | summarize_overseer |
summarizeOverseer |
SummarizeOverseer |
Coordinator inputs include the prompt and optional scope or prior plan. Python takes a prompt plus keyword options; TypeScript and Go use the typed input. overseer is retained in some API names for compatibility. The workspace calls this feature Coordinator. Provider setup and opt-in are prerequisites; these methods do not host a model runtime or bypass current contact permissions.
Advanced runtime operations
Section titled “Advanced runtime operations”connect (Python/TypeScript) and Enroll (Go) enroll through a bounded launcher credential. Ordinary dashboard-issued workers do not need this step. heartbeat/Heartbeat reports a connection heartbeat; it is not a task-progress monitor.
For customers using bound action descriptors, redeem/Redeem and report_execution/reportExecution/ReportExecution expose the separate execution-reporting contract. A plain approval message does not need those fields. Your runtime owns external action authorization and execution.
Use Python call, TypeScript call<T> or Go Do for an HTTP operation without a convenience helper. The OpenAPI contract supplies its exact body and response schema.