Apps

An app is an installed instance of a blueprint within an organization. While a blueprint defines what an application can do, an app is a running instance that does it — with its own connections, data, conversations, and service accounts.

Installing an app

When you install a blueprint, the platform:

1. Resolves the blueprint — finds the published version (directly or via an artifact from the marketplace).
2. Creates the app instance — scoped to your organization and space, linked to the specific blueprint version.
3. Provisions service accounts — creates identities in the identity provider for the app and each of its agents. These accounts allow agents to act in conversations and execute operations.
4. Creates organization membership — the app's service accounts are added as members of your organization with appropriate roles.

The resulting app shares the same UID as the blueprint, but its runtime data is entirely isolated to your organization.

App structure

Organization
└── Space
    └── App (installed)
        ├── uid                     → same as blueprint UID
        ├── blueprintId             → specific published version
        ├── serviceAccount          → identity for the app
        ├── agentServiceAccounts[]  → identities for each agent
        └── runtime data
            ├── connections         → authenticated credentials
            ├── collection records  → data in tables
            ├── conversations       → messages and threads
            ├── tasks               → execution history
            └── event subscriptions → active listeners

Multi-tenant isolation

Multiple organizations can install the same blueprint. Each gets:

• Its own app instance with a unique installation
• Its own service accounts in the identity provider
• Its own runtime data — conversations, records, connections, and tasks are never shared across organizations
• Access to the same actions, agents, and flows defined in the blueprint

This means a blueprint author can publish once, and many organizations can use it independently.

Calling actions

The primary way to interact with an app is by calling actions. Every action call goes through a single endpoint:

POST /v1/apps/{appUid}/actions/call

The request specifies:

• actionIdentifier — which action to invoke (for example, [email protected]/actions/uact_listFiles)
• connectionId — (optional) which connection credentials to use
• input — the action's input data
• waitForResult — whether to wait for completion or get a task ID for async polling

The platform resolves the action, determines whether it's a native service operation or an integration API call, creates a task for tracking, and executes it.

Synchronous vs. asynchronous execution

Actions support two execution modes:

Updating apps

When a new blueprint version is published:

• Publisher's own apps are updated automatically to the new version.
• Client apps (other organizations that installed the blueprint via the marketplace) are updated through the artifact distribution system.
• New agents added in the update get new service accounts provisioned.

The update process ensures continuity — existing runtime data (connections, records, conversations) is preserved.

Related concepts

• Blueprints — the templates that apps are installed from
• Actions — how to invoke operations through apps
• Organizations and Spaces — the multi-tenant structure apps live in
• Connections — managing credentials for external services