Apps and Data Flow Notebooks
Open Conversation → Apps for App notebooks, or Data Flows → Notebooks for data notebooks. An administrator authors notebooks in the selected tenant and project. A notebook combines explanations, configuration, retained examples, SQL and tests. Saving creates a draft revision.
Start an App structure draft
In Conversation → Apps, choose Add, enter a name and notebook key, then choose a starting template under App structure:
- Contract folder → database → API
- Slack → contracts → database comparison
- Weekly Hunter + Apollo → unique customers
Select a template and click Use template to apply it. Selecting an option alone does not change the draft. Applying a template replaces the unsaved draft, including its notes and files. Based on template shows the applied starting template; Current app components shows the actual components and their dependencies, including after saving and reopening. Older drafts without recorded template information still show their current components.
Check configuration lists missing settings for each component, such as a folder connection, document template, flow, customer identity fields or schedule timezone. These settings can remain incomplete while you save a draft.
Save and reopen your draft
- Enter a Name and Notebook key. The key starts with a lowercase English letter and contains only lowercase letters, numbers and underscores, for example
contract_processing. - Click Save draft and wait for the confirmation showing the app name and revision number. If a field is invalid, an error explains what to correct; your unsaved edits remain in the editor.
- The saved app remains selected in the list on this page. Select it later to reopen it in the same tenant and project. Each subsequent save creates a new revision.
Notes are optional descriptions for people reading the app. They do not execute instructions or configure components. You can leave their text empty or remove the Note. Keep the default cell key and section under Advanced note settings unless you need to change them.
If you edit Automation definition, use Validate and apply before saving. Testing, publishing and advanced tools are in a separate expandable section. Saving a draft does not publish or run it.
These are design templates. They do not create a database, enable a schedule, send messages or run a composed app. Completing the settings does not certify connections or make the app executable. The visual drag-and-drop designer and the composed execution path are still being developed. Existing notebook stages retain their current test controls.
Test a notebook
- Select your tenant/project and notebook. Save any pending edits.
- Choose Run tests, Run samples, Run section, or the Run button on one stage. Required dependencies run first.
- Expand the run history. Inspect the actual queued, running, succeeded or error state. A failed prerequisite blocks downstream work.
- Open Computed output to inspect typed rows and page through them. A complete sample is required for verification.
- Inspect each comparison and its differences. Missing references, ambiguous keys or incomplete coverage cannot pass.
SQL data stages use a bounded retained table named sample. Configured transforms use the same data transformations as the existing Flow designer. These sample runs do not read customer sources or write customer destinations. Document extraction uses a saved template and an authorized retained parsed document; label examples first and review extraction output.
An edit makes prior results stale. Model, parser, comparison and execution changes can also invalidate evidence. Run affected checks again before requesting activation.
When a data stage uses an extraction table, the run waits for you to accept the extraction result in Documents Automation → Monitoring. It then uses the table's declared grain, keys, types and currency fields. Correcting that result invalidates downstream evidence; run the checks again.
For a Channel test cell, configure the test destination, case revision and assigned reviewer, then choose Send test notification. Expand the run history to see the queued and provider-accepted states, and use the notification history to check the receipt and reviewer action. Only configured test destinations are allowed.
Review proposed edits
Expand Proposed notebook edits. If prompt generation is available, describe the change and choose Propose edit. Select a pending proposal, inspect its before/after diff, then choose Accept reviewed diff or Reject diff. Acceptance creates a new draft revision and requires new tests. A proposal cannot approve or activate itself.
If prompt generation is unavailable, you can still review pending proposals or edit a draft directly. Generated edits are restricted to declared resources and approved sample/reference files; unavailable connectors or fields must be resolved before continuing.
Activate or restore a tested version
- Run the declared tests for the saved revision. Document extraction also requires a current passed golden pilot.
- Expand Tested versions and activation and choose Request version review.
- The notebook owner reviews the exact revision and chooses Approve exact version.
- Choose Activate approved version. Changes since testing or approval block activation.
- Use Run active version on retained samples to inspect the approved version independently of later draft edits.
Critical failures cannot be overridden. An owner can override a verified standard test only by recording a reason and residual risk. An unverified result cannot be overridden.
To restore a previous tested version, enter a reason and choose Restore this version. Restoration preserves case and ledger history. A critically paused version cannot be restored; correct the issue, rerun tests and approve a new version.
An active version remains tied to its tested source. A critical mismatch pauses future runs. If test-channel monitoring is configured, a failure alert is queued. Remote acceptance of an email or chat message does not prove delivery to its recipient.
Pilot and availability
Use 20 representative historical documents with separate calibration and unseen holdout examples. Agree on matching keys, currency, record grain, tolerances and required accuracy before the pilot. The provided synthetic examples check software behavior; they do not certify customer accuracy or delivery.
Customer PO writes, arbitrary live notebook execution and automatic financial business actions are not enabled by saving or activating a notebook. Existing Flow designer links/history remain available. A migrated sample comparison does not activate the legacy schedule or duplicate it.
For document setup, labeling and result review, see Documents Automation.
Tenant repository setup
Tenant administrators configure a private GitHub or Bitbucket Cloud repository in Settings → Git repository (/settings?tab=repository). Super Admin can select the tenant in the panel.
- Choose a provider: GitHub or Bitbucket Cloud.
- Connect your account: choose the provider's sign-in button. GitHub displays a code to enter on its authorization page; AgentData connects automatically after approval. Bitbucket opens its consent page and returns to the selected tenant. For token-based access, expand Use an API token instead, enter the token (and Atlassian email for Bitbucket), then choose Load repositories.
- Choose a repository: repositories load automatically after connection, showing their account or workspace. Choose an existing private repository, or Load more to see further results across accessible accounts and Bitbucket workspaces. Public repositories are shown but cannot be selected for tenant definitions.
- To create one, choose Create a new repository, select the account or workspace, enter a name, and choose Create private repository. Review the created repository before saving.
- Branches load automatically for the selected repository, with its default branch selected. Choose another branch if needed. Expand Manual settings to enter an account/workspace, repository, branch or AgentData directory yourself. For a new repository in another organization, its owner can also be entered there.
- Choose Test connection, then Save tenant repository. AgentData initializes its template under the chosen directory and queues the current definitions for Git commits. New repositories receive the template when created. Review Repository sync until pending definitions become Committed.
Choose Edit repository settings to change the binding or reconnect credentials. If browser sign-in is unavailable, ask your platform Super Admin to enable it in Admin → Git integrations. The API token option remains available. Super Admin can enter the Bitbucket consumer key and secret there and copy the prefilled callback URL into Bitbucket; changes take effect immediately. Credentials are encrypted and never displayed again. A concurrent settings change requires reloading before saving.
Definition folders and automatic commits
AgentData keeps a versioned definition mirror in your tenant repository. The default root is agentdata/; Manual settings lets you choose a different directory.
| Folder | Contents |
|---|---|
semantic/entities/<entity-id>/ | Semantic metadata, Cube YAML and dbt YAML |
semantic/models/<model-id>/ | Named model selections and layouts |
apps/projects/<project-id>/<app-key>/ | App manifest, notebook source and authored supporting files |
flows/projects/<project-id>/<flow-key>/ | Data Flow manifest, notebook source and authored supporting files |
flows/legacy/<staging-id>-<flow-id>/ | Legacy flow configuration and schedule |
pipelines/<pipeline-id>/ | Pipeline dependency graph and cadence configuration |
schemas/, sql/migrations/, sql/queries/, tests/ | Reserved locations for governed schema, SQL and validation definitions |
For a previously connected repository, choose Initialize template and sync definitions. Initial sync includes existing semantic metadata and latest generated YAML, current apps/data flows, legacy flows/schedules and pipelines. Copied semantic entities without stored YAML receive generated YAML in the export. Staging databases must be reachable during initial legacy-flow export; retry initialization after reconnecting an offline connector.
Once enabled, saved definition changes are queued for AgentData commits. Repository sync shows pending changes, confirmed commits and items needing attention. A successful save inside AgentData is distinct from a confirmed Git commit. Provider failures retain the queued definition for retry. Deletions remove the current managed files; earlier Git commits retain their history. The first export is a baseline; earlier AgentData versions remain available in their existing histories.
If the repository changes outside AgentData, sync pauses. Choose Review repository changes, open the exact commit in your Git provider and review it. Continuing will commit queued AgentData definitions on top of that commit and can replace external edits to the listed managed files. Unrelated files remain. Further repository changes require another review.
Credentials, customer table rows, document binaries and execution outputs are excluded. Use references for sensitive samples in authored notes/tests. Existing notebook workspace bindings and histories remain separate. Repository sync does not activate apps, run pipelines or apply database migrations. Governed schema/migration publication is still a separate delivery step; the reserved folders do not enable it. Before switching repositories with pending changes, complete or review their sync so retained changes stay with their original repository.