Download the PHP package vested-ai/connector-sdk-php without Composer

Vested AI Connector SDK (PHP)

Connect any PHP service to the Vested AI platform. The SDK opens a long-lived gRPC stream to the hub, declares agents and tools over that stream, and dispatches tool calls to your handler code — no polling, no webhook setup, no managing your own LLM client. The hub handles model selection, prompt composition, and conversation state; your connector owns the business logic.

Install

Or pull the pre-built Docker image (PHP 8.3 + Swoole bundled):

30-Second Example

The scanner maps file path to class name, PSR-4 style, so one class per file named after it — a class declared in bootstrap.php is never discovered.

Declarations

Beyond agents and tools, a connector can declare two optional things on Register. Both follow the same contract: declare nothing and nothing changes. A connector that declares neither is untouched by both features.

You may declare both, and the combination needs one thing set up on the platform side. Declaring a credential_schema used to make a connector permanently un-extractable; that is no longer true, and if you have read that here before, this paragraph is the correction.

A connector that declares a credential_schema is schema-extracted as a named person: the platform holds an automation user for the connector and the hub resolves that user's sealed credential for the extraction, exactly as it would for a tool call. Without one, extraction is refused with 403 credential_gated, "connector declares per-user credentials; schema extraction has no acting user to gate as" — extraction is system-initiated, so with nobody named there is no credential to seal for.

Nothing you do in the SDK changes which way that goes: it is an operator setting on the platform, not a field on Register. What you should know is the shape of the failure if it has not been done. The refusal talks about credentials on the schema path and nothing points back at your Register, so it reads like a bug in extraction. The same applies in reverse: putting an already-extracted connector behind per-user credentials stops its extraction on the day you deploy it, until an automation user is named. Ask for that to be set up first, and the gap never opens.

#[CredentialSchema] — per-user credentials

Put #[CredentialSchema] on your UserCredentialHandler, one #[CredentialField] per field of the form the platform renders. Declaring a schema is what gates this connector's tools on the calling user having valid credentials.

The handler needs a private key to open sealed envelopes — set VESTED_CREDENTIAL_PRIVATE_KEY (or ..._FILE), or pass the PEMs as the second argument. Registering a handler without one throws at startup rather than failing every credential check later. Full guide: Per-user credentials.

#[RelationalSource] — expose a database to schema extraction

Put #[RelationalSource] on your RelationalSchemaProvider. Declaring one is what makes the connector's database visible to the platform's schema extraction; a connector that declares none is never extracted.

Four things worth knowing:

• The declaration is cross-checked. Both tool keys must name tools this connector declares, and sqlArg must match an argument of the query tool exactly, including case. Nothing downstream catches a typo: the platform would govern a key nothing answers to while the real tool ran ungoverned, which is why it is refused at startup instead.
• The describe tool must extend PaginatedToolHandler. A catalog does not fit one response, and only a paginated handler declares result_kind = rowset.
• catalogFingerprint() must detect column-level change, not just table-level. Hashing table names alone misses a field added to an existing table — the normal shape of a backward-compatible deploy — and would leave the platform believing the schema is unchanged. It is called live on every Register, so there is no fingerprint to supply by hand.
• No PHP connector implements a provider yet. The interface is here so the contract is identical across languages; the first implementation will be MySQL for Magento.

Multiple scopes need a defaultScope

scopes() can expose more than one database/company (a Magento connector spanning "production" and "erp_middleware_production", or a Business Central connector spanning several companies). When it does, an unqualified table name in a query is ambiguous — the platform cannot guess which scope it belongs to — so #[RelationalSource] takes a defaultScope:

Two invariants are enforced at bootstrap — on ConnectorApp::build(), before the worker ever dials the hub — not at query time:

• More than one scope with no defaultScope throws InvalidArgumentException. A single-scope (or scope-less) source may leave defaultScope blank.
• A defaultScope naming something scopes() never returns throws InvalidArgumentException too.

scopes() runs synchronously, inline, during that same bootstrap — before the worker ever dials the hub. There is no async variant and no timeout around it. Keep it cheap and I/O-free: return a declared/constant list (or one already held in memory), never a live catalog query. A database round trip in there blocks worker startup on that query, and a slow or unreachable database delays or fails the boot — worse than the stale-schema risk catalogFingerprint()'s live read exists to avoid. If you need a live, per-deployment scope list, enumerate it elsewhere (in describe(), or your own warm-up path) — not in scopes().

This is deliberately the same failure shape as the missing-credential-key check above: refuse on the connector author's own deploy, with a message that names the fix, rather than let a model's query resolve an unqualified table name against the wrong database in production.

defaultScope decides only what an unqualified name means, and nothing else: a qualified scope.table reference is never re-pointed at the default, and a query joining across two scopes is unaffected by it — each side of the join still resolves in its own scope.

What This Is

A connector is a long-lived worker process that registers one or more agents with the Vested AI hub. Each agent carries a model selection, a set of instruction blocks, and a set of tool definitions. Admins can override instruction bodies and disable tools in the admin UI; the connector's declared baseline is the floor that overrides are layered on top of. The hub routes LLM tool calls back to the connector over the same stream; the connector dispatches them to your handler code and returns results.

This differs from writing your own LLM client. The connector does not call the LLM directly. It registers capability and responds to callbacks. Prompt composition, model routing, conversation history, streaming to end users — all of that lives in the hub. The connector's surface area is: "declare what agents exist, implement what the tools do."

Documentation

License + Status

MIT. Current release: v0.11.0 (Swoole runtime, supervisor reconnect, PDO pool guidance, connector-declared tool sensitivity, #[CredentialSchema] and #[RelationalSource] Register declarations, #[RelationalSource] scopes/defaultScope with a bootstrap throw, #[Tool(agentKey: [...])] shared across agents, #[RelationalSource(paramsArg: ...)] bind parameters with the ParameterizedSql normaliser helper). Production-ready; used in the alsaif Magento connector.

Other language SDKs

Same wire protocol, same hub — all four SDKs are at feature parity (including connector-declared tool sensitivity):

• Python — PyPI vested-connect-sdk
• Node.js — npm @vested-ai/connector-sdk
• C# / .NET — NuGet VestedAI.ConnectorSdk