sinapsis-api
Local HTTP and WebSocket execution for Sinapsis Agents.
sinapsis-api provides a local execution service for Sinapsis Agents. It exposes HTTP endpoints for Agent and job management, and WebSocket/binary event delivery for observing execution. Agents run in separate subprocesses rather than inside FastAPI request handlers.
This package is the Local API, not the Sinapsis Cloud service. For applications that consume its endpoints, the recommended Python interface is sinapsis-sdk.
Architecture
flowchart TB
Client[CLI / SDK / HTTP clients] -->|HTTP / WebSocket| API[FastAPI · Local API]
API <-->|ZeroMQ · MessagePack control| Router[Agent Router]
Router <-->|ZeroMQ| WorkerA[Agent worker A · subprocess]
Router <-->|ZeroMQ| WorkerB[Agent worker B · subprocess]
WorkerA --> RuntimeA[Sinapsis Agent A]
WorkerB --> RuntimeB[Sinapsis Agent B]
WorkerA -->|Serialized SSEEnvelope| Router
WorkerB -->|Serialized SSEEnvelope| Router
Router --> Journal[Bounded per-Agent event journals]
Responsibilities are deliberately separated:
| Component | Responsibility |
|---|---|
| FastAPI | Validates requests, forwards Router commands, exposes HTTP and WebSocket responses. |
| Agent Router | Owns worker lifecycle, job state, event journals, subscription management and replay. |
| Agent worker | Instantiates and runs a Sinapsis Agent in its own OS process; emits execution events. |
| Sinapsis runtime | Evaluates the Agent graph and its Templates using the shared DataContainer contract. |
Multiple API workers can connect to the same Router, sharing Agent processes and event history.
Installation
Requires Python 3.13+.
uv pip install sinapsis-api
# or
pip install sinapsis-api
For normal local execution, use the sinx-api profile of sinapsis-cli. The instructions below show how to run the service components directly for development or self-managed operation.
Run the Local API
The Router must be started before FastAPI. In two terminals within an environment containing sinapsis-api:
Terminal 1 — Router
python -m sinapsis_api.agent_router
Terminal 2 — HTTP API
uvicorn sinapsis_api.api.main:app --host 127.0.0.1 --port 8005
Check connectivity:
curl http://127.0.0.1:8005/api/v1/health
The health response includes the Router's stream identifier. The interactive OpenAPI documentation is available at http://127.0.0.1:8005/docs when the service is running.
The Router and API are separate processes. Avoid running two Routers against the same configured endpoints.
HTTP API
Routes are versioned under /api/v1 and share typed request/response models from sinapsis-contracts.
| Method | Path | Purpose |
|---|---|---|
GET |
/api/v1/health |
Check API-to-Router connectivity and obtain stream_id. |
POST |
/api/v1/agents |
Start an Agent process from a validated AgentSchema JSON representation. |
DELETE |
/api/v1/agents/{agent_id} |
Stop an Agent process. |
GET |
/api/v1/agents/{agent_id}/events |
Replay retained Agent events with optional cursor and job filtering. |
WS |
/api/v1/agents/{agent_id}/events/ws |
Receive live events or replay-then-live delivery. |
POST |
/api/v1/jobs |
Start a finite job for a previously created Agent. |
GET |
/api/v1/jobs/{job_id} |
Retrieve job status. |
POST |
/api/v1/jobs/{job_id}/cancel |
Cancel a running job. |
POST |
/api/v1/jobs/{job_id}/feedback |
Submit approval feedback for an execution. |
A finite execution has two separate identities: agent_id identifies the Agent instance and its event stream, while job_id identifies one execution. Do not interchange them.
Create an Agent
POST /api/v1/agents accepts a JSON representation of the framework's validated AgentSchema. The service can assign an Agent ID if it is missing.
To prepare a schema from a user-defined Agent configuration:
from sinapsis.agent import AgentSchema, generic_agent_schema_builder
schema: AgentSchema = generic_agent_schema_builder(agent_definition)
agent_json = schema.model_dump_json()
The API receives agent_json as the request body. This is not the same as a Cloud jobs.submit() request, which wraps the user-defined graph under agent_definition.
Start and inspect a job
Once an Agent has been started and its agent_id returned:
curl -X POST http://127.0.0.1:8005/api/v1/jobs \
-H 'Content-Type: application/json' \
-d '{"agent_id":"AGENT_ID"}'
The response contains a job_id. To inspect it:
curl http://127.0.0.1:8005/api/v1/jobs/JOB_ID
You can also submit and inspect jobs using SinapsisAPIClient.jobs from the SDK, which handles Agent creation and job submission together.
StartJobRequest.payload is optional; when supplied, it must be a base64-encoded serialized DataContainer.
Agent and job lifecycles
An Agent is a running execution context; a job is one finite execution against it. Job state is tracked separately from application events.
Agent definition -> Agent process started -> Agent ready
|
v
Job queued -> running
| | |
completed failed cancelled
The runtime supports finite SINGLE and GENERATOR execution modes. Long-running LOOP_FOREVER Agents are started as production tasks rather than submitted as finite jobs.
Event transport and replay
Application output and Router control traffic are separate:
- A worker packages execution data into a Sinapsis
SSEEnvelopeand serializes it to MessagePack bytes. - ZeroMQ carries the serialized event to the Router.
- The Router retains it in a bounded per-Agent journal and distributes the same opaque payload to subscribers; it does not deserialize the
DataContainerfor routing. - FastAPI delivers event frames to clients over WebSocket or through an HTTP replay response.
This avoids repeated decoding of potentially large image, audio, array, and binary payloads along the transport path.
Event cursors
Events receive monotonically increasing cursor values within a logical Agent stream. Expiring older events does not renumber later cursors. Every stream has a stream_id.
WS /api/v1/agents/{agent_id}/events/wswithoutaftersubscribes to new events only.WS /api/v1/agents/{agent_id}/events/ws?after=0replays the currently retained window, then receives live events.WS /api/v1/agents/{agent_id}/events/ws?after=123resumes after cursor123, subject to retention limits.GET /api/v1/agents/{agent_id}/events?after=123returns a bounded replay page. Optionaljob_idfilters by execution.
Replay responses use application/x-sinapsis-events and length-prefixed binary frames. Replay headers include the stream ID, oldest/latest/next cursor, truncation status, and whether additional pages remain.
The client should persist its last processed cursor. If an old cursor has fallen outside the retained window, the Router replays what is still available and reports truncation.
Binary frame layout
MessagePack metadata header | serialized SSEEnvelope bytes
Metadata identifies the stream, cursor, Agent, worker instance and (when applicable) job. SDK consumers can use LocalJobEvent.metadata and LocalJobEvent.envelope; raw WebSocket clients must decode the framing and envelope correctly.
Bounded retention and backpressure
The local Router keeps a rolling event journal, not an indefinite archive. Limits apply to event age, event count, cumulative event bytes, and replay-page size.
| Configuration | Default | Meaning |
|---|---|---|
SINAPSIS_API_EVENT_RETENTION_SECONDS |
3600 |
Maximum retained age of journal events. |
SINAPSIS_API_EVENT_MAX_EVENTS_PER_AGENT |
10000 |
Maximum event count per Agent. |
SINAPSIS_API_EVENT_MAX_BYTES_PER_AGENT |
268435456 |
Maximum retained event bytes per Agent. |
SINAPSIS_API_EVENT_MAX_BYTES |
104857600 |
Maximum accepted size of one serialized event. |
SINAPSIS_API_EVENT_REPLAY_LIMIT |
1000 |
Maximum event count per replay page. |
SINAPSIS_API_SUBSCRIBER_QUEUE_SIZE |
1024 |
Pending live events per subscriber. |
SINAPSIS_API_STOPPED_AGENT_RETENTION_SECONDS |
86400 |
Retention of stopped-Agent journals before cleanup. |
For example, to retain recent events longer:
export SINAPSIS_API_EVENT_RETENTION_SECONDS=7200
Additional configuration controls worker outbound queue capacity, ZeroMQ high-water marks, startup timeouts and journal cleanup intervals. These bounded queues prevent a slow subscriber from indefinitely blocking other consumers. When a subscriber falls behind, it can reconnect from its last received cursor while the missing events remain retained.
Runtime configuration
The Router's default ZeroMQ endpoints are:
| Environment variable | Default |
|---|---|
SINAPSIS_API_ROUTER_API_ENDPOINT |
tcp://127.0.0.1:8765 |
SINAPSIS_API_ROUTER_AGENT_ENDPOINT |
tcp://127.0.0.1:8766 |
SINAPSIS_API_ROUTER_STREAM_ENDPOINT |
tcp://127.0.0.1:8767 |
The local direct-start examples use loopback endpoints. When running Router and API in separate containers, configure network-reachable endpoints instead; each container's 127.0.0.1 is its own network namespace.
The local API requires no external Redis or RabbitMQ broker for its Router-to-worker event transport. ZeroMQ provides IPC; the Router owns short-term event retention.
Integration with the SDK and CLI
For most applications, use the SDK instead of implementing binary event framing manually:
import asyncio
from sinapsis.agent import AgentSchema, generic_agent_schema_builder
from sinapsis_sdk.common.base_config import BaseAPIConfig
from sinapsis_sdk.local_api.client import SinapsisAPIClient
async def run(agent_definition: dict) -> None:
schema: AgentSchema = generic_agent_schema_builder(agent_definition)
async with SinapsisAPIClient(
BaseAPIConfig(api_url="http://127.0.0.1:8005")
) as client:
submitted = await client.jobs.submit(schema)
print("Submitted:", submitted.job_id)
status = await client.jobs.get_status(submitted.job_id)
print("Status:", status.status)
# asyncio.run(run(your_agent_definition))
The sinx-api CLI profile provides a command-line interface to the same local execution backend. See the Sinapsis CLI README for CLI-specific commands.
Documentation and resources
License
Sinapsis open-source components are available under your choice of the MIT License; or the Apache License 2.0 unless otherwise noted.
Metadata
Release files for sinapsis-api 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| sinapsis_api-1.0.0.tar.gz | 74.9 kB | Without provenance | Details for sinapsis_api-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| sinapsis_api-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for sinapsis_api-1.0.0-py3-none-any.whl |
Total release size: 121.0 kB
Release files / sinapsis_api-1.0.0.tar.gz
| Download URL | sinapsis_api-1.0.0.tar.gz |
|---|---|
| Size | 74.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
719c8b59103af9f85748f911fe3e66fd2c2104a53b3dd57b0be6996caebca800
|
|
BLAKE2b-256 checksum How to use checksums |
52e50a5d0c06633d07434c0e5ff61d3fd168bd77175d86e316574be8a17f13b3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.6.17
|
Release files / sinapsis_api-1.0.0-py3-none-any.whl
| Download URL | sinapsis_api-1.0.0-py3-none-any.whl |
|---|---|
| Size | 46.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3458389d920431bd69682e0f3a731914fab346e7d0930e7a95e43f268893cc98
|
|
BLAKE2b-256 checksum How to use checksums |
165de392b50cef44e2ab6b68b71121f266d7f7cac81b007c56cc80f583a8d5c1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.6.17
|
Security for sinapsis-api 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.