Skip to content
apomesh

Build on apomesh

This section is for the person building on apomesh: dispatching sessions, subscribing to live events, and wiring the substrate into an application. You drive the same substrate workflows through whichever transport fits your stack — every transport translates wire bytes to the same typed workflow and back, so a session started over gRPC behaves identically to one started over REST.

Pick a surface below. If you are running the stack rather than integrating with it, start with Operate instead.

Python SDK

Section titled “Python SDK”

The Python SDK is the ergonomic entry point: a Pydantic-typed wrapper over the daemon’s gRPC API. You dispatch a session with one call, iterate live events with async for, and retrieve the terminal outcome and cost rollup without touching gRPC plumbing. It also ships the apomesh.deep_research.run helper that drives the deep-research vertical end-to-end. Install it from source with uv; it is not yet on a package index.

REST + SSE

Section titled “REST + SSE”

The REST + SSE surface is the language-agnostic path: start and cancel sessions over plain HTTP JSON, and tail the live event bus as a Server-Sent Events stream. It exposes the same substrate workflows as gRPC, so a curl script and the Python SDK reach identical behaviour. The full endpoint set is described by the served OpenAPI document at GET /api/v1/openapi.json.

gRPC

Section titled “gRPC”

gRPC is the daemon’s native transport — the driver-facing StartSession / TailEvents / CancelSession RPCs, plus the registry, strategy-config, and token-admin services. The Python SDK wraps this surface directly, so the SDK page is the fastest way to consume it. The wire contract is the source of truth: apomesh.proto. The daemon listens on 50051 by default in the local stack.

MCP

Section titled “MCP”

apomesh both consumes and admits Model Context Protocol tools. An MCP server is one kind of connector: it is declared, probed and admitted through the connector plane’s admin RPCs rather than an MCP-specific surface, then admitted per session so agents can call its tools under the same sandbox and tenant-isolation contract as first-party tools. The dedicated MCP-admin RPCs and their McpAdminClient are gone — a declaration is a declaration whatever kind it names, which is what lets curation, rate control and credential resolution be written once instead of per kind. The SDK client is clients/connector_admin.py.

Programmable agents

Section titled “Programmable agents”

The surfaces above drive apomesh from outside. A programmable agent is the other direction: your own code, in your own language, shipped as a container image and run by the platform as a confined workload. It reaches the substrate over one typed channel — the function plane — rather than over gRPC or REST, and holds no substrate handles at all. Reach for it when an agent’s logic is genuinely code rather than configuration. The concepts are in programmable agents & the function plane.

Verticals as worked examples

Section titled “Verticals as worked examples”

A vertical is a specialization that plugs into the orchestrator’s strategy seam — it is the reference for how a real integration composes the substrate primitives. Two ship in-tree:

  • Deep Research — web search + fetch producing a report in which every claim carries a fetched citation, runnable under the VMAO loop or the multi-agent debate coordinator. This is the fully worked example.
  • Coding assistant — a file/shell/git tool loop; see verticals/coding-assistant and the sample dispatcher.

Next steps

Section titled “Next steps”