Connectors administration
Connectors are Kamiwaza-managed adapters to external sources. Kaizen discovers instances at runtime; your job is deciding what each one is allowed to be.
Discovery is not configuration
Kaizen carries no fixed connector catalog. It reads the connector instances and their declared surfaces from the current workroom at runtime.
Consequences:
- a new connector type appears without a Kaizen release;
- nothing in Kaizen's compose file or environment should enumerate connector types — adding such a list reintroduces the release coupling this design removes;
- an instance that disappears from the workroom simply stops being offered.
Two independent decisions
For each ready instance, choose:
| Decision | Effect |
|---|---|
| Expose as a tool | Agents may call it directly during a turn |
| Participate in RAG | Its content is retrievable as evidence |
These are independent. An instance can be a tool without being indexed, indexed without being a tool, both, or neither.
Either content grant makes the instance eligible for Kaizen's federated live query at the level that grant already permits. Tools permits live browse/search/fetch; RAG permits live evidence retrieval. The federated entry point changes discovery order, not authority: it cannot include an instance that the agent policy excluded.
Manage both from Admin → Kamiwaza Connectors.
The connector table keeps access details and RAG controls in separate columns. Long account names and surface lists wrap within their cells; at narrow widths, scroll the table to reach every action instead of relying on clipped controls.
Identity always flows through
Every connector call runs as the signed-in member. Kaizen holds no broad service credential that could see more than an individual can.
Two readiness shapes exist:
| Kind | Ready when | Operator note |
|---|---|---|
| Service-token | Ready for the whole workroom | No per-user action; check that the token's scope is genuinely appropriate for everyone |
| User-authorized | Ready only after that user connects | Members who have not connected simply get fewer results, not an error |
Because access is per member, two people running the same query legitimately get different results. That is correct behavior, not a bug report.
Kaizen-owned sync
A signed-in member can start a sync: Kaizen walks the connector's generic surfaces and streams each discovered document into the private index immediately.
Progress reflects how the walk works. Discovery shows an indeterminate count while content fetch, chunking, and embedding run concurrently; once the walk establishes the final total, the same run switches to exact percentage progress. A sync that shows no percentage for a while is working, not stuck.
Synced chunks carry an opaque member/workroom/connector grant that Kaizen revalidates against Kamiwaza on every retrieval. A synced chunk is a pointer that must prove itself again each time, not a stored permission.
Lifecycle operations
The ops surface supports listing, adopting, creating, updating, enabling, disabling, deleting, and resyncing connector configurations, plus per-instance RAG actions.
Chat can also discover the authenticated Core create/update operations when the
administrator and member selections allow them. Non-secret type settings—such
as a Website connector's HTTPS sites list—travel with the initiating member's
forwarded identity and require the normal write approval. Core remains the
authorization authority. Credential fields are not ordinary chat arguments;
they are rejected before dispatch and must use the platform's credential flow.
For an open-ended provider configuration, Chat first reads the registered
connector type's live schema and then reads the saved instance after the write.
Do not treat a create/update response alone as proof of configuration: missing
or different persisted settings are surfaced as a failed operation.
Resync when:
- a source has changed substantially and freshness matters,
- you changed the embedding model (existing vectors are not comparable),
- a walk failed partway and the index is incomplete.
Disable rather than delete when you want to stop retrieval but keep the configuration for later.
Deployment settings
Connector deployments accept non-secret settings forwarded from the frontend to the running pod, with automatic redeployment when they change. Use these for site-specific configuration; never for credentials.
Secrets belong in the platform's secret handling, marked as such, and are injected and redacted rather than stored in plain configuration.
Managed object sources for demos
Demo Builder can plan or use AWS S3 and Cloudflare R2 through an installed governed capability that refers to a platform-managed connection. Treat R2 as an S3-compatible source, but keep provider-specific endpoint and credential handling outside Kaizen and outside the Demo Blueprint.
Require a preview bounded by one bucket plus a prefix, exact object list, or manifest digest. Set limits for object count, total and expanded bytes, per-object bytes, duration, and concurrency. A successful import should return a coverage manifest with an outcome for every selected object and a version ID, ETag, or computed digest when available. Pagination, permission denials, source changes, timeouts, and decompression limits make coverage partial.
Large or restart-sensitive imports need a durable checkpoint contract from the governed capability. If no suitable tool or connector is installed, Demo Builder records the bounded source request in its operator plan and imports nothing; direct keys, endpoint overrides, signed URLs, and sandbox egress are not fallbacks.
The built-in SDK adapter may list safe connector metadata, but it does not create or reconfigure connectors and does not turn that inventory into S3/R2 object access. Connector credentials, endpoint selection, object coverage, and resumable ingestion remain the installed managed-source capability's contract.
Operational guidance
Start narrow. Expose one connector as a RAG source, verify retrieval quality and permission behavior with a real member account, then widen.
Watch the first sync. It is the heaviest embedding load a deployment will see outside a reindex. See Ingestion & indexing.
Prefer per-user authorization for sensitive sources. A service token that is ready for the whole workroom is exactly as broad as it sounds.
Expect partial results. If a provider is unavailable, Search labels the set partial and returns what the others authorized rather than failing. That is the designed behavior, so an occasional "partial" label is not an incident by itself.
Expect bounded navigation. A hierarchical provider may require Kaizen to browse its root and retry search inside returned containers. Kaizen caps depth, requests, page size, and per-surface time. A partial result can therefore mean a large hierarchy exceeded a live-turn bound as well as a provider being temporarily unavailable; use a private sync for exhaustive recurring retrieval.
Security notes
Connector content is untrusted text. It may contain instructions aimed at the model. Kaizen's defense is structural: connector content arrives as evidence and cannot grant a tool, widen a scope, approve an action, or supply an identity.
Exposing a connector as a tool widens what an agent can reach. It does not widen what any member can see — the provider still applies that member's access.