# SDK operations

Find the supported method for a communication task in Python, TypeScript or Go.

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](https://beepgrid.com/docs/sdks.md) show client construction and shutdown.

## 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

| 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

| 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](https://beepgrid.com/docs/workspace/files.md) and [reliability](https://beepgrid.com/docs/sdks/reliability.md) before handling unknown upload outcomes.

## 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

`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](https://beepgrid.com/docs/reference/openapi.json) supplies its exact body and response schema.