For developers
A workspace,
defined in code.
Connect your systems, give agents shared context, and automate work your team can review. Follow one support ticket to see how the pieces fit together.
An illustrative example
A support ticket, end to end.
Meridian Labs cannot sign in before renewal. Lobu links the ticket to the company, runs an assessment and gives the team a response to review.
Start with a definition, then follow how it is connected and used. Select a diagram box to explore its examples.
Start with Connect01Connect
Give agents access to your systems.
Define a connector once, connect an account, then choose its feeds and operations. The same contracts cover an API, a database, a browser session or a paired computer.
- Connector definition Connection + authconfigure an account
- Connector definition Subscriptionsdeclare signals
- Connector definition Connector operationsdeclare operations
A connector defines capabilities. A connection supplies an account and settings. A feed selects data; an Automation decides when that data should cause work.
Connector definition
The connector is reusable TypeScript: its definition names the integration, declares authentication and describes each feed and action. Feed handlers read or collect data; action handlers call the source. A connection supplies the account-specific settings later.
connectors/supportdesk.connector.ts
This is the shape of an authored connector module. The Supportdesk API is illustrative: implement the typed supportApi adapter for your provider. The default export is a ConnectorRuntime class; Lobu extracts its definition and invokes the appropriate handler.
import {
ConnectorRuntime, type RuntimeConnectorDefinition,
type FeedReadResult, type SyncCredentials,
} from "@lobu/connector-sdk";
type Checkpoint = { after: string };
type Options = { queue: string };
type Ticket = {
id: string; title: string; body: string; updatedAt: string;
verifiedAccountDomain: string;
};
declare const supportApi: {
read(input: {
queue: string; query?: string; limit?: number; cursor?: string;
credentials: SyncCredentials | null;
}): Promise<FeedReadResult>;
changes(input: {
queue: string; after?: string; credentials: SyncCredentials | null;
}): Promise<{ tickets: Ticket[]; checkpoint: Checkpoint; more: boolean }>;
};
export default class Supportdesk
extends ConnectorRuntime<Checkpoint, Options> {
readonly definition: RuntimeConnectorDefinition<Checkpoint, Options> = {
key: "demo.support", name: "Supportdesk", version: "1.0.0",
authSchema: { methods: [{
type: "oauth", provider: "support",
requiredScopes: ["tickets:read", "tickets:write"],
}] },
automationEvents: [{
key: "ticket.updated", label: "Ticket updated", resourceType: "ticket",
defaults: { execution: "window", activeRun: "coalesce" },
}],
feeds: {
tickets: {
key: "tickets", name: "Support tickets",
configSchema: {
type: "object", required: ["queue"],
properties: { queue: { type: "string" } },
},
read: async (ctx) => supportApi.read({
queue: ctx.config.queue, query: ctx.query,
limit: ctx.limit, cursor: ctx.cursor,
credentials: ctx.credentials,
}),
},
},
};
}
- key identifies this connector across accounts; version identifies the code installed for it.
- configSchema describes the settings of each tickets feed. ctx.config receives that feed’s queue; the account grant arrives in ctx.credentials.
- read is executable code. The catalog declares ticket.updated; the sync handler below emits it. Add actions in the same definition, and implement the provider adapter and OAuth provider registration.
Illustrative Supportdesk adapter on the current ConnectorRuntime contract.
Reference02Model
Define the objects your business works with.
Write entity types, relationship rules and event contracts in TypeScript. Then map source records to those identities so people and agents can follow a company from its current state to its supporting evidence.
- Entity types Relationshipsconstrain allowed pairs
- Entity types Source attributionsupply identity namespaces
- Entity types Payloads + attachmentsdefine event contracts
The schema defines what an object can contain. Relationships connect objects. Events record what happened and which objects it concerns.
Entity types
An entity type defines a business object: its properties, required values and the event kinds people can inspect on its records. Define it once in schema.ts, then register the returned handle in lobu.config.ts.
schema.ts
This project module defines Company and Person records, the events that can describe a company, and an ownership relationship. Import its exports into lobu.config.ts and list them under entities and relationships.
import { defineEntityType, defineRelationshipType } from "@lobu/cli/config";
export const company = defineEntityType({
key: "company",
name: "Company",
required: ["domain", "risk"],
properties: {
domain: { type: "string" },
risk: { type: "string", enum: ["healthy", "at_risk"] },
},
eventKinds: {
ticket: {
description: "A support interaction about this company.",
metadataSchema: {
type: "object",
properties: {
account_domain: { type: "string" },
ticket_id: { type: "string" },
},
required: ["account_domain", "ticket_id"],
},
},
summary: {
description: "Current account assessment with evidence.",
metadataSchema: {
type: "object",
properties: {
account_domain: { type: "string" },
risk: { type: "string", enum: ["healthy", "at_risk"] },
},
required: ["account_domain"],
},
},
observation: { description: "A material change in account risk." },
},
});
export const person = defineEntityType({ key: "person", name: "Person" });
export const ownerOf = defineRelationshipType({
key: "account-owner-of",
name: "Account owner of",
rules: [{ source: person, target: company }],
});
- properties and required describe current record data; each Company has a domain and one of the two risk values.
- eventKinds names the facts attached to a Company. Each metadataSchema validates the metadata of that event kind.
- Register company and person under defineConfig.entities and ownerOf under defineConfig.relationships. lobu apply installs the definitions.
Project definition. The ticket kind extends the account-health example with a structured support-event contract.
Reference03Automate
Define when work runs and what it produces.
An Automation ties together a trigger, named sources, instructions or TypeScript, and an output contract. Register it once, then let Lobu run it or let an external agent claim and complete its pending work.
- Define the Automation Sources + windowsstart bounded work
- Define the Automation Executionstart an immediate turn
A feed checkpoint tracks source collection. An Automation mark tracks completed work. A page cursor continues one read. Keep these separate so collection, analysis and retries can progress independently.
Define the Automation
Put the whole job in one definition: who runs it, what wakes it, which data it reads and what it writes. The same account-health Automation can wake on a weekday schedule or on the connector’s ticket.updated event.
automations/account-health.ts
This project module returns an Automation definition. lobu.config.ts passes it the analyst agent and support connection, then registers accountHealth(analyst, support) in defineConfig. The handles are resolved to installed workspace resources when the project is applied.
import {
defineAutomation, context, every, on, type Agent, type Connection,
} from "@lobu/cli/config";
import { company } from "../schema";
export const accountHealth = (agent: Agent, support: Connection) =>
defineAutomation({
slug: "account-health",
agent,
skills: ["account-health"],
prompt: "Assess account risk; preserve evidence and summarize changes.",
triggers: [
every("0 9 * * 1-5", { timezone: "Europe/London" }),
on("demo.support", "ticket.updated", {
connection: support,
execution: "window",
}),
],
sources: {
tickets: "SELECT id, payload_text, metadata FROM events WHERE origin_type = 'ticket' AND connector_key = 'demo.support'",
accounts: context(
"SELECT id, name, metadata FROM entities WHERE entity_type = 'company'",
),
},
outputs: {
accounts: { entity: company, key: ["domain"] },
summaries: { event: "summary", key: ["account_domain"] },
observations: { event: "observation" },
},
});
- triggers decides when to run. every sets the analysis cadence; on subscribes to the event declared by the support connector.
- sources names the evidence and reference context supplied to the run. outputs defines the arrays the result must contain.
- agent selects the owner and execution context. skills pins the account-health instructions from that agent’s skill library.
Project definition. The support feed can collect every 15 minutes while the Automation follows its own schedule or subscription.
Reference04Interact
Define the interface people use.
Write React components, register views, and bind them to records or events. Route chat messages and interface actions into the same Automation system.
- React components View registrationcompose registered modules
- View registration Hierarchical navigationgroup view keys
- View registration Declared interactionsdeclare view actions
React modules and event templates are available today. The navigation tree is a design proposal; every view and action still uses the current viewer’s authorized context.
View registration
A view module declares its key, placement and data query. Add its file to the project’s views list so lobu apply bundles it and makes it available in the matching record, collection, event or workspace context.
views/account-health.tsx
A record view answers a different question from the event view: what is the latest assessment for this company? The host supplies the company ID, and the query requests its current summary.
import { defineView, useScope, useQuery, tool } from "@lobu/views";
import {
AssessmentCard, type Assessment,
} from "./components/AssessmentCard";
export const view = defineView({
key: "account-health",
attach: [{ record: "company" }],
});
export default function AccountHealth() {
const { entity } = useScope();
const read = useQuery<{ content: Assessment[] }>(
typeof entity === "number" ? tool("read_knowledge", {
entity_id: entity,
semantic_type: "summary", sort_by: "date", limit: 1,
}) : null,
);
const assessment = read.data?.content[0];
if (read.loading) return <p>Loading…</p>;
if (read.error) return <p role="alert">{read.error}</p>;
return <>
{assessment
? <AssessmentCard value={assessment} />
: <p>No summary yet.</p>}
{read.truncated && <p>Partial result. Open the source record.</p>}
<button onClick={read.refetch} disabled={read.loading}>Refresh</button>
</>;
}
- key gives the module a stable identity. { record: "company" } offers it on company record pages.
- The query is parked until a numeric entity ID is available. It reads one current summary through the host’s permission checks.
- The same AssessmentCard is reused here and on the event page; only the parent’s query and scope change.
Complete TSX module using the current record attachment contract. Add this file to the project’s views list below.
ReferenceEnterprise controls
Control who can read, act and approve.
- Identity
- The authenticated person or run, selected workspace and assigned execution owner establish the identity. A label or agent ID does not impersonate another caller.
- Access control (ACL)
- Workspace permissions, connection access and supported source restrictions determine available context. Connection metadata visibility is separate from source access.
- Actions
- Read, operate and administer are distinct permissions. The Run SDK executes permitted calls under the current identity; it does not bypass policy.
- Data changes
- Entity field policy, relationship rules and connector operation policy apply at their own boundaries. A view's controls do not provide a general write credential.
- Approvals
- Configured policy can defer work for human approval. Review the exact pending request and distinguish a decision from the later execution outcome.
- Audit
- Source attribution, event history, run outputs and operation receipts connect intent to results. Inspect retries, missing source continuity and pending work explicitly.
The complete example
Browse the customer-health project.
Six files for the illustrative Meridian Labs example. Supply your provider adapter and OAuth registration.
lobu.config.tsimport {
defineConfig, defineAgent, defineConnection, defineAuthProfile,
connectorFromFile, skillFromFile, viewFromFile, secret,
} from "@lobu/cli/config";
import { company, person, ownerOf } from "./schema";
import { accountHealth } from "./automations/account-health";
// #region connect
const supportConnector = connectorFromFile(
"./connectors/supportdesk.connector.ts"
);
const supportAccount = defineAuthProfile({
slug: "support-account", connector: "demo.support",
authKind: "oauth_account",
});
const support = defineConnection({
slug: "support", connector: "demo.support",
authProfile: supportAccount,
feeds: [{
feed: "tickets", name: "Enterprise tickets",
config: { queue: "enterprise" },
schedule: "*/15 * * * *", // Optional collection cadence
}],
});
// #endregion
const analyst = defineAgent({
id: "account-health", dir: "./agents/account-health",
skills: [skillFromFile("./agents/account-health")],
providers: [{ id: "claude", key: secret("ANTHROPIC_API_KEY") }],
});
export default defineConfig({
org: "meridian-demo",
entities: [company, person], relationships: [ownerOf],
connectors: [supportConnector], authProfiles: [supportAccount],
connections: [support], agents: [analyst],
automations: [accountHealth(analyst, support)],
views: [viewFromFile("./views/account-health.tsx")],
});
Apply
Review. Then run.
From your project directory, review the diff and prerequisites, then apply the definitions and confirm the CLI plan.
lobu apply --dry-run
lobu applyCall your workspace.
After applying the project, agents can call Lobu through MCP and your application can use @lobu/client. Read live data and shared memory, start Automations, or request connector actions with the caller's workspace permissions.
Agent via MCP · query_sdk. Lobu runs this TypeScript and supplies client. Replace the example IDs with ones discovered in your workspace.
export default async (_ctx, client) => {
const workspace = await client.org("meridian-demo");
const live = await workspace.feeds.readMany({
reads: [{ feed_id: 71, query: "status:open", limit: 20 }],
});
const memory = await workspace.knowledge.search({
query: "renewal risk", entity_id: 42, include_content: true,
});
return { live, memory }; // Check each feed's ok / next_cursor.
};