# ThinkPlatform documentation Guides and reference for using, developing with, and administering ThinkPlatform. - [ThinkPlatform documentation](/overview.md) (User guide › Get started): Use ThinkPlatform, automate your work, and manage access to your organization. - [Get started with ThinkPlatform](/guides/get-started/quickstart.md) (User guide › Get started): Sign in, choose a project, and save your first document. - [Sign in](/guides/get-started/sign-in.md) (User guide › Get started): Access ThinkPlatform with your organization's account. - [Organizations and projects](/concepts/organizations-and-projects.md) (User guide › Get started): Understand how sign-in, membership, and project access fit together. - [Agents, tasks, flows, and workspaces](/concepts/workflows.md) (User guide › Get started): Choose the right place for a request, a repeatable workflow, or scheduled work. - [Navigate and find resources](/guides/navigation-and-search.md) (User guide › Use ThinkPlatform): Use global search and local filters to find work in your project. - [View and edit a canvas](/guides/canvas/view-and-edit.md) (User guide › Use ThinkPlatform): Create a document and edit canvas pages where you have permission. - [Upload and download files](/guides/files/upload-and-download.md) (User guide › Use ThinkPlatform): Attach a file to an agent chat and retrieve available results. - [Run a flow and inspect results](/guides/flows/run-and-results.md) (User guide › Use ThinkPlatform): Test a graph or code flow and review its output. - [Share a canvas page](/guides/sharing-and-permissions.md) (User guide › Use ThinkPlatform): Choose which projects can access a page and verify the recipient's access. - [Create and configure an agent](/guides/agents/create-and-configure.md) (User guide › Agents and tasks): Set up an agent and test it with a small request. - [Chat with an agent](/guides/agents/chat-and-results.md) (User guide › Agents and tasks): Ask an agent to help and inspect its response and files. - [Add project skills to an agent](/guides/agents/project-skills.md) (User guide › Agents and tasks): Upload a skill to a project and attach it to an agent. - [Create and manage a task](/guides/tasks/create-and-manage.md) (User guide › Agents and tasks): Assign work to an agent or team and follow it in the task view. - [Approvals and recovery](/guides/tasks/approvals-and-recovery.md) (User guide › Agents and tasks): Review an agent's approval request and check work after an interruption. - [Review your inbox](/guides/tasks/inbox.md) (User guide › Agents and tasks): Find notifications and return to their source. - [Explore files and data assets](/guides/data/files-and-data-assets.md) (User guide › Data and machine learning): Browse project files and inspect available lakehouse assets. - [Work with tables and vector stores](/guides/data/tables-and-vectors.md) (User guide › Data and machine learning): Manage structured records and prepare documents for vector indexing. - [Training and models](/guides/data/training-and-models.md) (User guide › Data and machine learning): Inspect training bundles and model assets in your project. - [Run a training job](/guides/data/training-jobs.md) (User guide › Data and machine learning): Choose a dataset and training configuration, then inspect the job and its output. - [Deploy a model](/guides/data/model-deployment.md) (User guide › Data and machine learning): Choose a cloud or edge target and verify the deployment. - [Schedules and webhooks](/guides/automation/schedules-and-webhooks.md) (User guide › Automation): Configure scheduled work and outbound event notifications. - [Receive events with webhook endpoints](/guides/automation/webhook-endpoints.md) (User guide › Automation): Configure an authenticated inbound webhook for an agent or flow. - [Operate agent workspaces](/guides/operations/workspaces.md) (User guide › Operations): Inspect and manage the runtimes used by agents and workspace-backed flows. - [Open a published web app](/guides/operations/hosted-apps.md) (User guide › Operations): Use a project application through ThinkPlatform and understand its data permissions. - [Operate cloud and edge resources](/guides/operations/cloud-and-edge.md) (User guide › Operations): Inspect container apps and edge devices, and verify changes to their runtime state. - [Registry and modules](/guides/operations/registry-and-modules.md) (User guide › Operations): Find container images and inspect project integrations. - [Troubleshoot access and errors](/guides/troubleshooting/access-and-errors.md) (User guide › Fix a problem): Diagnose missing projects, save conflicts, indexing, runtime readiness, and uncertain runs. - [Contact support](/guides/get-started/support.md) (User guide › Fix a problem): Review an inquiry before sending it and distinguish acceptance from confirmed storage. - [Build and automate with ThinkPlatform](/developers/overview.md) (Developers › Get started): Choose the CLI, Python SDK, or agent guidance for your ThinkPlatform workflow. - [ThinkPlatform CLI](/cli/get-started/overview.md) (Developers › CLI › Get started): Install the CLI, connect to your project, and read your first Canvas page. - [Installation](/cli/get-started/installation.md) (Developers › CLI › Get started): Prepare a supported Python environment and install the ThinkPlatform CLI and SDK. - [Authentication](/cli/get-started/authentication.md) (Developers › CLI › Get started): Choose a sign-in method, save a connection profile, and verify your identity and project context. - [Upgrade to client 0.6.134](/cli/guides/upgrading.md) (Developers › CLI › Get started): Update the CLI and SDK while keeping your profiles and adapting older Apps commands. - [Connect a coding agent](/cli/guides/agent-setup.md) (Developers › CLI › Guides): Connect an agent to ThinkPlatform documentation and install bundled CLI guidance. - [Choose an organization and project](/cli/guides/context.md) (Developers › CLI › Guides): Save your organization and project once, then use short commands. - [Read and update a Canvas page](/cli/guides/canvas-pages.md) (Developers › CLI › Guides): Find content, export it, and make a verified page edit. - [Publish a web app](/cli/guides/apps.md) (Developers › CLI › Guides): Build a container app from source, publish it behind ThinkPlatform authentication, and open it from Canvas. - [Inspect a shared database table](/cli/guides/database-tables.md) (Developers › CLI › Guides): Discover a table, inspect its schema, and retrieve a small sample of rows. - [Upload and inspect Data Lake files](/cli/guides/files.md) (Developers › CLI › Guides): Upload local files, inspect paged listings, and resolve project Data Lake paths. - [Run work and inspect its outcome](/cli/guides/execution.md) (Developers › CLI › Guides): Keep Flow runs, Agent tasks, and MLOps jobs distinct while checking status and results. - [Discover and call an API operation](/cli/guides/api-requests.md) (Developers › CLI › Guides): Use the deployed OpenAPI schema to resolve a request before sending it. - [Capture CLI output in a script](/cli/guides/automation.md) (Developers › CLI › Guides): Check exit status, preserve diagnostics, and consume structured read results. - [Troubleshoot a failed command](/cli/guides/troubleshooting.md) (Developers › CLI › Guides): Diagnose configuration, authentication, permission, and request errors, and check whether interrupted work completed. - [CLI Reference](/cli/reference/commands.md) (Developers › CLI › Reference): Short commands for everyday work, with detailed options for people and agents. - [Python SDK](/python-sdk/overview.md) (Developers › Python SDK › Get started): Read and update ThinkPlatform resources from synchronous Python applications. - [SDK authentication](/python-sdk/authentication.md) (Developers › Python SDK › Get started): Choose explicit credentials, environment settings, or a CLI profile. - [Resource workflows](/python-sdk/resources.md) (Developers › Python SDK › Guides): Read project resources, update a page title, and page through data lake files. - [Database tables and rows](/python-sdk/database.md) (Developers › Python SDK › Guides): Inspect shared database tables, query sample rows, and update a row. - [Errors and retries](/python-sdk/errors.md) (Developers › Python SDK › Guides): Handle missing context, credential failures, connection problems, and API errors. - [Use the SDK inside a Hosted App](/python-sdk/hosted-apps.md) (Developers › Python SDK › Guides): Access project data through the current app request with narrowly declared permissions. - [Execute and inspect Lakehouse statements](/python-sdk/lakehouse.md) (Developers › Python SDK › Guides): Submit SQL, inspect completion, read result chunks, and cancel an unfinished statement. - [Python API reference](/python-sdk/api-reference.md) (Developers › Python SDK › Reference): Look up client setup, credentials, resource methods, defaults, and return types in client 0.6.134. - [Models and results](/python-sdk/models.md) (Developers › Python SDK › Reference): Look up SDK response fields, types, defaults, and JSON aliases. - [Use agent skills for developer workflows](/developers/agent-skills.md) (Developers › Agent skills): Find task guidance and examples for a coding agent working with ThinkPlatform. - [App development commands](/agent-skills/thinkplatform-app-development/references/commands.md) (Developers › Agent skills › App development): Publish container apps, connect a Canvas application page, and use request-bound SDK access. - [Data engineering commands](/agent-skills/thinkplatform-data-engineering/references/commands.md) (Developers › Agent skills › Data engineering): Inspect, transform, and validate data across the Data Lake, shared database, and Lakehouse. - [MLOps commands](/agent-skills/thinkplatform-mlops/references/commands.md) (Developers › Agent skills › MLOps): Manage datasets, training bundles, jobs, models, and inference deployments. - [Agent commands](/agent-skills/thinkplatform-agent-ops/references/commands.md) (Developers › Agent skills › Agent operations): Manage agents, teams, tasks, workspaces, memories, and skills. - [Automation commands](/agent-skills/thinkplatform-automation-ops/references/commands.md) (Developers › Agent skills › Automation): Manage schedules, hooks, webhooks, and agent follow-up tasks. - [Business workflow commands](/agent-skills/thinkplatform-business-workflows/references/commands.md) (Developers › Agent skills › Business workflows): Build workflows with database tables, files, flows, and user interfaces. - [Canvas commands](/agent-skills/thinkplatform-canvas-interface/references/commands.md) (Developers › Agent skills › Canvas): Create and update pages, build dashboards, and embed interactive interfaces. - [Edge commands](/agent-skills/thinkplatform-edge-ops/references/commands.md) (Developers › Agent skills › Edge operations): Provision devices, inspect modules and twins, and manage deployments. - [Integration and flow commands](/agent-skills/thinkplatform-integrations-and-flows/references/commands.md) (Developers › Agent skills › Integrations and flows): Discover modules, configure flows, and connect event-driven integrations. - [Lakehouse AI commands](/agent-skills/thinkplatform-lakehouse-ai/references/commands.md) (Developers › Agent skills › Lakehouse AI): Discover AI functions, run SQL, validate notebooks, and save recurring work as jobs. - [SQL and notebook patterns](/agent-skills/thinkplatform-lakehouse-ai/references/patterns.md) (Developers › Agent skills › Lakehouse AI): Apply AI functions to project data with SQL queries and notebook examples. - [Agent cost commands](/agent-skills/thinkplatform-agent-cost-analysis/references/commands.md) (Developers › Agent skills › Agent cost analysis): Inspect agent usage, task configuration, schedules, and cost attribution. - [Agent cost model](/agent-skills/thinkplatform-agent-cost-analysis/references/cost-model.md) (Developers › Agent skills › Agent cost analysis): Calculate agent costs from provider pricing, token usage, and billing data. - [Diagnose agent costs](/agent-skills/thinkplatform-agent-cost-analysis/references/diagnostic-playbook.md) (Developers › Agent skills › Agent cost analysis): Identify changes in usage, model pricing, context size, and tool activity that drive agent costs. - [Agent cost report template](/agent-skills/thinkplatform-agent-cost-analysis/assets/agent-cost-analysis-report.md) (Developers › Agent skills › Agent cost analysis): Summarize agent usage, cost drivers, and recommendations in a structured report. - [Lakehouse cost commands](/agent-skills/thinkplatform-lakehouse-cost-analysis/references/commands.md) (Developers › Agent skills › Lakehouse cost analysis): Inspect spending and investigate SQL warehouses, jobs, and dashboard refresh costs. - [Lakehouse cost model](/agent-skills/thinkplatform-lakehouse-cost-analysis/references/cost-model.md) (Developers › Agent skills › Lakehouse cost analysis): Reconcile billing and usage data, calculate cost metrics, and avoid double counting. - [Diagnose Lakehouse costs](/agent-skills/thinkplatform-lakehouse-cost-analysis/references/diagnostic-playbook.md) (Developers › Agent skills › Lakehouse cost analysis): Investigate idle compute, repeated queries, expensive scans, retries, and missing billing coverage. - [Lakehouse cost report template](/agent-skills/thinkplatform-lakehouse-cost-analysis/assets/lakehouse-cost-analysis-report.md) (Developers › Agent skills › Lakehouse cost analysis): Document Lakehouse spending, workload findings, and cost-saving recommendations. - [Plant operations commands](/agent-skills/thinkplatform-autonomous-plant-ops/references/commands.md) (Developers › Agent skills › Autonomous plant operations): Inspect plant resources, review operational state, and plan improvements. - [Administration](/admin/overview.md) (Administration › Get started): Manage access and understand the boundaries of your ThinkPlatform environment. - [Members and permissions](/admin/members-and-permissions.md) (Administration › Access and security): Invite organization members and manage access to projects. - [Security and authentication](/admin/security-and-authentication.md) (Administration › Access and security): Understand user sign-in and the separate authority of agents and workspaces. - [Data management](/admin/data-management.md) (Administration › Data): Understand where project data lives before moving or deleting it. - [Review usage and manage budgets](/admin/costs-and-budgets.md) (Administration › Costs): Inspect organization spending and configure monthly AgentOps LLM limits. - [CLI command and option metadata](/assets/cli-commands.json) --- Source: /overview.md # ThinkPlatform documentation Use ThinkPlatform, automate your work, and manage access to your organization. Find the instructions for the way you work. Start with the web app, use developer tools to automate a task, or manage your organization's access and data. **[Use ThinkPlatform](/guides/get-started/quickstart.md)** Choose a project, work with pages and agents, and find your results. **[Build and automate](/developers/overview.md)** Connect the CLI, use the Python SDK, and give an external agent a specific task. **[Manage access](/admin/overview.md)** Understand membership, permissions, authentication, and data management. **[Find help](/guides/troubleshooting/access-and-errors.md)** Resolve sign-in, access, and operation errors before trying again. ## Start with your project Your organization and project determine which resources you can see and operate. Sign in with your organizational account, then check the organization and project shown in the header before opening or changing a resource. Read [Organizations and projects](/concepts/organizations-and-projects.md) if you are unsure which project to choose or why a resource is missing. ## Find a task **[Work with pages](/guides/canvas/view-and-edit.md)** Open a page or dashboard and understand when you can edit it. **[Work with agents](/guides/agents/create-and-configure.md)** Create an agent, test its instructions, and follow its work. **[Manage files and data](/guides/data/files-and-data-assets.md)** Find project files and choose the right data workflow. **[Run a flow](/guides/flows/run-and-results.md)** Check inputs, run a flow, and review its outcome. ## Choose how to work | Interface | Start here | | --- | --- | | ThinkPlatform in your browser | [User quickstart](/guides/get-started/quickstart.md) | | CLI in your terminal or an external agent | [CLI overview](/cli/get-started/overview.md) | | Python application or notebook | [Python SDK](/python-sdk/overview.md) | | Organization or project administration | [Administration](/admin/overview.md) | For the relationship between agents, tasks, flows, and their runtimes, read [How work runs](/concepts/workflows.md). ## Get help For a missing project, denied action, or uncertain operation result, start with [Access and errors](/guides/troubleshooting/access-and-errors.md). For terminal setup or authentication problems, use [CLI troubleshooting](/cli/guides/troubleshooting.md). ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /guides/get-started/quickstart.md # Get started with ThinkPlatform Sign in, choose a project, and save your first document. Create a short document to get familiar with your project and verify that you can save work. ## Before you begin You need your organization's ThinkPlatform address and a Microsoft Entra account in its tenant. You also need access to an organization and a project, and permission to create and edit canvas pages. Signing in does not itself grant project access. ## Choose a project 1. Open the ThinkPlatform address and [sign in](/guides/get-started/sign-in.md). 2. Use the organization and project selector to select the intended organization and an existing project. 3. If you need a new project and have permission to create one, choose **Create project** in the project selector, enter a **Project name**, and choose **Create**. Select the new project. If you cannot create a project, select an existing one you can use or ask an administrator for access. ## Create your first document 1. Open **Home**. In the **Pages** panel, choose **Create root page**, then **Document**. 2. In the new page, replace **Untitled Page** with a title such as `Getting started`. Enter a harmless sample in the empty command block, such as `This is my first page.`, and press **Enter** to commit the line. 3. Wait for the page's **Saved** status. Navigate away and reopen the page from **Pages**, or reload it, and check that the title and text appear. You can now explore **AgentOps → Agents**, **DevOps → Flow**, or **MLOps → Data → Files** in the same project. See [View and edit a canvas](/guides/canvas/view-and-edit.md) for more about page editing. ## Troubleshoot If a project or **Create root page** is unavailable, check the selected organization and project and ask an administrator about access. If saving fails, preserve your unsaved text and resolve the displayed error before leaving. If creation has an uncertain outcome, check the project or page list before trying again. See [Organizations and projects](/concepts/organizations-and-projects.md) and [Access and errors](/guides/troubleshooting/access-and-errors.md). ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /guides/get-started/sign-in.md # Sign in Access ThinkPlatform with your organization's account. Sign in through your organization's Microsoft Entra account to use ThinkPlatform in your browser. ## Before you begin Have your organization's ThinkPlatform address and an account in its Entra tenant. Tenant members can sign in without a ThinkPlatform administrator registering each person first. Project visibility and permission to perform operations are separate. ## Sign in 1. Open the ThinkPlatform address supplied by your organization. 2. Follow the sign-in prompt and authenticate with your organizational account. Complete any verification required by your organization. 3. Once signed in, select the organization and project for your work. ## Verify and troubleshoot Check that the selected organization and project are correct. If sign-in fails, check the account and the message shown by your identity provider; contact your organization's administrator if you cannot complete authentication. If you can sign in but cannot see a project, ask its administrator about membership and access. See [Access and errors](/guides/troubleshooting/access-and-errors.md). ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /concepts/organizations-and-projects.md # Organizations and projects Understand how sign-in, membership, and project access fit together. An organization groups people and projects. A project is the working scope for resources such as agents, workspaces, and data. Select the intended organization and project before working with those resources. ## Sign-in and membership Signing in with your organization's Microsoft Entra account establishes who you are. Eligible tenant users may sign in automatically; sign-in alone does not grant membership in a ThinkPlatform organization or access to its projects. An administrator can invite a person to an organization and add an organization member to a project. ## Organization and project roles Organization and project roles apply at different scopes. An organization Owner has access to projects in that organization; an organization Member, Reader, or custom role does not by itself grant access to an unjoined project. A project role controls access within that project. The available actions depend on the role, resource, and configuration. ## Agents and workspaces A human user's access is separate from the authority of an agent or workspace. An agent's configured tools and approvals govern what it can do, and a workspace may use a managed identity for access to external resources. Seeing an agent does not automatically give it your permissions or access to every resource you can use. See [Members and permissions](/admin/members-and-permissions.md) to manage access and [Security and authentication](/admin/security-and-authentication.md) for sign-in and runtime identity. For programmatic access, start with the [developer overview](/developers/overview.md), [CLI](/cli/get-started/overview.md), or [Python SDK](/python-sdk/overview.md). ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /concepts/workflows.md # Agents, tasks, flows, and workspaces Choose the right place for a request, a repeatable workflow, or scheduled work. Start a conversation when you want an agent to help with a request. Use a task when the work needs a name, an assignee, and a place to return to. Use a flow when you have defined the steps or code to run. ![A person or trigger starts an agent task or flow run; configured services perform the work and return messages, files, records, or pages.](/assets/guides/workflow-map.svg) ## Choose a starting point | You want to… | Use | Example | | --- | --- | --- | | Ask a question or work through a request | [Agent chat](/guides/agents/chat-and-results.md) | Summarize a document and ask a follow-up question. | | Assign work and track its conversation and results | [Task](/guides/tasks/create-and-manage.md) | Ask an agent to prepare a weekly maintenance summary. | | Run defined steps or code with explicit inputs | [Flow](/guides/flows/run-and-results.md) | Process the selected input file and return a report. | | Run work at a chosen time or interval | [Schedule](/guides/automation/schedules-and-webhooks.md) | Prepare the summary each weekday morning. | | Start work when another system sends an event | [Webhook endpoint](/guides/automation/webhook-endpoints.md) | Start a task when an authorized service submits a request. | A schedule or webhook starts work; it is not the work's final result. Open the resulting task or run to read its output and errors. ## What an agent can use An agent combines a model and instructions with the tools, skills, and knowledge selected in its settings. [Create an agent](/guides/agents/create-and-configure.md) with a simple request first, then add the capabilities that request needs. [Project skills](/guides/agents/project-skills.md) package reusable instructions and supporting files; they are separate from the external coding-agent skills under Developers. ## Where work runs and results live A [workspace](/guides/operations/workspaces.md) provides a runtime for workspace-backed tools and code. It is not a project folder or a permanent archive. Keep the messages and outputs you need in the relevant task, page, or configured durable storage, and follow [Data management](/admin/data-management.md) before replacing or deleting a runtime. Access to the task, connected resources, and external services can differ. [Sharing and permissions](/guides/sharing-and-permissions.md) explains how to share a resource with another project. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /guides/navigation-and-search.md # Navigate and find resources Use global search and local filters to find work in your project. Select your organization and project before looking for project resources. The sidebar groups destinations such as **AgentOps → Agents**, **DevOps → Flow**, **MLOps → Data**, and **DB → Tables**. ## Search from the header 1. Click **Search...** in the header, or press **Command+K** on a Mac or **Ctrl+K** on other systems. 2. Enter a destination or resource name. Try `Flow` to find the Flow area, `Tables` for the table area, or a page or agent name you already know. 3. Select a result to open it. Check its name and project before changing it. Global search combines navigation and available resource results in the current context; results depend on access and what has loaded. A missing result alone does not prove a resource was deleted. ## Filter a list Use a local search when you are already in an area and want to narrow its list. For example, **Home → Pages** has **Search pages**, and **DB → Tables** has **Search tables**. Enter part of a known name, select the result, and clear the search when you want to see the full list again. Local filters narrow that view; they do not search every area. If you cannot find an item, clear the local filter, check the organization and project selector, and open the relevant area directly. If it remains missing, ask the project administrator to check your access. See [Organizations and projects](/concepts/organizations-and-projects.md). ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /guides/canvas/view-and-edit.md # View and edit a canvas Create a document and edit canvas pages where you have permission. Canvas pages can contain documents, dashboards, and slides. Page creation and editing require the relevant project permissions. ## Before you begin Sign in and select the organization and project containing the page. To create a page, you need permission to create pages; to edit one, you need permission to modify it. ## Create and edit a document 1. Open **Home** and find the **Pages** panel. Choose **Create root page**, then **Document**. The new page opens as **Untitled Page**. 2. Select the title and enter a name. Enter your first line in the empty command block, such as `This is my first page.`, and press **Enter** to commit it. When editing existing text, click outside the text block to commit the edit. 3. Page edits autosave. Wait for the displayed **Saved** status, then navigate away and reopen the page from **Pages**, or reload it, and verify the title and content. 4. To find an existing page, select it in **Pages** or use **Search pages**. Open it and edit its content if you have permission. ## Add a heading and list For a small meeting note, use the empty command block beneath your first line: 1. Type `/` and select **Heading**. Enter `Meeting notes`, then click outside the heading to commit the edit. 2. In an empty command block, type `/` and select **Bulleted List**. Enter `Review the plan` and press **Enter**. Enter `Share the results` in the next bullet, then click outside the block to commit it. 3. Wait for **Saved**, navigate away, and reopen or reload the page. Check that the heading and both bullets appear. An embedded database record editor may instead require **Save changes**. Use that control for record edits and check the result; the page's autosave status does not confirm an unsaved record edit. ## Troubleshoot If the creation or editing control is unavailable, check the selected project and ask an administrator about your access. If a save error appears, preserve unsaved text and resolve the error before navigating away. If page creation has an uncertain outcome, check **Pages** before creating another copy. ## Application pages and spatial widgets A dedicated application page displays a published Hosted App or HTML Dynamic UI rather than document blocks. Use [Published web apps](/guides/operations/hosted-apps.md) to open one and the [CLI publication guide](/cli/guides/apps.md) to create its page. Dashboard widgets also include **Spatial View**, **Range Summary** and **Linked Comparison** for configured spatial data. These differ from ordinary document text blocks; their data source, coordinate mapping and comparison settings determine the view. Review the widget configuration and source data before interpreting a spatial result. Creating a document alone does not configure a spatial dataset. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /guides/files/upload-and-download.md # Upload and download files Attach a file to an agent chat and retrieve available results. Agent chat can accept file attachments and display downloadable result files when the agent and project support them. ## Before you begin Choose a project and an available agent. ## Send and retrieve files 1. Open the agent chat and choose **Attach files**, or paste or drop a file into the composer where supported. 2. Add a message describing what the agent should do with the file, then send it. Wait for the upload and response. 3. Review the response and open a result file card when available. Use its download action to save a copy to your device. ## Verify and troubleshoot Check the filename and downloaded content. If upload or download fails, read the displayed error, check your connection and project access, and check whether the upload or download completed before retrying. A preview may not be available for every file; use the download action if it is offered. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /guides/flows/run-and-results.md # Run a flow and inspect results Test a graph or code flow and review its output. Flow editors provide different inputs and result views. Review the flow before running it: its steps can change data or call other systems. ## Before you begin Sign in, select the intended organization and project, and ensure you can access and run the flow and its connected resources. Obtain appropriate input values and check the destination and possible effects before testing. ## Open the flow Open **DevOps → Flow** and select the flow. Follow the instructions for the editor that opens: a code editor with **Inputs** and **Run Results**, or a graph of connected nodes. ## Run a code flow 1. Review the code, selected tools and workspace, and the **Inputs** and **Outputs** definitions. Under **Inputs**, enter suitable values in the **default** fields for the inputs used by the test. 2. Choose **Run** in the editor toolbar and wait for the response. 3. Inspect **Run Results** for output values and the **Terminal** for output or errors. A validation error can include the path, expected and actual types, and suggestions. ## Run a graph flow 1. Review the nodes, connections, input values, and destinations. Supply the required values in the relevant input nodes or settings. 2. In the graph v2 editor, open the **Run** tab and enter any required runtime input as JSON under **Run Inputs**. Use the toolbar run control. Inspect **Run Status**, **Result**, **Tracing**, and **Node Outputs**, and select nodes to inspect their results. 3. In the other graph editor, use the toolbar play control and inspect the results displayed on the relevant nodes and any error message. ## Verify and recover Compare the result with the intended output, and verify any changes at the external destination. If validation fails, correct the reported inputs or configuration and check access to connected resources. After an error or interruption, inspect the run status and destination before running again: some steps may already have taken effect. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /guides/sharing-and-permissions.md # Share a canvas page Choose which projects can access a page and verify the recipient's access. Canvas sharing sets the projects in which a page is available. It does not add people to a project or give them every operation on the page. A recipient still needs the relevant membership and permission. ![Sharing scopes for a page in Operations: keep it in Operations, also share it with Planning, or make it available to all organization projects. Viewer permissions still apply.](/assets/guides/sharing-permissions.svg) ## Before you begin Open the page in its original project. You need permission to manage the page's sharing. For a selected target project, the sharing control lists projects where you have an Owner or Admin role; making a page available across the organization is reserved for organization Owners. ## Share with another project Suppose a document belongs to **Operations** and a colleague works in **Planning**, another project in the same organization. 1. In **Operations**, open the document and choose **Page actions → Sharing**. 2. Select **Share with projects**. Under **Projects**, select **Planning**. At least one project is required for this option. 3. Close the dialog and wait for the page's **Saved** status. Ask the colleague to select **Planning** and open the shared page. They should be able to find and view it if their access permits; sharing does not itself grant editing rights. ![Sharing settings with Share with projects selected and Planning chosen as the destination project.](/assets/guides/sharing-settings.jpg) In this example, the page remains in Operations and is also shared with Planning. If **Planning** is not selectable, check whether you have the required Owner or Admin role there. If the colleague cannot see the page, check their membership and page permissions with the project administrator. A link alone does not grant access. ## Choose or restrict the scope | Sharing setting | Scope | Who can select it | | --- | --- | --- | | **Current project only** | The page remains in its original project. | A person permitted to manage the page's sharing. | | **Share with projects** | The original project and selected eligible projects. | A page manager with Owner or Admin role in each target project. | | **Available to all organization projects** | Projects across the organization. | An organization Owner who can manage the page. | To remove **Planning** from the example, return to **Page actions → Sharing** and remove it from **Projects**. If no other project needs access, choose **Current project only**. Close the dialog, wait for **Saved**, and ask the colleague to check access again in **Planning**. Removing a shared scope does not remove copies previously downloaded or otherwise saved by recipients. For membership and role management, see [Members and permissions](/admin/members-and-permissions.md) and [Organizations and projects](/concepts/organizations-and-projects.md). ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /guides/agents/create-and-configure.md # Create and configure an agent Set up an agent and test it with a small request. An agent combines instructions with a model and the tools, skills, and knowledge it can use. Start with a narrow job, then add access as needed. ## Before you begin Select the project where the agent belongs. You need access to create agents and to any resources you attach. ## Create and test 1. Open **AgentOps → Agents** and select **Create agent**. 2. Enter a name and an **Instruction** describing the job, expected output, and boundaries. For example: “Summarize the text I provide in three bullets. Do not change any external resources.” 3. Choose an available **Model** and execution mode. Legacy uses an existing Workspace; Sandbox uses a dedicated Workspace and user permissions. The mode is not an ordinary editable field after creation; an existing Legacy agent can use the migration workflow below. Leave tools and knowledge unselected for this simple test. 4. Select **Create**. Find the new agent in the list and open its chat. 5. Send: “Summarize this: The team shipped the search page Monday. On Tuesday, users reported slow results. The team plans to add caching on Friday.” A plausible response contains three bullets: the search page shipped Monday; users reported slowness Tuesday; caching is planned for Friday. Check the facts and bullet count. See [Chat with an agent](/guides/agents/chat-and-results.md). ## Configure capabilities Open the agent's settings to change its instruction, model, tools, skills, or knowledge. For a Sandbox agent, you can also edit its roles and individual permissions; ordinary editing does not change its execution mode. Use **Edit tools** to add only the tools the job needs, and **Edit skills** to attach reusable instructions. Under **Knowledge**, choose available **Table DB** or **Vector DB** resources when the agent needs them. For Sandbox, select available roles or individual permissions appropriate to the work; choices exceeding your permissions are unavailable. Review each tool's **Ask first** setting: it controls whether confirmation is required before that tool runs. Save your changes and test the specific capability with a limited request. Bundled skills run through the Shell built-in tool. Outside Sandbox execution, add Shell when using a bundled skill; the settings show a warning if it is missing. See [Project skills](/guides/agents/project-skills.md) for uploading and attaching project skills. If creation or a test fails, read the displayed message and check the selected project, access, and configuration. If a test could have changed a resource, inspect its destination before retrying. Review any requested decision as described in [Approvals and recovery](/guides/tasks/approvals-and-recovery.md). ## Migrate an existing Legacy agent Use **Migrate Agent** in the agent's settings when Sandbox is available for the project. This workflow retains the Agent ID and integrations while moving execution to its own Workspace. 1. Save any pending settings edits, then choose **Migrate Agent** to preview the move. 2. Review the selected roles, individual permissions and displayed environment-variable names. If a runtime-reset acknowledgement appears, read it before confirming: local files and manually installed packages remain in the old Workspace and are not copied automatically by this migration. Preserve needed output in durable storage first. 3. Choose **Migrate** and inspect completion. If interrupted, use **Check status**, then the displayed **Complete migration** or **Cancel migration** action as appropriate. Do not start another migration without checking the existing state. 4. After completion, send a small read-only request and verify the agent's expected capabilities. Inspect any denied operation against its new roles and resources. ## Update a Sandbox An eligible agent can show **A Sandbox update is available** in its settings. Choose **Update** only after reviewing active work and saving required outputs. The workflow can wait for active tasks, prepare a new Sandbox and move workspace files. Manually installed software needs to be set up again. Check for **Sandbox updated**, then verify a small task. If it reports a failure, inspect its status; the interface provides **Retry** and says when the current Sandbox can continue to be used. A Sandbox update and a Legacy-to-Sandbox migration have different file-transfer behavior. Neither replaces a durable backup. See [Data management](/admin/data-management.md). ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /guides/agents/chat-and-results.md # Chat with an agent Ask an agent to help and inspect its response and files. An agent chat lets you submit a request and inspect the response, activity, and available result files. ## Before you begin Select the project and an available agent. ## Start a conversation 1. Open **AgentOps → Agents** and select an available agent. 2. Open its chat, enter a specific request in the input field, and send it. Include relevant context and the outcome you need. 3. Follow the response and any displayed activity. If an approval is requested, review it before choosing **Approve** or **Reject**. 4. Inspect the answer and any result or file cards. Open or download a file when the corresponding action is available. ## Verify and troubleshoot Check the answer and files against your original request before relying on them. If a message fails, read the displayed error. Before retrying a request that may change something, check the conversation and destination for effects that may already have occurred. If an agent or resource is unavailable, check the selected project and your access. See [Approvals and recovery](/guides/tasks/approvals-and-recovery.md). To set up an agent for a specific job, see [Create and configure an agent](/guides/agents/create-and-configure.md). For named work assigned to an agent or team, see [Create and manage a task](/guides/tasks/create-and-manage.md). ## Continue, steer, or stop work When supported by the conversation, you can send a text instruction while the agent is working. It is queued for the active task rather than proving the agent has already acted on it. Check the displayed status and subsequent response. Attachments are not supported in this queued-text path; wait for the appropriate upload state to send a file. Use the conversation's stop control, or `/stop`, to request that running work stop. Wait for the resulting status. Stopping a task does not undo a completed external write or notification. After a disconnect, reopen the existing conversation and inspect its recovered messages and results before resending work. ## Open saved results beside the chat A result card can identify a **Canvas page**, **Table** or **Schedule**. Select its title to open the resource in the side view. Inspect the resource's actual content and use its own save controls when editing; an agent message is not proof that an edit was stored. You can also return through the resource's normal project view. Saved native resources differ from downloadable file cards. To preserve a file outside the runtime, follow [Upload and download files](/guides/files/upload-and-download.md) and [Data management](/admin/data-management.md). ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /guides/agents/project-skills.md # Add project skills to an agent Upload a skill to a project and attach it to an agent. Project skills provide reusable instructions and supporting files for agents in a project. They are separate from the coding-agent skills described under Developers. ## Before you begin Sign in, select the intended organization and project, and ensure you have permission to upload skills and edit the agent. Prepare a skill folder or ZIP containing its `SKILL.md` and any supporting files needed by the instructions. Review the files before upload. Place `SKILL.md` at the root of the selected folder. For a ZIP, place one `SKILL.md` at the ZIP root or inside a single top-level folder. Its frontmatter must contain a nonempty `name` and `description`. For example, a minimal `SKILL.md` can contain: ```markdown --- name: brief-summary description: Summarize supplied text in a few bullets. --- Summarize the text supplied by the user in three concise bullets. ``` Include supporting files under the same skill root when needed. The upload rejects duplicate skill folder names; choose a different folder name if one already exists. Folder uploads have a file-count limit set by the installation; the default is 200 files. ## Upload and attach 1. Open **AgentOps → Skills** in the project. Select **Upload Zip** or **Upload Folder**, then choose the prepared package. 2. Wait for the upload result. Find the skill in the list and open it to inspect its name, description, files, and `SKILL.md` content. 3. Open **AgentOps → Agents**, select the agent, and open its settings. Under **Skills**, select **Edit skills**, choose the project skill, and save the agent settings. 4. Open the agent's chat and give it a small request that exercises the skill. Inspect the response and any files against the skill's intended outcome. If the upload succeeds but the list fails to refresh, use **Reload list**; another upload is not needed. For other errors, read the message and check the package and project access. If the skill is absent from the agent selector, confirm that you are in the intended project and that the upload appears in its Skills list. Bundled skills have a separate Shell requirement outside Sandbox; see [Create and configure an agent](/guides/agents/create-and-configure.md). ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /guides/tasks/create-and-manage.md # Create and manage a task Assign work to an agent or team and follow it in the task view. A task gives assigned work a name, an assignee, and a conversation you can return to. Use an agent chat for a direct request, or a task when you want to track the work. See [How work runs](/concepts/workflows.md) for the relationship between agents, tasks, flows, and workspaces. ## Before you begin Select the project and an available agent or team. ## Create and follow a task 1. Open **AgentOps → Task** and select **Create Task**. 2. Enter a **Task Name** and describe the desired outcome and relevant context in **The task description**. 3. Select **Agent** or **Team**, then choose the assignee. A name and an agent or team are required. 4. Submit the form. Find and open the task in the task view, then inspect its conversation and status. Use the task's message input to continue the work with additional context or a follow-up request. 5. Check the response and any resulting files or changes. Review any approval request before deciding; see [Approvals and recovery](/guides/tasks/approvals-and-recovery.md). The task view also offers **Create recurring schedule** in its timeline view. Use that separate action when work should recur, rather than assuming a newly created task is a schedule. For a direct conversation, see [Chat with an agent](/guides/agents/chat-and-results.md). Notifications may provide a link back to the task; see [Inbox](/guides/tasks/inbox.md). If you cannot find the task or assignee, check the selected project and access and refresh the task view. If submission or subsequent work reports an error, inspect the task and any destination that might already have changed before retrying. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /guides/tasks/approvals-and-recovery.md # Approvals and recovery Review an agent's approval request and check work after an interruption. Some agent actions require a decision before they continue. Review the requested action in the context of your task. ## Review and recover 1. When an approval request appears, read the proposed action and its details. Confirm that the target and consequences match your intention. 2. Choose **Approve** to allow the requested action or **Reject** to decline it. If the details are unclear, do not approve until you understand them. 3. Watch the subsequent status and response. An approval is a decision, not itself proof that the action completed. 4. After a disconnect or error, reopen the relevant conversation or task and inspect the visible status and results before retrying. Check the target system when the action may have already taken effect. ## Verify and troubleshoot Look for a completion result or an error and verify any consequential change at its destination. If status remains unclear, contact your administrator or support with the task context and the displayed error; avoid repeating an action until you know its outcome. You can return to a linked task or chat from an [Inbox](/guides/tasks/inbox.md) notification when a source link is available. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /guides/tasks/inbox.md # Review your inbox Find notifications and return to their source. The inbox brings notifications together and can link you back to the task or agent chat that produced an item. ## Review an item 1. Sign in and open **Inbox**. Select **All**, **Unread**, or **Archived**, and use the category filters to narrow the list. 2. Select an item to read its details. When a source link is available, open it to inspect the associated task, agent chat, or other source. 3. Use **Mark read** or **Mark unread** to change its read state. Use **Archive** to move it to the archived view, or **Restore** to return an archived item. **Mark this view as read** marks the displayed items in the current category and archive view as read. Check the source for the actual result or approval request; a notification alone does not establish that work completed. If the source is unavailable, check the organization, project, and your access. If the inbox fails to load, retry and read any displayed error. See [Create and manage a task](/guides/tasks/create-and-manage.md) and [Approvals and recovery](/guides/tasks/approvals-and-recovery.md). ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /guides/data/files-and-data-assets.md # Explore files and data assets Browse project files and inspect available lakehouse assets. Use **Data** to explore the resources available in your project. Depending on your deployment, these may include a file browser and lakehouse catalog or jobs. ## Before you begin Sign in and select the intended organization and project. You need permission to read the resources; uploading or deleting requires additional access. Lakehouse features require the corresponding services to be configured. ## Browse and transfer files 1. Open **MLOps → Data → Files**. Browse to the intended folder and inspect its path and contents. 2. To add files, select the destination folder and use **Upload Files** or **Upload Folder** if available. Confirm the upload destination before choosing your files. 3. To retrieve files, use the download action for a file or select files and use **Download Selected**. 4. Check the resulting file list or downloaded copy. The folder deletion dialog can delete recursively, so review the target before confirming any deletion. ## Inspect lakehouse assets Where the lakehouse is configured, open **MLOps → Data → Catalog** to inspect available data assets. Open **MLOps → Data → Jobs**, select a job, and choose **Runs** to inspect recent run states and times. Availability and data access depend on the connected services and your permissions. ## Troubleshoot If a folder or asset is missing, verify the project and path, clear filters, and check access with an administrator. For a failed transfer, read the displayed error and check the destination before retrying. For advanced file operations, see [CLI files](/cli/guides/files.md). ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /guides/data/tables-and-vectors.md # Work with tables and vector stores Manage structured records and prepare documents for vector indexing. **Tables** holds structured records and views. **Vector** provides stores for document indexing when the required services are configured. ## Before you begin Select the intended organization and project. Reading, creating, editing, and deleting resources can require different permissions. Vector stores require the configured search and storage services. ## Work with a table 1. Open **DB → Tables**, choose **New table**, and enter `reading_list` as **Table name**. Set the first column to `title` with type **Text**, then use **Add column** to add `owner` with type **Text**. Create the table. 2. In the empty row, enter `Ocean report` and `Avery`, then save the row. Add a second row, `Energy brief` and `Morgan`, and save it. 3. Search for `Ocean report` and check that the first row displays its owner. Clear the search to see both rows. Before using **Delete selected**, confirm the selected records; deletion changes the data. For programmatic operations, see [CLI database tables](/cli/guides/database-tables.md). ## Prepare a vector store 1. Prepare a small text file named `sample.txt` containing `The blue turbine is inspected on Tuesday.` Use only data approved for the project. 2. Open **DB → Vector**, choose **Create vector store**, enter `inspection-example` as **Store name**, and use the managed Vector Store folder. Create the store, select it, and use **Upload files** to upload `sample.txt`. 3. Check the file list and indexing status. Upload and indexing are separate, and indexing can take time or fail. To test retrieval, an authorized agent can be configured with this store under **Vector DB** and asked `When is the blue turbine inspected?`; inspect its answer and supporting result against the source sentence. The store view itself does not provide a query control, and this test requires an agent with access and a working search service. If those prerequisites are unavailable, indexing status alone cannot confirm retrieval. Deleting a store can delete search assets and, depending on the source choice, managed source files. Read the confirmation carefully. Deleting documents also removes them from the search index during a subsequent indexer run. ## Troubleshoot Check the selected project, your permissions, and the displayed error. If documents appear in the file list but are not searchable, inspect indexing status and consult your administrator about the search service. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /guides/data/training-and-models.md # Training and models Inspect training bundles and model assets in your project. Use **Training** and **Models** to work with the training and model resources available in your project. The available features depend on configured services and permissions. ## Before you begin Select the intended organization and project. Obtain access to the relevant training or model resources. Before deploying a model or starting a training operation, review its inputs, destination, and potential resource use. ## Inspect and upload a training bundle 1. Open **MLOps → Training → Bundles** and select an available bundle and version to inspect its manifest, parameter schema, command preview, and files. 2. To add a bundle, use **Upload** if available. Supply a version and select a ZIP or folder whose root contains `training-bundle.yaml`. 3. Choose **Upload** and wait for the result. Open the uploaded version and verify its details and files. Uploading a bundle makes it available for use; it does not itself establish that training has run. To choose a dataset and run training, follow [Run a training job](/guides/data/training-jobs.md). ## Inspect models 1. Open **MLOps → Models → Registry** and select the relevant model and version. 2. Review the displayed model details, artifacts, and associated training information where available. 3. If deployment controls are available and you are authorized to use them, open **MLOps → Models → Deployments** and review the target and confirmation details before deploying. Check the resulting deployment status and destination. See [Deploy a model](/guides/data/model-deployment.md) for cloud and edge workflows. ## Troubleshoot Check the selected project and permissions if resources are missing. For an upload error, verify the bundle structure and version and read the displayed message. For a failed training or deployment operation, inspect its status and error before retrying; confirm whether any changes already took effect. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /guides/data/training-jobs.md # Run a training job Choose a dataset and training configuration, then inspect the job and its output. A training job uses a selected dataset version and training configuration to run work. Creating a job does not mean that training or model registration has completed. ## Before you begin Select the intended organization and project and confirm you can create and inspect training jobs. Have a suitable dataset and version available, a model name, and either an available preset architecture or an uploaded training bundle and version. For a custom bundle, also identify a supported execution target, compute when required, environment, and values required by its parameter schema. Review the bundle and dataset contract and the expected resource use with the people responsible for the environment. ## Create a job with a preset For this example, use model name `example-model` and experiment name `example-training`. First identify an existing preset architecture and a dataset version suitable for that architecture in your project; select the names your deployment actually offers. Review its expected dataset layout and the preset's parameters before starting. 1. Open **MLOps → Training → Jobs** and choose the add action to open **Create New Job**. Select **Preset architecture**. 2. Enter `example-model` in **Model Name**. Under **Experiment**, select an existing experiment or choose to create one and enter `example-training` as **New Experiment**. 3. Choose the prepared **Architecture**, then review its displayed hyperparameters and set them to values suitable for the dataset and available compute. Do not assume the same parameters apply to every architecture. 4. Select the prepared **Dataset** and its **Version**. Read the dataset validation result and warnings; validation is advisory and does not block submission. Resolve any mismatch before proceeding. 5. Review the model, experiment, architecture, parameters, and dataset version, then choose **Create**. Find the created job in the list and open its details. A job record is the immediate output; wait for the run and inspect its results before expecting a model artifact. ### Use a custom bundle instead Choose **Custom bundle** and select an uploaded **Training Bundle** and **Bundle Version**. Choose **Execution Target**, **Compute** when required, and **Environment**. Review the command preview and supply the bundle parameters required by its schema, then select the dataset and version and review validation before creating the job. The bundle's contract determines the expected inputs and outputs. ## Verify and recover Follow the job status and inspect its logs and metrics in the job details. After successful completion, inspect the associated model output or version in **MLOps → Models → Registry** when it is available; a submitted job or a successful status alone does not guarantee a usable registered model. Check the model's details and artifacts before deploying it. If creation fails, review the displayed validation or service error and the selected dataset, bundle, target, and permissions. If a run fails, inspect its logs and metrics, correct the underlying issue, and check whether a job or model output already exists before creating another run. See [Training and models](/guides/data/training-and-models.md) for bundle preparation and [Model deployment](/guides/data/model-deployment.md) for deployment choices. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /guides/data/model-deployment.md # Deploy a model Choose a cloud or edge target and verify the deployment. Select an appropriate target for a registered model version. Deployment changes a runtime and can consume resources; review the destination and permissions before proceeding. ## Before you begin Select the intended organization and project. You need permission to manage model deployments, an available model version compatible with the target, and access to the target infrastructure. For Edge, identify the intended device and format. For cloud, coordinate the available instance type or compute and environment with the infrastructure administrator. Availability and supported model formats depend on the deployment. ## Deploy to cloud 1. Open **MLOps → Models → Deployments** and choose **Cloud Online** or **Cloud Batch** for the intended workload. Choose **Add**. 2. Enter a **Logical Name**, choose **Model** and **Version**, and inspect the displayed deployment metadata. For online, select the instance type and count and review the request timeout. For batch, select compute and review instance count, mini batch size, concurrency and output settings. 3. Submit the configuration. Open the deployment, refresh its details, and wait for both endpoint and deployment states to show success. Check the endpoint, model version, and any traffic settings before relying on it. ## Deploy to an edge device 1. On **Deployments**, choose **Edge**, select the intended device, and choose **Add**. 2. Select **Model**, **Version**, **Deploy Format**, and desired **Status**. Choose **Review Deploy**, inspect the confirmation, and confirm only when the target and changes are correct. 3. Refresh the device deployments and inspect the status, model version, format, and any reported error. Verify the runtime on the device separately before relying on the model; a submitted desired state is not proof of a successful rollout. ## Troubleshoot Check the selected project, permissions, target availability, compatibility, and the displayed status or error. Cloud provisioning can take time; inspect both endpoint and deployment state. For Edge, check the device and deployment status. Before retrying or changing a deployment, inspect the current destination to avoid duplicating an operation or overwriting an unintended version. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /guides/automation/schedules-and-webhooks.md # Schedules and webhooks Configure scheduled work and outbound event notifications. Scheduled automations run configured work on a timetable. Webhook subscriptions send selected events to a target URL. Availability depends on your deployment and permissions. ## Before you begin Select the intended organization and project. You need permission to configure the automation and access to its target. Ensure the target action and recipient are appropriate: a schedule can repeatedly perform work, and a webhook sends event data outside the platform. ## Create a scheduled automation For this example, use the summary agent from [Create and configure an agent](/guides/agents/create-and-configure.md), with its three-bullet instruction and no tools or knowledge attached. The schedule repeats the same fixed-input test each day; it does not collect live project status. 1. Open **Automation → Schedules** and choose **New scheduled automation**. Enter `Daily summary test` as **Name**, choose **Agent**, and select the summary agent. Enter `Summarize this: The team shipped the search page Monday. On Tuesday, users reported slow results. The team plans to add caching on Friday.` as the prompt. 2. Under **Execution mode**, choose **Schedule** and a daily schedule. Set **Hour** to `9`, **Minute** to `0`, **Second** to `0`, and **Timezone** to `Asia/Tokyo`. Leave **Start after** empty and turn off **Catch up missed runs** so missed runs are not requested for catch-up. Review the enabled setting and choose **Create**. 3. Open the schedule and check **Next run**: it should be the next future 09:00 in Tokyo, subject to the displayed schedule and service state. After that time, inspect **Last run** and open the resulting agent task. Check for three bullets covering Monday's release, Tuesday's slow results, and Friday's planned caching. A scheduled time or created record does not prove the task succeeded. A schedule can be stopped or edited through its available controls. Check its status after changing it. Some target and device combinations may be unavailable; follow any warning shown in the form. For requests arriving from an external sender to start an agent or flow, use an authenticated [inbound webhook endpoint](/guides/automation/webhook-endpoints.md). ## Create a webhook subscription 1. Open **Automation → Webhooks → Subscriptions** and choose **New subscription**. 2. Enter the **Target URL** and select the **Event types** to send. Configure authentication, signing, retry, and enabled settings as appropriate for the receiving service. 3. Choose **Create**, then inspect the subscription and its delivery information as events occur. Confirm receipt at the destination. ## Troubleshoot Check the selected project, permissions, target configuration, and displayed errors. For schedules, verify the timezone, enabled state, next run, and target status. For webhooks, check the URL, selected events, authentication, and delivery details. Before retrying or re-enabling an automation, check whether the operation already occurred. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /guides/automation/webhook-endpoints.md # Receive events with webhook endpoints Configure an authenticated inbound webhook for an agent or flow. An inbound webhook endpoint receives a request and starts an agent task or flow. It is different from an outbound [webhook subscription](/guides/automation/schedules-and-webhooks.md), which sends platform events to another service. ## Before you begin Select the organization and project containing the intended agent or flow. A project Owner must create and manage the endpoint and have access to its target. Arrange an authorized sender and agree on its authentication method and a safe test payload. An endpoint's tasks run as the current editor shown in **Run as user**; verify that person's access and the target's actions before saving. Do not use another person's credentials or include secrets in a test payload. ## Create and authenticate an endpoint 1. Open **Automation → Webhooks → Endpoints** and choose **New Webhook Endpoint**. Enter a **Hook name** and choose the **Target type** and agent or flow. 2. For an agent, write **Instruction text** describing what it should do with the incoming data and select the payload mode. For a flow, review its fixed/default inputs and, if using schema mapping, map only the incoming fields that should override those inputs. Check the selected target and **Run as user**. 3. Choose an **Auth mode** supported by the sender: `static_secret`, `github_signature`, or `entra_jwt`. For a shared or signing secret, securely store the generated secret when it is shown; it is shown only once. Give it only to the authorized sender through an approved secret channel. For Entra JWT, coordinate the platform-managed tenant, caller identity, and required app role with your administrator. 4. Choose **Create**. Copy the endpoint URL from the resulting endpoint details and configure the authorized sender with the corresponding authentication. Treat the URL and credentials as sensitive; do not paste them into chat, documentation, or logs. ## Test and verify the result 1. Select the saved endpoint and find **Request example** in its details. Choose the **curl** or **Python** tab and copy the example into a private, controlled environment for the authorized sender. The example is specific to the endpoint and auth mode; replace placeholders using the sender's approved credential source. Do not put credentials in a shared shell history, chat, ticket, or log. 2. Use a harmless payload that matches the configured agent instructions or flow mapping. The example includes sample JSON; replace any real or sensitive values with harmless test values and review the target's side effects first. For `static_secret`, the request uses `Authorization: Bearer `. For `github_signature`, calculate `X-Hub-Signature-256: sha256=` using the signing secret and the exact request body, as shown in the example; changing the body requires a new signature. For `entra_jwt`, use `Authorization: Bearer ` with an authorized caller and the displayed token scope. Never share the secret or token as part of the payload. 3. Have the authorized sender run the prepared request once. Open **Deliveries** and refresh; inspect status, response code, error, and task ID when available. Follow the task or flow run to inspect its status and result; a received request alone does not prove the target completed successfully. Review delivery details carefully because they can contain request headers and payload data. If authentication fails, check the chosen mode and sender configuration with the responsible administrator without exposing credentials. If the delivery is accepted but the task fails, inspect the target, its inputs, and the editor's permissions. Before retrying, check whether the first event already started work or changed a resource. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /guides/operations/workspaces.md # Operate agent workspaces Inspect and manage the runtimes used by agents and workspace-backed flows. An agent workspace is a project-scoped runtime for tools such as shell and Data Lake operations. Select the organization and project, then open **AgentOps → Workspaces**. The actions available depend on your permissions, the workspace's ownership and runtime type. A shared workspace may be visible but read-only; some agent-managed workspaces have different controls. ## Inspect or create a workspace Select a workspace to review its status, runtime, image and observation details. A status observation can be stale or unconfirmed; refresh and inspect the resource before starting, stopping, or updating it. If it is missing, check the selected project and its access settings. For example, create a cloud workspace using **Azure Container Apps**: 1. Choose **Create workspace**, enter a name such as `analysis-workspace`, set **Type** to `cloud`, and choose **Azure Container Apps** as **Runtime provider**. The provider is fixed at creation; the deployment must have its infrastructure and permissions configured. 2. Choose **Track stable** under **Image Update Policy**. Leave environment variables, GitHub repository, and setup script empty for this example. Under **Storage**, add a **Blob Path** only for a project folder the workspace is permitted to use; obtain the actual path and grants from your administrator. A path in the form does not itself grant storage access. 3. Review **Sharing** and select the intended project scope, then create the workspace. Wait for provisioning and inspect the displayed status and image. If provisioning fails, use the displayed error with your administrator; do not assume a cloud runtime is ready merely because it appears in the form. Workspace creation does not configure secret injection or network policy. Arrange and verify these with your deployment administrator before relying on them. A track-stable image follows the platform-selected stable image; a pinned image stays on the selected image until changed. For an eligible track-stable workspace, **Roll out image** updates the runtime. Check the resulting image and status before relying on the change. ## Open a web application A process listening on `localhost` inside a workspace is not automatically reachable from your browser. Do not assume that the workspace's tool API URL can forward an arbitrary loopback port or provide a project-authorized web preview. Use a preview endpoint only when it is explicitly supported and configured for that runtime. For a container-backed web app, use the supported [Hosted App publication workflow](/cli/guides/apps.md) when it is enabled. Otherwise, ask the deployment administrator for a separate authenticated application endpoint. That application must verify its users and their access to the intended project. Opening a URL from a ThinkPlatform page does not transfer the page's permissions to the application. See [Cloud and edge operations](/guides/operations/cloud-and-edge.md) for the distinction between inspecting a cloud app and changing its deployment. ## Stop, resume, or delete Where available, **Stop** and **Resume** change runtime state. Check the resulting status after the action. A Sandbox preview may retain its disk across stop and resume, but recreating it starts a new disk. Treat workspace local files as ephemeral unless durable backing is configured, and verify any required outputs in durable storage. See [Data management](/admin/data-management.md). Deleting a workspace removes the workspace and can interrupt agents or flows that use it. Before using **Delete**, review dependencies and save needed files to a durable location. Confirm the deletion in the dialog and check the workspace list afterward. Deletion and stopping are different operations; stopping is appropriate when the runtime should remain available to resume. Human sign-in and workspace execution credentials are separate. A workspace may use a managed identity for external resources, and its allowed paths and grants affect what it can access. See [Security and authentication](/admin/security-and-authentication.md). If provisioning or an action fails, check the displayed error, selected project, workspace ownership, runtime configuration and underlying resource permissions with the responsible administrator. See also [Cloud and edge operations](/guides/operations/cloud-and-edge.md) and the [CLI guide](/cli/get-started/overview.md). For an agent-owned Sandbox, use the update controls in [Agent settings](/guides/agents/create-and-configure.md#update-a-sandbox) rather than treating it as an ordinary shared workspace. Legacy migration and Sandbox updates have distinct file-transfer conditions. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /guides/operations/hosted-apps.md # Open a published web app Use a project application through ThinkPlatform and understand its data permissions. A Hosted App is a container-backed application published to a ThinkPlatform project. It can open on a dedicated Canvas application page or inside a document or dashboard. Your deployment administrator must enable and configure Hosted Apps before a developer can publish to it. ## Open and try an app 1. Select the organization and project where the app was published. Open the Canvas page or project link provided by its developer. 2. Complete the app's ThinkPlatform authentication and review any requested data permissions before granting consent. 3. Perform one small intended action. If the app changes a record, reopen the record to verify its saved value. For the [sample app](/cli/guides/apps.md), the page should display **Inspection app**. A dedicated application page uses the page area for the app rather than document blocks or widget frames, while retaining navigation back to ThinkPlatform. The app's declared permissions and your current project/resource permissions both apply. A shared page does not grant access to an unrelated Table or every SDK operation. Report a denied operation with the project, app and displayed message; do not use another person's credentials to work around it. ## If the app does not open Ask the developer to inspect publication and readiness. A stopped release, incomplete build, missing consent or unavailable deployment service can prevent access. A long publication wait does not establish that a separate deployment is needed; check the recorded result before retrying. A process on an arbitrary port inside an Agent Workspace is not automatically a Hosted App. Use the supported publication workflow and its authenticated endpoint rather than exposing a workspace port directly. See [Operate agent workspaces](/guides/operations/workspaces.md). ## Develop or update an app Use the [CLI publication guide](/cli/guides/apps.md) to publish source or a Registry image, create the Canvas page, and update or stop a release. Data-aware backends use [request-bound SDK access](/python-sdk/hosted-apps.md). When handing an app to users, provide its page URL, app ID, tested actions and any remaining limits. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /guides/operations/cloud-and-edge.md # Operate cloud and edge resources Inspect container apps and edge devices, and verify changes to their runtime state. Select the organization and project before opening **DevOps → Cloud** for Container Apps or **DevOps → Edge** for devices. Visibility and available changes depend on membership, roles, resource ownership and deployment configuration. ## Inspect and control a cloud app In **Cloud**, select an app to inspect its status, image and configuration. If the list fails to load or its status is out of date, refresh it before changing the app. Creating or editing an app requires project permission and a configured environment. For an app you are authorized to control, use its start or stop action, then refresh and verify its state. These actions change runtime state; they do not delete the app. If the action fails, check the error, project, app ownership, environment configuration and underlying cloud permissions. Project Owner permission is required for the start and stop operations. To delete an app, first identify its users and dependent services, preserve any needed data, and confirm the intended target. Use the app's delete action and confirm the dialog, then refresh the list and verify the result. Deleting an app can interrupt its workloads; it is distinct from stopping it. ## Share an authenticated web application For the supported project application path, see [Published web apps](/guides/operations/hosted-apps.md) and [Publish a web app](/cli/guides/apps.md). Hosted App publication is distinct from creating an ordinary Container App. Permission to manage a Container App in ThinkPlatform does not automatically protect the application's own HTTPS endpoint or give it project-level authorization. Verify the application's authentication and its checks for the intended users before sharing its URL. For an application that must reject unauthenticated requests from the first deployment, arrange a deployment with its entrance blocked until authentication is configured and verified. Do not assume the standard Cloud creation workflow enables authentication before an external endpoint becomes reachable. Ask the deployment administrator to prepare and verify that configuration before deploying the business application. ## Inspect an edge device In **Edge**, select a device and inspect its connectivity, modules and deployment information. Select a module to inspect its twin. Desired properties describe the intended configuration; reported properties are the last state the module reported. A device showing online does not prove every module has applied the desired configuration. For a deployment or twin change, verify the device and module, review the intended change, and use the controls available to your role. Afterward, inspect reported state and deployment status. If they differ from the desired state, check device connectivity, module health, image availability and pull access; allow time for the device to report back. Container images are managed separately in [Registry and modules](/guides/operations/registry-and-modules.md). For agent runtimes, see [Operate agent workspaces](/guides/operations/workspaces.md). ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /guides/operations/registry-and-modules.md # Registry and modules Find container images and inspect project integrations. **DevOps → Registry** lists container images. **DevOps → Modules** manages project API and MCP integrations. These are separate resources: an image can be deployed to a runtime, while a module describes an integration and its endpoints. ## Find an image 1. Select the organization and project and open **DevOps → Registry**. 2. Choose **Organization** or **Common**, search for a repository and select it to load its tags. 3. Inspect the tag, digest and update time. Copy the image reference for the intended deployment and verify its image and runtime status after deployment. Browsing an image does not prove the target runtime can pull it. If pull credentials are missing or a deployment fails, check the target's registry configuration and runtime identity with the responsible administrator. Organization registry push requires an organization Owner or Admin; project Owner alone is insufficient. Common registry push and deletion are restricted to platform administrators. Delete controls depend on the relevant management permission. Before deleting a tag or repository, find its active deployment references and confirm the intended target: deletion can prevent future deployments or rollouts. Verify the result in the registry afterward. ## Register an MCP module This example requires a reachable MCP server, its approved endpoint URL and any server-required authentication header. Ask the server administrator for those values and a harmless read-only tool and test input. The example URL `https://mcp.example.com/mcp` is a placeholder, not a working service. 1. Open **DevOps → Modules** and choose **Add API**. Set **Type** to **MCP**, enter `Example tools` in **API Name**, and enter the approved MCP endpoint URL. 2. If the server requires a header, use **Custom headers → Add header**, enter its **Header name** and **Header value**, and leave it enabled. Keep credentials out of prompts and shared notes. Review **Sharing settings**, then save. Complete any separate server authorization if prompted and submit again. 3. Select the saved module and inspect its discovered endpoints. Open the agreed read-only tool and use **Tool Test** to enter the benign input required by its displayed schema. Run it and inspect the result or error. Tool tests make real requests, so check the tool's effects before running one. Registration alone does not guarantee remote authorization. If tools are missing or the test fails, verify the URL, module access, headers and external authorization with the server administrator. Saved sensitive values may be masked; enter a replacement deliberately when rotating a credential. Before deleting a module, identify its dependent agents and flows. See [Cloud and edge operations](/guides/operations/cloud-and-edge.md), [Operate agent workspaces](/guides/operations/workspaces.md), and the [Python SDK overview](/python-sdk/overview.md). ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /guides/troubleshooting/access-and-errors.md # Troubleshoot access and errors Diagnose missing projects, save conflicts, indexing, runtime readiness, and uncertain runs. Use the symptom and the affected operation to choose a check. If you need help, include the project, resource name, time, and displayed message; omit credentials and sensitive content. ## A project is missing Open the organization and project selector. Select the intended organization and clear any project search. Signing in with an Entra account does not automatically add you to every ThinkPlatform project. If the project is still absent, ask its administrator to check your organization membership and project role. See [Members and permissions](/admin/members-and-permissions.md). ## A canvas page has a save conflict The message **“This Canvas page was modified elsewhere. Reload the page before saving.”** means another change conflicts with your edit. Copy any unsaved text somewhere safe first, then reload the page, compare the current content, and reapply the needed change. Wait for **Saved**, navigate away and reopen or reload the page to verify it. See [View and edit a canvas](/guides/canvas/view-and-edit.md). ## Uploaded vector files are not searchable yet Open **DB → Vector**, select the store, and inspect its file list and indexer status and latest run information. An upload and an indexer run are separate: a file can appear before indexing completes. If the last run reports failures, use the displayed details to investigate the source and ask the search-service administrator to check the indexer. Do not repeatedly upload the same files while the result is uncertain. See [Tables and vector stores](/guides/data/tables-and-vectors.md). ## Sandbox is unavailable In the workspace creation form, inspect **Runtime provider**. If **Azure Container Apps Sandbox** is disabled or the form says Sandbox is unavailable, the deployment has not reported it ready. Ask a global administrator to prepare and verify the organization Sandbox infrastructure. If the form says it could not check readiness, resolve that check with the administrator; Azure Container Apps may remain available as another provider. See [Operate agent workspaces](/guides/operations/workspaces.md). ## A flow times out or its outcome is unclear A timeout does not establish that every step failed. Open the flow's result or node status, then inspect any external destination the flow could have changed. Record the run details and ask the responsible operator to check the target if its state is unclear. Retry only after determining whether the earlier run took effect, especially for writes or notifications. See [Run a flow and inspect results](/guides/flows/run-and-results.md). For terminal-specific problems, see [CLI troubleshooting](/cli/guides/troubleshooting.md). For an unresolved issue, use [Contact support](/guides/get-started/support.md) and preserve its receipt or uncertain submission ID before leaving the form. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /guides/get-started/support.md # Contact support Review an inquiry before sending it and distinguish acceptance from confirmed storage. Open **Support** at the bottom of the application sidebar, then **Contact support**. **Docs** in the same menu opens this documentation. Inquiry submission must be enabled for your deployment. ## Prepare and review an inquiry 1. Check the selected organization and project. Wait for the form's identity and target checks to finish. 2. Describe your issue or question in up to 5,000 characters and confirm your **Reply-to email address**. Include the affected resource, expected behavior, actual result and time. Omit tokens, passwords and confidential file contents. File attachments are not currently available in this form. 3. Choose **Review**. Check the fixed description, reply address and target on the review screen. Choose **Edit** to change them. 4. Choose **Send** when the content is ready. Inspect the result and save the **Inquiry receipt** when one is provided. ## Understand the result Acceptance and confirmed storage are separate states. An accepted or pending result is not yet proof that the inquiry was stored. Use the displayed status-check action when the outcome is uncertain, retaining the same submission ID rather than sending a duplicate. The draft and submission ID are kept only within the current page; reloading or navigating away can lose them. Preserve the needed text and receipt before leaving. If identity verification fails, verify your session as instructed. If submission is unavailable, keep the draft and displayed ID and ask your organization's support contact about the available route. An inquiry receipt does not promise a response time or resolution. For immediate access checks, see [Troubleshoot access and errors](/guides/troubleshooting/access-and-errors.md). ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /developers/overview.md # Build and automate with ThinkPlatform Choose the CLI, Python SDK, or agent guidance for your ThinkPlatform workflow. Use ThinkPlatform's developer tools to discover resources, work with project data, and automate supported platform operations. The CLI and Python SDK are included in the public `ThinkPlatform-client` package. **[CLI](/cli/get-started/overview.md)** Install the client, sign in, and save a project profile before using short commands. **[Python SDK](/python-sdk/overview.md)** Use the public Python client from an application, notebook, or script. ## Start with one read For a new terminal setup, follow [Installation](/cli/get-started/installation.md) and [Authentication](/cli/get-started/authentication.md). Then choose your organization and project interactively: ```bash tp profile setup tp context show tp canvas pages list ``` The examples in the CLI guides assume that you have already selected the intended profile and project. Use extra flags when you need an override or a specific output format. See [Projects and profiles](/cli/guides/context.md). For Python, follow the [SDK overview](/python-sdk/overview.md) and [SDK authentication](/python-sdk/authentication.md) before making your first request. ## Work with an external agent Give the agent a specific project and a clear outcome. Have it inspect the current identity and context, discover the relevant resources, and explain the intended changes before a write. Verify the result before retrying an operation whose outcome is uncertain. Use [Agent setup](/cli/guides/agent-setup.md) for the documented skill and Markdown discovery routes. The [Agent skills guide](/developers/agent-skills.md) introduces task-specific command guidance and examples. A documentation search connection provides instructions; it does not authenticate the agent to ThinkPlatform or grant additional permissions. ## Choose a workflow | Task | CLI guide | Python guide | | --- | --- | --- | | Work with pages | [Canvas pages](/cli/guides/canvas-pages.md) | [SDK resources](/python-sdk/resources.md) | | Read or update table data | [Database tables](/cli/guides/database-tables.md) | [Database API](/python-sdk/database.md) | | Transfer project files | [Files](/cli/guides/files.md) | [SDK resources](/python-sdk/resources.md) | | Execute a flow or monitor work | [Execution](/cli/guides/execution.md) | [SDK resources](/python-sdk/resources.md) | | Use an endpoint directly | [API requests](/cli/guides/api-requests.md) | [API reference](/python-sdk/api-reference.md) | ## Understand the access boundary Developer tools use the authenticated identity and the selected organization and project. The public client does not include the Flow or Agent execution engines. An organization's workspace identity and permissions for external services are separate from your CLI sign-in. See [Organizations and projects](/concepts/organizations-and-projects.md) for the shared access model, and [SDK errors](/python-sdk/errors.md) or [CLI troubleshooting](/cli/guides/troubleshooting.md) when a request fails. ## Build a project web app Client 0.6.133 adds [Hosted App publication](/cli/guides/apps.md), [request-bound SDK access](/python-sdk/hosted-apps.md), and [Lakehouse statements](/python-sdk/lakehouse.md). Review [Upgrade and migration](/cli/guides/upgrading.md) for older Apps commands. The deployment must enable and authorize the corresponding service. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /cli/get-started/overview.md # ThinkPlatform CLI Install the CLI, connect to your project, and read your first Canvas page. `tp` is the ThinkPlatform CLI. Discover commands, inspect project resources, and automate platform operations with structured results. ## Install the client Install the CLI and Python SDK from the public `ThinkPlatform-client` package: ```bash Installation python -m pip install ThinkPlatform-client tp --version tp --help ``` ### Supported platforms and package contents See [Installation](/cli/get-started/installation.md) for environment setup, supported platforms, upgrades, and troubleshooting. Use a fresh Python environment. The initial binary wheel release targets CPython **3.11–3.13** on Linux x86_64 (glibc 2.28+), macOS 11+ on Apple silicon, and Windows x86_64. Intel Macs and public source distributions are outside this initial release. The client connects to an existing ThinkPlatform service. It includes CLI and SDK access to platform APIs, including Flow and Agent operations. The client does not include their execution engines. ## Make your first read ### Discover the available commands Inspect help before choosing an operation. Help runs locally and does not require authentication. ```bash tp --help tp commands tp canvas pages list --help ``` Command groups and flags are covered in the [CLI reference](/cli/reference/commands.md). ### Set up your profile and choose a project Run the interactive setup in your terminal: ```bash tp profile setup ``` Enter a profile name, review the connection defaults, and complete sign-in. The wizard lists accessible organizations and projects by name. Choose each by number, then confirm the summary to save and activate the profile. You do not need to look up IDs. With no connection settings configured, setup uses the production service and browser sign-in. For another deployment, use its administrator-approved settings. See [Authentication](/cli/get-started/authentication.md). ```bash tp context show ``` Check the saved destination. Setup requires an interactive terminal without JSON or query output; a person should complete it before handing work to an agent. Scripts can use the [manual context commands](/cli/guides/context.md#manual-selection-for-scripts). ### Read a page and verify the result List Canvas pages, choose an ID from the result, and read that page. ```bash tp canvas pages list tp canvas pages get PAGE_ID ``` Check that the returned page matches the selected project and intended title. Page content is in the top-level `blocks` array. If the list is empty, use another project you can access; there is no need to create a page for this check. See [Canvas pages](/cli/reference/commands.md#common-reads) for more read options. ## Give your agent a bounded task Prepare the local [Agent skills](/cli/guides/agent-setup.md) when your coding agent supports skill files. You can also follow the commands directly; skill installation does not change your platform access. Start with a request that makes the scope and expected result explicit: ```text Inspect the available ThinkPlatform CLI help. Confirm my identity and organization/project context, then list up to five Canvas pages. Read one page as JSON and summarize its title and content. Do not create, update, or delete resources. Ask me to complete interactive sign-in if required, and report the page ID you used to verify the result. ``` For automation, put global output flags before the command: `tp --json …` requests machine-readable JSON, while `--query` selects a field from the result. Keep IDs from discovery output rather than guessing them. See [output](/cli/reference/commands.md#json-errors-and-query-behavior). When you move on to changes, ask the agent to explain the target resources and intended effect first, then verify the resulting state with a read command. ## Next steps - [Installation](/cli/get-started/installation.md): prepare your environment and verify the client. - [Authentication](/cli/get-started/authentication.md): connect an account and manage profiles. - [Agent skills](/cli/guides/agent-setup.md): inspect and install the bundled task guidance locally. - [Choose an organization and project](/cli/guides/context.md): discover and verify the destination. - [Read and update Canvas pages](/cli/guides/canvas-pages.md): complete a small resource workflow. - [Files and Data Lake](/cli/guides/files.md): upload and inspect workflow inputs. - [Run and monitor work](/cli/guides/execution.md): distinguish Flow runs, Agent tasks, and MLOps jobs. - [Troubleshooting](/cli/guides/troubleshooting.md): diagnose context, permission, and uncertain execution outcomes. - [Python SDK](/python-sdk/overview.md): use the public client from Python. For container-backed applications, see [Publish a web app](/cli/guides/apps.md). Updating from an older client? Read [Upgrade and migration](/cli/guides/upgrading.md) before using old Apps scripts. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /cli/get-started/installation.md # Installation Prepare a supported Python environment and install the ThinkPlatform CLI and SDK. The `ThinkPlatform-client` package contains the `tp` CLI and public Python SDK. It connects to an existing ThinkPlatform service; get your deployment's connection settings before signing in. Install the CLI and SDK from PyPI. The current release is **0.6.134**. ## Supported environments The client is distributed as binary wheels for these environments: | Python | Operating system | Architecture | | --- | --- | --- | | CPython 3.11, 3.12, or 3.13 | Linux with glibc 2.28+ | x86_64 | | CPython 3.11, 3.12, or 3.13 | macOS 11+ | Apple silicon (arm64) | | CPython 3.11, 3.12, or 3.13 | Windows | x86_64 | Intel macOS is excluded from the initial release. Public source distributions are also outside this release, so an unsupported environment cannot fall back to building the client from source. ## Create a fresh environment Use a separate virtual environment for the client. The examples select Python 3.13; substitute 3.11 or 3.12 if that is your supported interpreter. **Bash (Linux or macOS)** ```bash python3.13 -m venv .venv source .venv/bin/activate python --version python -m pip install --upgrade pip ``` **PowerShell (Windows)** ```powershell py -3.13 -m venv .venv .\.venv\Scripts\Activate.ps1 python --version python -m pip install --upgrade pip ``` If PowerShell prevents activation, use `.\.venv\Scripts\python.exe` in place of `python` and `.\.venv\Scripts\tp.exe` in place of `tp` in the following commands. ## Install the client Install from PyPI in the activated environment: ```bash python -m pip install ThinkPlatform-client ``` ## Verify the installation These commands run locally and do not require credentials: ```bash tp --version tp --help tp profile setup --help ``` Set up your connection and project interactively: ```bash tp profile setup tp canvas pages list ``` The wizard guides sign-in and numbered organization/project selection, then saves the profile after confirmation. See [Authentication](/cli/get-started/authentication.md) for deployment settings and [Projects and profiles](/cli/guides/context.md) for manual setup and scripts. ## Upgrade Upgrade within your client environment: ```bash python -m pip install --upgrade ThinkPlatform-client tp --version ``` If you previously used the full `ThinkPlatform` runtime package, create a fresh environment for `ThinkPlatform-client`. Keep your runtime environment separate rather than installing both distributions over the same package files. ## Troubleshooting ### pip cannot find a matching distribution Check `python --version`, your operating system, and interpreter architecture against the supported matrix. Upgrade pip in that environment and retry. Linux requires glibc 2.28+; Intel macOS and unsupported Python versions have no initial public wheel. ### The package installed, but tp is not found Activate the environment where you installed the client and rerun `python -m pip show ThinkPlatform-client`. The `tp` executable lives in that environment's `bin` directory on Linux/macOS or `Scripts` directory on Windows. You can also invoke `.venv/bin/tp` or `.\.venv\Scripts\tp.exe` directly from the directory containing `.venv`. ### pip uses a different Python environment Run installation through `python -m pip` after activating the environment. Check `python --version` and `python -m pip --version` to confirm the interpreter and pip location before retrying. ### An upgrade behaves unexpectedly after using the full package Create a new virtual environment and install only the client there. Verify `tp --version` and `tp --help` before configuring authentication. Avoid copying installed package files between environments. For changes from older versions, including the Apps command split, see [Upgrade and migration](/cli/guides/upgrading.md). ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /cli/get-started/authentication.md # Authentication Choose a sign-in method, save a connection profile, and verify your identity and project context. Connect `tp` to the ThinkPlatform deployment you use, then verify the account and project before working with resources. Start with the [installation guide](/cli/get-started/installation.md) if `tp --help` is not available yet. ## Set up a profile For a person at a terminal, start with: ```bash tp profile setup ``` The wizard asks for a profile name, service URL, API audience and authentication mode. Review the defaults, complete sign-in, choose an accessible organization and project by number, and confirm the summary. Names are shown alongside IDs for disambiguation; you do not need to find IDs beforehand. Setup saves and activates the named profile only after confirmation. ```bash tp context show tp canvas pages list ``` Cancelling, an empty access list, or an authentication/API error leaves the saved configuration and active profile unchanged. Discovery uses reads and does not create or change service resources. Sign-in can still use the existing secure credential cache described below. Setup requires interactive input and output terminals. It rejects JSON output and root `--query` before authentication or network access. Agents and unattended scripts should use prepared profiles or the [manual context commands](/cli/guides/context.md#manual-selection-for-scripts), with `configure --no-prompt` when saving explicit settings. `configure` remains available for offline connection setup. ## Get your connection settings For the production service, `tp profile setup` guides browser sign-in and project selection. If your profile is already configured, use `tp auth login` to sign in again. The shared registration is already configured, so you do not need to create an app or provide a secret. Your organization may require administrator consent. If an approval request appears, follow your organization's approval process and retry sign-in after it is approved. ### Built-in application settings | Setting | Production value | | --- | --- | | Service URL | `https://thinkplatform.ai` | | API audience | `api://04d6aecc-4540-463a-87e3-4024ffad7428` | | Authentication | `interactive-browser` | | Tenant ID | `5a959e94-a278-467d-ab33-d59909a75bad` | | CLI application ID | `709439d2-4a99-44c2-8c35-9b1e71cc2e34` | These shared public-client defaults apply when the effective URL and audience match the production values and browser or device-code auth is selected. Environment variables and explicit CLI options can override them. If another URL or audience is configured without an explicit auth mode, the CLI uses `azure-cli`. Use the URL, audience, client ID, tenant, and auth mode approved for a custom deployment. The `https://thinkplatform.example` and `api://YOUR_API` values below are placeholders for a custom deployment. Replace them with its actual settings. ## Choose an authentication mode | Mode | When to use it | What it needs | | --- | --- | --- | | `azure-cli` | Your local Azure CLI already has the intended account signed in. | Azure CLI installed and signed in, plus the API audience. | | `device-code` | You want to complete sign-in using a code in a browser, including on another device. | For production defaults, the shared CLI registration is selected automatically; for other services, use the deployment-approved client ID, tenant and API audience. | | `interactive-browser` | You want browser-based sign-in from your local machine. This is the default when no connection settings are configured. | For production defaults, the shared CLI registration is selected automatically; for other services, use the deployment-approved client ID, tenant and API audience. | | `workspace-delegation` | You are inside a provisioned managed Agent Workspace. | The workspace's managed identity, injected assertion and workspace locator, API URL, and required organization/project context. | The deployment must allow the application identity used by your chosen mode. Browser and device-code sign-in need an approved public-client registration; a web-only application registration is not sufficient. Administrator consent for one API audience does not grant access to a different API audience. For `azure-cli`, sign in through Azure CLI as directed by your administrator before running `tp auth login`. This mode uses Azure CLI's application identity rather than the shared ThinkPlatform CLI registration, so the deployment must explicitly allow Azure CLI. For workspace delegation, use the settings injected by the workspace rather than copying credentials from another session. ## Sign in separately or use a custom deployment ### Set application settings for browser or device-code sign-in Skip this step for the production defaults. For a custom deployment, use the approved public-client ID and tenant. You can also set `THINKPLATFORM_AZURE_CLIENT_ID` and `THINKPLATFORM_AZURE_TENANT_ID` to override the production registration. These environment settings are non-secret and are not stored in profiles. **Bash** ```bash export THINKPLATFORM_AZURE_CLIENT_ID="YOUR_CLIENT_ID" export THINKPLATFORM_AZURE_TENANT_ID="YOUR_TENANT_ID" export THINKPLATFORM_API_AUDIENCE="api://YOUR_API" ``` **PowerShell** ```powershell $env:THINKPLATFORM_AZURE_CLIENT_ID = "YOUR_CLIENT_ID" $env:THINKPLATFORM_AZURE_TENANT_ID = "YOUR_TENANT_ID" $env:THINKPLATFORM_API_AUDIENCE = "api://YOUR_API" ``` For custom deployments, set the API audience for the target service separately from the client ID used to sign in. Never use a client secret with these public-client flows. ### Log in and save your connection defaults For the production defaults, sign in using your active profile: ```bash tp auth login ``` For a custom deployment, supply its URL and audience explicitly. Put global options before the command: ```bash tp --base-url https://thinkplatform.example --audience api://YOUR_API --auth-mode interactive-browser auth login ``` Choose `device-code` or `azure-cli` as the `--auth-mode` value when appropriate. Complete any sign-in prompts yourself. Login acquires a credential, calls the service to check your identity, and saves effective connection and context settings to the selected profile after success. For production browser/device flows, it also stores an encrypted token cache in the operating system's credential store and a separate non-secret account record locally. Later CLI processes reuse that account silently while the stored credential remains valid; Azure may request sign-in again when required. ### Verify the account and effective context ```bash tp auth whoami tp context show ``` `auth whoami` makes an authenticated request to the service. Confirm it shows the intended account. `context show` displays effective local settings; it does not prove that you can access the selected project. Follow [Select a context](/cli/guides/context.md) to discover organizations and projects and choose one you can access. ## Configure without signing in `configure` saves defaults without authenticating. Run it interactively to review the selected profile's settings: ```bash tp configure ``` To save connection settings without prompts: ```bash tp --base-url https://thinkplatform.example --audience api://YOUR_API --auth-mode azure-cli configure --no-prompt tp auth login ``` `configure --reset-context` clears saved organization/project defaults when writing configuration. Review the effective context again before continuing. ## Work with profiles Profiles keep connection and default context settings for different environments. Configuration is written to `~/.config/thinkplatform/config.json`, unless `THINKPLATFORM_CONFIG_PATH` selects another file. ```bash tp profile list tp profile show work tp profile use work tp context show ``` `profile use` changes the active saved profile. Successful profile setup, login and configuration also make their selected profile active. A profile is a set of settings; switching it does not sign out of Azure or revoke a credential. Profile selection uses `--profile`, then `THINKPLATFORM_PROFILE`, then the active saved profile (or `default`). Switching profiles changes connection settings; it does not switch the signed-in Azure account. Individual settings use explicit global flags first, environment variables second, and the selected profile third: | Setting | Flag | Environment variables, in precedence order | | --- | --- | --- | | API URL | `--base-url` | `THINKPLATFORM_API_BASE_URL`, `THINKPLATFORM_BASE_URL` | | API audience | `--audience` | `THINKPLATFORM_API_AUDIENCE`, `AZURE_API_AUDIENCE` | | Authentication mode | `--auth-mode` | `THINKPLATFORM_AUTH_MODE` | | Organization | `--org-id` | `THINKPLATFORM_ORG_ID` | | Project | `--project-id` | `THINKPLATFORM_PROJECT_ID` | With no deployment configured, the CLI uses its production service URL and audience defaults. If you configure another URL or audience, provide the matching deployment settings; an unspecified auth mode then resolves to `azure-cli`. Workspace delegation requires an explicit, environment-provided, or profile API URL. Environment overrides can remain effective after switching profiles, so check `context show` whenever you change environments. ## Hand sign-in back to a person When an agent reaches an interactive sign-in prompt, have a person complete it through the normal browser or device-code flow. Resume the task after checking `auth whoami` and the intended context. Do not paste passwords, access tokens, workspace assertions, or credential files into prompts or documentation. The Python SDK can use the same credential modes. See [SDK authentication](/python-sdk/authentication.md) and the [authentication command reference](/cli/reference/commands.md#authentication). ## Secure credential persistence CLI profiles store connection and context settings, not access tokens. Production browser/device credentials use an encrypted operating-system token cache and a separate non-secret account record at `~/.config/thinkplatform/auth/thinkplatform-cli-{hash}.json`, where `hash` is the SHA-256 of the lowercase tenant ID, a colon, and the lowercase client ID. The CLI never stores tokens in plaintext. Removing this account record removes metadata only; it does not revoke or clear the cached session in the operating system's credential store. Treat identity output as account information and review it before sharing logs. Production browser and device-code authentication requires OS-backed encrypted credential storage. The CLI fails closed when that storage is unavailable and does not write tokens in plaintext. On headless Linux systems without Secret Service, use Azure CLI authentication if your deployment allows Azure CLI: ```bash az login --tenant 5a959e94-a278-467d-ab33-d59909a75bad tp --auth-mode azure-cli auth login ``` ## Troubleshooting ### Browser or device-code sign-in reports a missing client ID For the production URL and audience, the shared registration is selected automatically unless client or tenant environment variables override it. For a custom deployment, set `THINKPLATFORM_AZURE_CLIENT_ID` and `THINKPLATFORM_AZURE_TENANT_ID` to its approved values. `AZURE_CLIENT_ID` and `AZURE_TENANT_ID` are accepted as fallbacks. Confirm custom deployment settings with its administrator before retrying. ### Sign-in cannot use secure token storage on Linux The production browser and device-code flows need Linux Secret Service for encrypted token storage. On a headless system without it, use `az login` and `--auth-mode azure-cli` if your deployment allows Azure CLI, as described above. The CLI does not fall back to storing tokens in plaintext. ### macOS asks Python for Keychain access macOS may ask the Python interpreter running `tp` to access the login Keychain for the `ThinkPlatform CLI` encrypted token cache. **Allow** grants access for the current request, so the prompt may appear again. **Always Allow** is optional; choose it only if you recognize and trust that exact Python interpreter. Changing or upgrading the interpreter can trigger another prompt. Your Keychain password stays on your Mac; never share it in chat. If access is denied or the Keychain is locked, sign-in fails and the CLI does not store tokens in plaintext. Managed Agent Workspace managed-identity sign-in does not use your local user Keychain. Older `Microsoft.Developer.IdentityService` items are not read, migrated, or deleted by this CLI flow. ### The account, service, or project is unexpected Inspect `tp profile show` and `tp context show`, then check environment overrides and any explicit global flags. For Azure CLI mode, confirm the account selected in Azure CLI. Run `tp auth whoami` again against the intended service, then select an accessible project using the context guide. ### Workspace delegation cannot acquire a credential Confirm you are in the provisioned workspace with its expected API URL and context. Missing or expired assertions, missing workspace settings, managed identity configuration, or unavailable permissions need attention from the workspace administrator. Do not substitute credentials from another workspace. ### Sign-in succeeds but an operation is denied Authentication identifies the caller; access still depends on the service's permissions and selected organization/project. Confirm the account and context, then ask your administrator for the access required by the specific operation. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /cli/guides/upgrading.md # Upgrade to client 0.6.134 Update the CLI and SDK while keeping your profiles and adapting older Apps commands. ThinkPlatform-client **0.6.134** is available on PyPI. Activate the environment in which you use `tp`, then upgrade: ```bash python -m pip install --upgrade ThinkPlatform-client tp --version tp context show ``` The expected version is `0.6.134`. Upgrading the client preserves saved profiles; check the selected project before continuing. You do not need to rerun profile setup unless you want to change the connection. If another version appears, check `command -v tp` on Bash or `Get-Command tp` on PowerShell and activate the intended environment. See [Installation](/cli/get-started/installation.md) for supported Python versions and platforms. ## Update older Apps commands The `apps` command now publishes and manages container-backed web apps. Dynamic UI and scheduled automation have separate command groups. | Older command | Current route | | --- | --- | | `tp apps ui …` | `tp dynamic-ui …` | | `tp apps cycle …` | `tp automation schedules …` | | `tp apps create-sample …` | Removed. Create the required resources explicitly, or publish an application you have prepared. | Start with a read or command help: ```bash tp dynamic-ui list tp automation schedules list tp apps list tp apps publish --help ``` Subcommand options can differ; inspect the [CLI reference](/cli/reference/commands.md) before updating scripts. The Python SDK's existing `client.apps.ui` and `client.apps.cycle` namespaces remain available. Container publication uses the separate `client.hosted_apps` namespace. ## New workflows - [Publish a web app](/cli/guides/apps.md) from source or an immutable Registry image, then open it on a Canvas application page. - [Use the SDK inside a Hosted App](/python-sdk/hosted-apps.md) with request-bound authorization. - [Execute and inspect Lakehouse statements](/python-sdk/lakehouse.md) and configure a job with `tp lakehouse jobs schedule`. - Use the [app development skill](/agent-skills/thinkplatform-app-development/references/commands.md) for an external coding agent. These clients call your deployment's APIs. Installing a newer client does not enable Hosted Apps, provision infrastructure, or grant permissions. Ask your administrator whether the workflow is enabled for your project. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /cli/guides/agent-setup.md # Connect a coding agent Connect an agent to ThinkPlatform documentation and install bundled CLI guidance. Give your coding agent access to ThinkPlatform documentation and task-specific skills. It can read Markdown pages and LLM indexes, discover task skills, or use guidance bundled with the CLI. Access to documentation does not grant permission to operate on ThinkPlatform resources. ## Read Markdown and LLM indexes The documentation is public. Fetch [the compact index](https://docs.thinkplatform.ai/llms.txt) to find relevant pages, or [the full documentation](https://docs.thinkplatform.ai/llms-full.txt) when your agent needs the complete content. Individual pages are available as Markdown using the page's `.md` route or a request with `Accept: text/markdown`. For example, read [the CLI overview as Markdown](https://docs.thinkplatform.ai/cli/get-started/overview.md), then follow links to installation, authentication, and the commands for your task. Check that a fetch returned the expected text before using it. ## Discover task skills Skills describe how to complete tasks such as preparing datasets, managing agents, or building Canvas dashboards. In **Developers**, browse the **Agent skills** group for command references, examples, and report templates. Read the instructions for your task, then follow their links to supporting pages as needed. For clients that fetch skills directly, [the skill catalog](https://docs.thinkplatform.ai/skill.md) provides discovery. Machine-readable catalogs are available at [the skills index](https://docs.thinkplatform.ai/.well-known/skills/index.json) and [the agent skills index](https://docs.thinkplatform.ai/.well-known/agent-skills/index.json). Retrieve the instructions for your task and follow their links to supporting references and templates as needed. If your client cannot retrieve the documentation or skill references, use the CLI's bundled guidance below. ## Use locally bundled CLI guidance Install the [CLI](/cli/get-started/installation.md) to inspect and install the plugin and skills bundled with that CLI version. `tp plugins` operates on local bundled content and does not require a ThinkPlatform login. Installed guidance helps an agent choose commands; the agent still needs an authenticated CLI and access to the intended organization and project for platform operations. ## Find the right guidance List the bundled plugin and its skills, then ask for guidance matching your task: ```bash tp plugins list tp plugins recommend datalake upload-file tp plugins recommend mlops jobs ``` Recommendations include a `skill_id` and a `show_command`. Read the recommended instructions before installing. For the bundled MLOps skill: ```bash tp plugins show thinkplatform tp plugins show thinkplatform --file skills/thinkplatform-mlops/SKILL.md ``` Without `--file`, `show` displays the bundled plugin manifest. With global `--json`, it returns an object containing `id`, `file`, and `content`; without it, the file content is printed directly. Recommendation results depend on the guidance included in your installed CLI version. ## Install the full plugin For Codex, inspect the proposed destination and files, then install: ```bash tp plugins install thinkplatform --target codex --dry-run tp plugins install thinkplatform --target codex tp plugins doctor --target codex ``` The install result reports `destination`, `files`, and `dry_run`, plus marketplace registration information where applicable. Review those paths. `doctor` checks local plugin and manifest paths and whether a marketplace file exists. It does not check platform authentication, prove the agent has loaded the instructions, or validate a skill's execution. Follow your agent's normal workflow to load newly installed guidance. Other supported targets are `agents`, `claude`, and `dir`. The `agents` target uses the current repository as its root. The `claude` target installs bundled skill folders into the Claude-compatible skills location. For an explicit plugin directory, supply `--dest`: ```bash tp plugins install thinkplatform --target dir --dest ./agent-guidance --dry-run tp plugins install thinkplatform --target dir --dest ./agent-guidance tp plugins doctor --target dir --dest ./agent-guidance ``` This example writes a `thinkplatform` plugin folder below `./agent-guidance`. A directory export still needs to be loaded by the consuming agent. ## Install one skill instead Choose a `skill_id` from `plugins list` or `plugins recommend`. To install only the MLOps skill into Codex's skill directory: ```bash tp plugins install-skill thinkplatform-mlops --target codex --dry-run tp plugins install-skill thinkplatform-mlops --target codex ``` Check `destination` and `files` in the result. For Codex, `doctor` checks plugin installation paths, so it is not a verification command for a standalone skill install. Inspect the reported skill folder and confirm it is available in your agent. Both install commands refuse an existing destination by default. If you intend to replace it, review the plan with `--force --dry-run`, then use `--force`; replacement creates a timestamped backup. Do not overwrite local customizations without reviewing them. ## Connect the agent to the correct project Have a person run `tp profile setup` in the terminal environment where the agent invokes `tp`. It guides sign-in and organization/project selection, saving the profile after confirmation. The wizard requires an interactive terminal and rejects JSON output and root `--query`; agents should use the prepared profile rather than automate the wizard. For unattended setup, use the [manual context commands](/cli/guides/context.md#manual-selection-for-scripts) and `configure --no-prompt` with explicit settings and discovered IDs. Authentication can still require a person to complete sign-in. Before a platform write, have the agent inspect: ```bash tp context show ``` Give the agent the intended profile or destination, task scope, and permitted changes. Ordinary commands such as `tp canvas pages list` reuse the saved context; root `--json` is optional for machine parsing. Use explicit global `--org-id` and `--project-id` overrides when a task must not depend on a saved default. `tp skills` is a separate, remote platform skill registry scoped to an organization and project. Installing bundled guidance with `tp plugins` does not upload a platform skill, change an Agent's configuration, or register a remote skill. Use the [command reference](/cli/reference/commands.md) for those separate operations. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /cli/guides/context.md # Choose an organization and project Save your organization and project once, then use short commands. Complete [installation](/cli/get-started/installation.md) and [authentication](/cli/get-started/authentication.md) first. ## Choose a project interactively At a terminal, run: ```bash tp profile setup ``` Enter a profile name, review the connection settings, and complete sign-in. Choose an organization and project from the numbered lists of names, then confirm the summary. Setup saves and activates the profile after confirmation; IDs are displayed only to distinguish entries. Cancelling, empty results, or an authentication/API error leaves the saved configuration unchanged. Setup makes service reads only. It requires an interactive terminal and rejects JSON output and root `--query` before sign-in or network access. For agents or scripts, use the manual commands below. ## Use your saved context ```bash tp context show ``` Check the profile, organization and project shown here. Once they are saved, everyday commands use that context automatically: ```bash tp canvas pages list tp flows list ``` You do not need to repeat `--profile`, `--org-id`, `--project-id`, or `--json` on these commands. Normal output uses the default `auto` renderer. Environment overrides still take precedence over saved settings, so check the effective context before making changes. ## Manual selection for scripts For non-wizard setup, first prepare authentication using your deployment settings. Discover the choices: ```bash tp context orgs tp context projects --org-id ORG_ID ``` Replace `ORG_ID` with an organization ID from the first result. Choose a project from the second result, then save both IDs: ```bash tp context use --org-id ORG_ID --project-id PROJECT_ID tp context show ``` `context use` checks access to the organization and project before saving them to the selected local profile. The options after `context use` are required for this one-time selection; they are not needed on each later command. `context show` also reports the service URL, audience, authentication mode and config path. A saved project does not imply current permission: service authorization still applies to every request. ## Switch between saved profiles To create or update a named profile interactively, run `tp profile setup` and enter its name. The wizard resolves connection defaults for that target profile, rather than copying the previously active profile. For offline connection settings, use `tp --profile work configure`, then select context with the manual commands above. For unattended configuration after discovery, save explicit IDs without prompts: ```bash tp --org-id ORG_ID --project-id PROJECT_ID configure --no-prompt ``` Use the intended prepared profile and connection settings. This saves local defaults without authenticating or checking service access. Later, switch to an existing saved profile such as `work` with: ```bash tp profile use work tp context show ``` Use `tp profile list` to see saved names and `tp profile show` to inspect the selected profile. Selecting a profile does not switch the signed-in Azure account. ### Override the profile or destination for one command Global options go **before** the command path. Use an override only when this invocation should differ from the active profile: ```bash tp --profile staging canvas pages list tp --org-id ORG_ID --project-id PROJECT_ID canvas pages list ``` These overrides do not change the active profile or its saved context. `context projects --org-id` is a command-local discovery option, while the identically named root option overrides the invocation's default context. Profile selection uses `--profile`, then `THINKPLATFORM_PROFILE`, then the active saved profile (or `default`). Individual settings use explicit flags, then environment settings, then the selected profile. See [authentication](/cli/get-started/authentication.md#work-with-profiles) for the full precedence table. ### Read context as JSON for a script ```bash tp --json context show ``` An abbreviated result is `{"profile":"work","org_id":4,"project_id":18}`. Use IDs from your own environment. This JSON flag is optional for normal terminal use; scripts that parse JSON should request it explicitly. See [scripting and output](/cli/guides/automation.md). If discovery fails, confirm the active profile and identity, then check access with your administrator. Do not guess IDs. See the [command reference](/cli/reference/commands.md) for all profile and context options. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /cli/guides/canvas-pages.md # Read and update a Canvas page Find content, export it, and make a verified page edit. Start with [installation](/cli/get-started/installation.md), [authentication](/cli/get-started/authentication.md), and a verified [project context](/cli/guides/context.md). Replace `PAGE_ID` below with an ID returned by your project. ## Find and read a page ```bash tp canvas pages list tp canvas pages search 'Release notes' tp canvas pages get PAGE_ID ``` Replace `PAGE_ID` with an ID from the list. These commands use your active profile and saved project context. Search examines titles and blocks. Full `get` returns a page object whose content is in top-level `blocks`, with metadata such as `id`, `title`, and `updatedAt`. For a large inventory, add `--limit` and `--offset` to `pages list`; those options slice the fetched list locally. Continue offsets until a slice is empty, and account for concurrent changes when collecting a full inventory. Use `--fields id,title,parentPageId,updatedAt` to select a compact view, or `--summary` with `pages get` for a compact page summary. ### Optional filters and paging ```bash tp canvas pages list --fields id,title,parentPageId,updatedAt --limit 20 --offset 0 tp canvas pages list --fields id,title,parentPageId,updatedAt --limit 20 --offset 20 ``` `--fields` selects a compact view; `--limit` and `--offset` slice the fetched list locally. Export the project pages before editing: ```bash tp canvas pages export --format jsonl --fields id,title,blocks > pages.jsonl tp canvas pages export --format markdown > pages.md ``` Exports fetch page documents. JSONL is one JSON record per line; Markdown is text. Treat an interrupted export as incomplete and check the exit status before using the file as a backup. ## Create a small document The Home commands provide convenient text authoring for the same Canvas pages. Preview the request, then run the same create command without `--dry-run` when the destination and content are correct: ```bash tp home pages create --title 'Release notes' --content 'Initial release checklist.' --dry-run tp home pages create --title 'Release notes' --content 'Initial release checklist.' ``` A preview returns `ok`, `dry_run`, `method`, `path`, `params`, and `body`; it does not create a page. The actual create returns the backend page result. Copy its page ID, then verify the stored document: ```bash tp canvas pages get PAGE_ID ``` ## Append and verify ```bash tp home pages update PAGE_ID --append-content 'Review completed.' --dry-run tp home pages update PAGE_ID --append-content 'Review completed.' tp canvas pages get PAGE_ID ``` `--append-content` preserves existing blocks and adds a text block. `--content` and `--blocks` replace the page blocks; choose them only when you intend replacement. The Home update command reads the current page and sends its `updatedAt` as `expectedUpdatedAt`. An update preview can therefore perform a read even though it does not write. On a conflict, fetch the page again, reconcile your change, and preview again. Do not bypass conflict protection with `--force` or blindly repeat an append: a timeout may occur after the server accepted it. Read the page first to see whether your text is already present. Compare the final blocks and title with your intended result. See the [command reference](/cli/reference/commands.md) for structured Canvas editing. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /cli/guides/apps.md # Publish a web app Build a container app from source, publish it behind ThinkPlatform authentication, and open it from Canvas. Use **ThinkPlatform-client 0.6.134** with an authenticated saved profile for the intended organization and project. Hosted Apps and source builds must be enabled and configured by your deployment administrator. You need permission to publish to the project and use its Registry and build infrastructure. This guide publishes a small new app; do not reuse an existing app ID without reviewing its current release. ## Prepare a small application Create an `app-example` directory containing these two files. This example serves a static page and requests no Table or Lakehouse access. ```html index.html Inspection app

Inspection app

Published with ThinkPlatform.

``` ```dockerfile Dockerfile FROM python:3.12-slim WORKDIR /app COPY index.html . CMD ["python", "-m", "http.server", "8080", "--bind", "127.0.0.1"] ``` The app listens on loopback port `8080` inside its container; the ThinkPlatform authentication sidecar provides browser access. Source publication builds a Linux amd64 image remotely, so an Agent Workspace does not need a local Docker daemon. Test the page locally before uploading your source. ## Create the companion Dynamic UI The publication API requires a companion HTML Dynamic UI in the same project. Save this as `companion-ui.json`: ```json { "renderer": "html", "title": "Inspection app", "owner": {"scope": "project"}, "html": "Inspection app" } ``` ```bash tp dynamic-ui create --body @companion-ui.json ``` Record the returned `uiId` as `UI_ID`. The companion identifies the app's project resource; the container serves the actual UI. ## Publish and inspect Generate one request UUID and save it with your publication inputs. In Bash: ```bash REQUEST_UUID=$(python -c 'import uuid; print(uuid.uuid4())') tp apps publish inspection-app --name "Inspection app" --source ./app-example --ui-id "$UI_ID" --request-id "$REQUEST_UUID" tp apps show inspection-app ``` On PowerShell, assign the UUID with `$REQUEST_UUID = [guid]::NewGuid().ToString()` and pass `$UI_ID` and `$REQUEST_UUID` in the same command. Set `UI_ID` to your actual returned value first. Inspect readiness, release and URL. The default wait is 300 seconds; a timeout does not prove that publication failed. Retain the request UUID, source and options, inspect the recorded state, and resume the same operation when appropriate. Do not repeatedly submit new request IDs while an earlier result is uncertain. ### Use an image, grant data access, or control waiting Use `--image` instead of `--source` for an authorized Registry image with an immutable `@sha256:` digest. Source upload is limited to 50 MiB compressed. The CLI does not interpret `.dockerignore`: within Git it uses tracked and nonignored untracked files, plus built-in exclusions. Review tracked inputs and use `.gitignore` for local-only files. Outside Git, prepare a dedicated source directory. Exclude credentials, profiles and unrelated data yourself. Use repeated `--table-read` or `--table-write` options for exact Table IDs, `--lakehouse-read` for delegated Lakehouse reads, and `--project-permission` only for an accepted read permission shown in help. Publication permissions, the current user's permissions and resource scope all apply. The app must use the [request-bound SDK](/python-sdk/hosted-apps.md); do not put a personal token in the image. Keep `--legacy-table` only for existing apps that require that separate bridge. `--wait 0` submits one step without polling. Other values range from 0 to 1800 seconds. Keep the same request ID and inputs when resuming; an explicitly terminal failure requires diagnosis rather than an automatic resubmission loop. ## Open it from Canvas Save `app-page.json` with the stable app ID: ```json { "title": "Inspection app", "layout": {"surface": "application", "contentWidth": "full"}, "application": {"source": {"kind": "hosted-app", "appId": "inspection-app"}}, "blocks": [] } ``` ```bash tp canvas pages create --body @app-page.json ``` Open `/canvas/PAGE_ID` on your ThinkPlatform host, replacing `PAGE_ID` with the returned page ID. Check that **Inspection app** appears. If permissions were requested, review the consent before continuing. A successful CLI publication alone does not verify another person's access or an app's data writes; test the intended action and read its stored result back. ## Update or stop an app Read the current release first: ```bash tp apps show inspection-app ``` For an update, generate a new request UUID and publish with `--replaces` set to the exact previous release. Retain that release and the new UUID on retries. Use `--replaces-stopped` only if that exact previous release is stopped. Inspect `tp apps publish --help` for `--replace-current` and the full update options. To stop a release you own and intend to retire: ```bash tp apps stop inspection-app --release "$RELEASE" tp apps show inspection-app ``` Set `RELEASE` to the inspected release ID. Stopping unpublishes the release and stops its runtime; preserve shared Tables, files and Canvas pages unless you intend to remove those separately. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /cli/guides/database-tables.md # Inspect a shared database table Discover a table, inspect its schema, and retrieve a small sample of rows. Complete [installation](/cli/get-started/installation.md) and [authentication](/cli/get-started/authentication.md), then select your [organization and project](/cli/guides/context.md). This task reads an existing shared database table; it does not create one. ## Discover the table and schema ```bash tp db tables list tp db tables list --name Inventory tp db tables get --table-id table-example ``` Replace `table-example` with an ID from the list. The list command returns an array; `--name` filters names by a case-insensitive substring. For a compact view, add `--fields id,name,schema_version`. For a large list, `--limit` and `--offset` shape the fetched records locally. `tables get` is the CLI's table description and schema inspection command. Its object includes `id`, `name`, `schema_version`, `columns`, and access metadata. Inspect `columns` before building queries. There are no separate `db tables describe`, `schema`, or `preview` commands. ## Preview a bounded row sample ```bash tp db rows query --table-id table-example --body '{"filters":[],"sort":[],"page":1,"page_size":5}' ``` The JSON body is the backend query, so this asks the server for a small sample. A query result has an `items` array and a `meta` object. Each row has an `id` and user column values under `data`, alongside row metadata. This abbreviated example shows how row values are nested: ```json {"items":[{"id":"row-example","data":{"sku":"SAMPLE-001"}}],"meta":{}} ``` After confirming that your table actually has a `sku` column, project it or export a bounded sample: ```bash tp db rows query --table-id table-example --body '{"filters":[],"sort":[],"page":1,"page_size":5}' --fields id,data.sku tp db rows query --table-id table-example --body '{"filters":[],"sort":[],"page":1,"page_size":5}' --fields id,data.sku --format jsonl > sample.jsonl tp db rows get --table-id table-example --row-id row-example ``` Replace `row-example` with an ID from the query. Compare its `data` with the sample to verify you selected the correct table and row. `--fields` can use dotted paths; projection changes the displayed shape. Optional command-local `--limit` and `--offset` slice the received rows, whereas `page` and `page_size` inside `--body` are sent to the server. Local slicing does not fetch another server page. Inspect returned `meta` and the deployed query contract before implementing pagination. If you get an empty sample, check context, table access, and the table ID before changing the query. A missing projected column may indicate a schema mismatch. Use [API discovery](/cli/guides/api-requests.md) to inspect deployed request requirements rather than guessing filters. For reusable code, see the [SDK database workflow](/python-sdk/database.md) and [error handling](/python-sdk/errors.md). All CLI options are in the [command reference](/cli/reference/commands.md). ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /cli/guides/files.md # Upload and inspect Data Lake files Upload local files, inspect paged listings, and resolve project Data Lake paths. Complete [installation](/cli/get-started/installation.md), [authentication](/cli/get-started/authentication.md), and [context selection](/cli/guides/context.md). This guide uses the `datalake` command group. ## Choose the destination These examples use your active profile and saved project context. Check the destination before uploading: ```bash tp context show ``` Use an explicit logical namespace. `project/uploads/example.csv` refers to the selected project's Data Lake area. `shared/` addresses shared storage, subject to access. `legacy/` is read-only. Bare paths are interpreted relative to `project/`; they do not address historical root-level blobs. The CLI rejects `..` segments and writes targeting another project's `projects/PROJECT_ID/` namespace, where `PROJECT_ID` is that other project's identifier. ## Plan and upload one file Choose a new destination and replace `./example.csv` with an existing local file. Review its path and size in the plan before executing: ```bash tp datalake upload-file \ --local-path ./example.csv \ --remote-path project/uploads/example.csv \ --dry-run tp datalake upload-file \ --local-path ./example.csv \ --remote-path project/uploads/example.csv ``` The dry run builds a local upload plan without requesting upload URLs or uploading bytes. Actual uploads use ThinkPlatform-issued SAS URLs. On success, inspect `ok`, `uploaded_count`, and `uploads`, then verify the remote listing. Do not treat a failed or interrupted upload as proof that no bytes were stored. Check the destination before repeating it. For a directory, relative file paths are preserved below the remote prefix. The local directory must contain at least one file: ```bash tp datalake upload-dir \ --local-dir ./dataset \ --remote-prefix project/uploads/dataset \ --dry-run ``` Inspect the complete file list before running the same command without `--dry-run`. Choose only files intended for that project. Upload transport options are documented in `tp datalake upload-dir --help` and the [command reference](/cli/reference/commands.md). ## Inspect directories and files `tree` lists child directories; `list` includes files and directories. Start with the directory you want to inspect: ```bash tp datalake tree \ --path project/uploads tp datalake list \ --path project/uploads ``` The tree result is an array. The list result contains `items` and may contain a continuation token. Inspect the actual token field (`continuationToken` or `continuation_token`) before requesting another page: ```bash tp datalake list \ --path project/uploads --continuation-token 'TOKEN_FROM_PREVIOUS_RESULT' ``` Replace the quoted token with the value returned for that listing. `--limit`, `--offset`, and `--path-contains` shape the fetched records locally; a local limit does not request a backend page of that size or prove the directory has only that many entries. Advance the local offset to inspect the rest of a fetched page before following its continuation token. For a complete inventory, `list --all` follows continuation pages. It fetches all pages before applying local limits, so avoid it for an initial exploratory read. `--format jsonl` emits one item per line and omits the surrounding page metadata; use ordinary JSON while discovering continuation tokens. ## Preview or resolve a selected path Copy an exact path from the listing: ```bash tp datalake preview \ --path project/uploads/example.csv tp datalake resolve-uri \ --path project/uploads/example.csv ``` Preview prints the endpoint's JSON or text response. A binary response requires `--output`; this saves the raw preview response and does not promise the original file or a full-file download: ```bash tp datalake preview \ --path project/uploads/example.csv --output ./example.preview ``` The preview endpoint determines content and size; the command has no row-limit or byte-limit option. Use it on a selected file rather than looping through an entire directory. `resolve-uri` returns fields including `abfss_uri`, `logical_path`, `physical_path`, and `scope`. Inspect the returned URI for downstream tools that support ADLS; resolution does not transfer file contents or grant those tools access. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /cli/guides/execution.md # Run work and inspect its outcome Keep Flow runs, Agent tasks, and MLOps jobs distinct while checking status and results. Complete [authentication](/cli/get-started/authentication.md) and [context selection](/cli/guides/context.md) first. These examples use your active profile and saved project context. Confirm the destination before starting work: ```bash tp context show ``` Choose commands according to the resource you are operating on: | Resource | Start or submit | Inspect | | --- | --- | --- | | Flow | `flows run FLOW_ID` | Inspect the run response and follow the instructions for that execution mode | | Agent task | Prepare a runtime or create a task, then `tasks post-message TASK_ID` | `tasks get`, `status`, and `messages` | | MLOps job | A workload-specific submission command | `mlops jobs get`, `wait`, `logs`, and `metrics` | A Flow ID, task ID, and MLOps job ID identify different resources. A Flow run does not necessarily create an MLOps job. Do not pass an arbitrary returned `id` into another command group. ## Run an existing Flow Discover the Flow and inspect its `id`, `mode`, `device`, and `input_schema`: ```bash tp flows list ``` This command returns the project's Flow array and has no list limit option. Read only the fields needed for your chosen Flow. Prepare `./flow-input.json` as a JSON object matching that Flow's input schema. Use `{}` only when the Flow accepts no required inputs. Replace `FLOW_ID_FROM_LIST` below with the exact selected ID: ```bash tp flows run 'FLOW_ID_FROM_LIST' \ --input @./flow-input.json ``` The command submits to the Flow runs endpoint and prints the returned JSON object. Inspect it before selecting any ID, status, result, or follow-up URL: the CLI does not impose a single response schema or automatically wait for completion. There is no universal Flow results or logs command in this command group. Follow the instructions for checking progress and retrieving results for that Flow's execution mode. If the response identifies a separate MLOps job, use that confirmed job ID with the job commands below. `--device` overrides the device for an IoT-backed run. The current `flows run --dry-run` request preview shows a different endpoint from the actual run submission, so it is not an authoritative preview of the executed request. Confirm the selected Flow and inputs before invoking a run. ## Send work to an Agent task Find the Agent in your saved project context: ```bash tp agents list tp tasks list ``` Inspect IDs and names before selecting an Agent. Agent and task lists support `--offset` for subsequent slices. Use an existing task when continuing its conversation. For a new chat runtime, replace example Agent ID `27` with the selected Agent's ID: ```bash tp tasks prepare-runtime --agent-id 27 --private ``` Inspect the response's `task_id`, `thread_id`, `status`, and `reused`. This operation can reuse a runtime. Use its numeric `task_id` for `tasks` commands; the thread ID is a different identifier. Alternatively, `tasks create --agent-id 27 --title "Review the sample"` creates a task record and returns its `id`. Creating a record or preparing a runtime alone does not demonstrate that your requested work completed. Replace example task ID `83` with the returned task ID. Review the prompt preview, then submit: ```bash tp tasks post-message 83 \ --prompt 'Summarize the sample data available to this task.' --dry-run tp tasks post-message 83 \ --prompt 'Summarize the sample data available to this task.' tp tasks status 83 tp tasks get 83 tp tasks messages 83 --summary ``` Inspect the returned status fields for completion, errors, or a request for user input. A successful `post-message` request confirms acceptance of that request, not successful completion of the task. `messages --summary` reports message counts and sizes without message content, but still fetches the messages. For a bounded read of recent checkpoint content, use the `thread_id` returned by runtime preparation or task details: ```bash tp agents tasks checkpoints 'THREAD_ID_FROM_RESULT' \ --limit 20 --direction newest ``` Inspect `messages` and `returned` in the checkpoint page; a recent slice is not the complete conversation. If you need the task messages response, use: ```bash tp tasks messages 83 ``` That command has no message-limit option. The CLI has no generic task wait command; space out status checks and impose a deadline in your own automation. ## Follow an MLOps job For one training submission, find a registered dataset and a supported architecture in your saved project context: ```bash tp mlops data list tp mlops data versions 'DATASET_NAME_FROM_LIST' tp mlops hyperparameters architectures tp mlops hyperparameters get 'ARCHITECTURE_FROM_LIST' ``` Replace the quoted names with discovered values. Read the architecture's schema and prepare `./hyperparameters.json` as a matching JSON object. Choose the intended output model name. The architecture list and schema reads have no local limit option. Check compatibility with the dataset before submitting; training can allocate compute. Review the request, then submit it once: ```bash tp mlops train submit \ --model-name 'CHOSEN_OUTPUT_MODEL_NAME' \ --architecture-name 'ARCHITECTURE_FROM_LIST' \ --dataset-name 'DATASET_NAME_FROM_LIST' \ --dataset-version 'VERSION_FROM_DATASET_VERSIONS' \ --hyperparameters @./hyperparameters.json --dry-run tp mlops train submit \ --model-name 'CHOSEN_OUTPUT_MODEL_NAME' \ --architecture-name 'ARCHITECTURE_FROM_LIST' \ --dataset-name 'DATASET_NAME_FROM_LIST' \ --dataset-version 'VERSION_FROM_DATASET_VERSIONS' \ --hyperparameters @./hyperparameters.json ``` Inspect the full submission response. Copy its actual `job_id` into the commands below, after confirming it identifies the submitted MLOps job. The response comes from the server without a fixed client model; if no usable `job_id` is present, inspect the response and job inventory before continuing. Do not substitute a model ID, a Flow run ID, or a guessed job name. To find an existing job or reconcile a submission: ```bash tp mlops jobs list ``` Inspect the returned collection before extracting an ID. Local `--name`, `--status`, `--limit`, and `--offset` shape the fetched job collection; they do not guarantee backend pagination. Replace `JOB_ID_FROM_RESULT` with the exact job ID: ```bash tp mlops jobs get 'JOB_ID_FROM_RESULT' tp mlops jobs wait 'JOB_ID_FROM_RESULT' \ --interval-seconds 10 --timeout-seconds 600 tp mlops jobs logs 'JOB_ID_FROM_RESULT' --tail 50 tp mlops jobs metrics 'JOB_ID_FROM_RESULT' ``` `wait` returns `job_id`, `status`, `terminal`, polling details, and the last `job`. It exits `0` for a recognized successful terminal state and `1` for a recognized failure or a polling timeout. A timeout result has `timed_out: true` and `terminal: false`; it stops waiting and does not cancel the job. Unknown statuses continue polling until the deadline. `watch` provides the same bounded polling with progress output when JSON mode is off. `logs --tail 50` trims the fetched logs locally. Use `--contains` to filter or `--output ./job.log` to save them. `stream-logs` waits for the backend stream to finish and has no command-level duration limit, so prefer fetched logs for bounded inspection. Metrics and job details are separate from application result artifacts: inspect the actual returned metadata and use the workload's documented artifact retrieval workflow. Do not assume a generic `results` command exists. If a run submission, runtime preparation, or message post times out, the server may already have accepted it. Reconcile task lists, messages, job inventories, and any returned identifiers before retrying. Do not automatically repeat mutations: duplicate runs or prompts can create duplicate work. See [scripting and output](/cli/guides/automation.md) for exit status and partial-output handling, and [troubleshooting](/cli/guides/troubleshooting.md) for recovery checks. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /cli/guides/api-requests.md # Discover and call an API operation Use the deployed OpenAPI schema to resolve a request before sending it. Complete [installation](/cli/get-started/installation.md), [authentication](/cli/get-started/authentication.md), and [context selection](/cli/guides/context.md). API discovery reads the OpenAPI schema from your configured service, so it requires connectivity and may require authentication. ## Find the operation ```bash tp api operations ``` The result is an array of operation records. Add `--path-contains /jobs` to narrow the list, or `--fields operation_id,method,path,request_body_required` for a compact view. `--limit` and `--offset` slice the fetched records locally. Choose the exact `operation_id` from your deployment and inspect it before calling it. The following example uses `get_job`. Use that operation ID only if discovery returns it for your service; otherwise, substitute the operation ID and parameters shown by your service. ```bash tp api show get_job ``` The description includes `method`, `path`, `parameters` with their `in` and `required` fields, and `request_body_required`. The example below assumes a job read with a `job_id` path parameter and a required `org_id` query parameter. ## Resolve, then call Replace `job-example` with a job ID obtained from your project. Supply every required path and query parameter. Organization/project parameters can be filled from effective CLI context when the operation defines them. ```bash tp api call get_job --path-param job_id=job-example --dry-run ``` Review the method, destination, query, and body. The CLI resolves the request against OpenAPI, but a preview is not a guarantee that the server will accept the payload. `--dry-run` still fetches the schema. Once the request is correct, perform the read: ```bash tp api call get_job --path-param job_id=job-example ``` The result is the backend response, not a universal CLI envelope. Confirm it describes your intended job. For operations requiring JSON, `--body` accepts a JSON string or `@request.json`; inspect the deployed schema for its required structure first. Missing required parameters or required bodies produce an error before the target request is sent. ### Optional machine-readable request preview Add global `--json` when you need to capture or parse the preview: ```bash tp --json api call get_job --path-param job_id=job-example --dry-run ``` Example output: ```json {"ok":true,"dry_run":true,"method":"GET","path":"/api/mlops/jobs/job-example","params":{"org_id":"ORG_ID_FROM_CONTEXT"},"body":null} ``` Authenticated CLI API and raw requests accept relative paths or absolute URLs only when the URL's HTTP(S) origin exactly matches the configured API origin (scheme, normalized host, and effective port). Explicitly configured HTTP deployments remain supported, but an HTTPS API cannot be downgraded per request. Invalid or ambiguous URLs and origin mismatches are rejected before credentials are acquired. Redirects are not followed. ## Keep the two query options distinct ```bash tp --json --query status api call get_job --path-param job_id=job-example ``` Before `api`, global `--query status` selects a field from the response. After `call`, command-local `--query name=value` adds an HTTP query parameter; use this to supply HTTP query values explicitly. Organization and project values can otherwise come from saved context when the operation defines them. The output selector supports field paths and list indices, not JMESPath filters or expressions. Only select `status` after verifying that field exists in the full response. If discovery finds no match, broaden the path filter and inspect the available operation IDs. If a write times out, inspect server state before retrying; request previews do not make writes idempotent. See the [command reference](/cli/reference/commands.md), [SDK overview](/python-sdk/overview.md), and [SDK errors](/python-sdk/errors.md). ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /cli/guides/automation.md # Capture CLI output in a script Check exit status, preserve diagnostics, and consume structured read results. Complete [installation](/cli/get-started/installation.md), [authentication](/cli/get-started/authentication.md), and [context selection](/cli/guides/context.md) before running unattended reads. Prepare the profile in advance; authentication can require user interaction. This guide shows how to capture a Canvas page inventory for another program. ## Check context, then capture a read ```bash tp context show ``` Confirm the active profile, organization and project. These examples use that saved context. Add `--json` when another program needs to parse the result, then run this shell script: ```bash if tp --json canvas pages list --fields id,title,updatedAt > pages.json 2> pages.err; then python3 -c 'import json; pages=json.load(open("pages.json")); print("Pages:", len(pages))' else cat pages.err >&2 exit 1 fi ``` Successful ordinary JSON commands write their result to stdout and exit `0`. This list is an array, so the script parses it before using it. On failure, treat `pages.json` as unusable even if it exists or contains some data. Keep stderr separate so diagnostics cannot corrupt JSON input. Handled authentication, API, context, and value errors exit `1`. With `--json`, these handled errors are JSON objects on stderr with `ok: false` and `error`; API errors may also include `status_code` and `response_body`. Command syntax errors generally exit `2` and may be plain text. Do not assume every failure is JSON, or print diagnostics containing sensitive server details into public logs. ## Select a known field For a program needing just the effective project ID: ```bash tp --json --query project_id context show ``` Global `--query` is a narrow output path selector: it supports keys, dotted fields, and nonnegative list indices, such as `items[0].id`. It is not JMESPath and does not support filters, wildcards, or arbitrary expressions. Missing keys and invalid indices fail; check that an array is nonempty before selecting its first item. JSON strings remain JSON strings, including quotes. ## Handle each command's output contract `--json` is a global option placed before the command. It does not turn every command into one JSON document. Canvas JSONL exports and row queries with `--format jsonl` produce one record per line; Markdown exports produce text; job log streaming produces streamed content. Downloads and other file-oriented commands also need their own contract. Inspect command help and the [command reference](/cli/reference/commands.md) before piping output to a JSON parser. There is no universal `--yes`, `--non-interactive`, or `--dry-run` option. Use only options advertised by the specific command. Some write commands provide previews; an API preview may still fetch OpenAPI, and a Canvas update preview may read the current page. Verify actual stored state after a write. Local `--limit` and `--offset` options often slice a fetched collection. They do not establish that all backend pages were fetched. Record which slices you processed and account for concurrent changes. Interrupted exports or streams can leave partial files; check completion and exit status before promoting them to downstream inputs. A timeout does not prove a mutation failed. Read the resource and reconcile its state before retrying a create, append, or delete. Use bounded retries only when the operation's semantics make repetition safe; do not add a blanket mutation retry loop. Follow [execution workflows](/cli/guides/execution.md) to monitor remote work and [troubleshooting](/cli/guides/troubleshooting.md) to diagnose failures. For longer workflows with typed results and explicit error handling, use the [Python SDK](/python-sdk/overview.md) and its [error guidance](/python-sdk/errors.md). ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /cli/guides/troubleshooting.md # Troubleshoot a failed command Diagnose configuration, authentication, permission, and request errors, and check whether interrupted work completed. Start with the exact command, exit status, and effective context. A successful login establishes an identity; the requested resource still needs to be accessible to that identity. CLI command syntax in these docs targets version **0.6.134**. For supported installation environments, see [installation](/cli/get-started/installation.md). ## Establish what failed Run these reads using the same profile and environment as the failing command: ```bash tp --version tp context show tp auth whoami tp context orgs ``` `context show` reports effective local settings; it does not prove the API is reachable. `auth whoami` makes an authenticated API request. After selecting an authorized organization from the response, discover its projects: ```bash tp --org-id "$ORG_ID" context projects ``` Use the discovered organization and project explicitly when reproducing the resource read. [Projects and profiles](/cli/guides/context.md) explains setting precedence. A shell, scheduled process, or managed workspace can use a different profile, credential, or environment from your interactive terminal. ## Diagnose by symptom | Symptom | Check | Next action | | --- | --- | --- | | `No such command`, `No such option`, or usage exit status `2` | `tp --version` and the exact command's `--help`. Global options go before the command path. | Correct the syntax or use a client version that supports the documented command. Do not retry the same invalid invocation. | | Missing organization or project context | Effective context and the IDs discovered above. | Pass `--org-id` and `--project-id` for the intended resource. | | Token acquisition or interactive login failure | Auth mode and deployment-provided connection settings in [authentication](/cli/get-started/authentication.md). | Complete the authorized login flow or correct the credential configuration. Unattended execution needs a credential prepared for that environment. | | HTTP `401` | Identity, audience, base URL, and credential validity. | Resolve authentication before repeating the operation. See the SDK's [refresh behavior](/python-sdk/errors.md#retry-behavior) when using Python. | | HTTP `403` | Identity **and** organization/project/resource access. | Ask the deployment administrator for the specific operation and resource access required. Changing context or logging in again does not grant permissions. | | HTTP `404` | Base URL, resource ID, context, and whether the resource still exists. | Rediscover it through an authorized listing. The status alone cannot distinguish a missing resource from every deployment's access-hiding behavior. | | HTTP `400` or another validation response | Option types, request body, required fields, and current resource schema. | Correct the request. For DB writes, inspect the table's current schema; for API calls, inspect the deployed operation definition. | | A conflict or stale-version response | Current resource state and the update's version condition. | Read again and reconcile changes. [Canvas updates](/cli/guides/canvas-pages.md) use `updatedAt` conflict protection; do not bypass it just to suppress an error. | | HTTP `429`, server `5xx`, or a transport failure | Response diagnostics and whether the operation can safely be repeated. | For safe reads, use a bounded retry policy and honor a supplied `Retry-After` value. For writes, establish the outcome before repeating. These statuses do not imply a universal CLI retry policy. | | A successful command followed by invalid JSON parsing | The specific command's output mode. | Separate stdout/stderr and inspect the output contract. Logs, downloads, Markdown, and JSONL are not necessarily one JSON document. | These are diagnostic starting points, not a universal error schema for every deployed endpoint. Preserve the actual response privately when further diagnosis is needed. ## A user can read, but an Agent cannot Compare the successful and failing environments, rather than assuming they share credentials: 1. Verify the API base URL and effective organization/project IDs. 2. Inspect the identity using `auth whoami` in each environment. A managed workspace may use workspace delegation instead of the user's interactive credential. 3. Confirm that the failing identity can discover the required organization/project and perform a small read of the intended resource. 4. Ask the administrator to check that identity's access to the named operation and resource. Use the deployment's actual permission vocabulary; there is no documented universal permission flag that fixes every endpoint. Reading a project does not establish permission to upload files, start a job, invoke an Agent, or change a database row. Request the access needed for the actual workflow. Bundled local [Agent skills](/cli/guides/agent-setup.md) teach commands; installing them does not grant platform permissions. ## Recover an uncertain write or run A timeout or interrupted terminal can occur after the service accepted a request. Capture a returned operation/resource ID if one is available. Then inspect the resource or execution status using the appropriate read commands in [execution workflows](/cli/guides/execution.md). For a create without a returned ID, inspect the relevant collection and reconcile candidate resources using your intended attributes and context before deciding whether to submit again. A second create or run may duplicate work. A failure in output projection with `--query` can also happen after a write succeeded. Removing the projection and reading current state helps establish what happened. An expired polling timeout is a limit on how long your client waited; it is not evidence that the remote operation was canceled. Inspect its current status before starting another run. ## Share a useful diagnostic report Include the client version, command path and option names, operation and approximate time, exit status, HTTP status if present, and the expected versus observed behavior. Include a request/correlation identifier only when the service supplies one; the client does not guarantee a common field across all APIs. Redact access tokens, SAS query strings, credentials, private paths, resource contents, and sensitive error bodies before sharing logs. For reproducible scripting, see [scripting and output](/cli/guides/automation.md). Python callers should catch the documented [SDK exceptions](/python-sdk/errors.md) rather than assume CLI exit codes apply to Python. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /cli/reference/commands.md # CLI Reference Short commands for everyday work, with detailed options for people and agents. Examples target CLI **0.6.134** and use your configured **active profile**. Save your organization and project once with [Projects and profiles](/cli/guides/context.md). The CLI reuses those settings, so everyday commands do not need `--profile`, `--org-id`, `--project-id`, or `--json`. Use IDs discovered in your own environment. ## Common reads List pages, Flows, tasks, or tables using your saved context: ```bash tp canvas pages list tp flows list tp tasks list tp db tables list ``` Read a resource using an ID from its list: ```bash tp canvas pages get PAGE_ID tp tasks get TASK_ID tp tasks status TASK_ID tp db tables get --table-id TABLE_ID ``` Replace these placeholders with IDs returned by your service. Default `auto` output renders readable tables or values where appropriate and falls back to JSON for complex results. Resource-specific text, exports and streams retain their own output contracts. ### Filter, select fields, or page through results ```bash tp canvas pages list --limit 5 --fields id,title tp canvas pages list --limit 5 --offset 5 --fields id,title tp tasks list --limit 20 --offset 0 ``` Canvas `--limit` and `--offset` slice the fetched list locally; they do not fetch successive backend pages. The `home pages list` alias does not support these options. Task lists default to 100, allow at most 200 per request, and accept an offset. A first page is not a complete inventory; account for concurrent changes when collecting one. To read table rows, supply the table ID and a backend query body: ```bash tp db rows query --table-id TABLE_ID --body '{"filters":[],"sort":[],"page":1,"page_size":10}' ``` Row values are nested under `data`. The body accepts inline JSON or `@path/to/file.json`; inspect the table's columns and deployed query contract before authoring filters. See [database tables](/cli/guides/database-tables.md) for server pagination and output projection. ## Find the right command ```bash tp commands tp canvas pages list --help ``` `tp commands` shows the command tree. These optional discovery tools also work without authentication: ### More help and command discovery ```bash tp --version tp --help tp commands home --depth 3 tp commands --all tp help home pages create tp home pages create --help ``` `--all` includes top-level aliases. Prefer canonical paths such as `tp auth whoami`, `tp context orgs`, and `tp mlops jobs list` in automation. ## Authentication For interactive onboarding, set up and activate your connection and project: ```bash tp profile setup tp context show ``` Setup asks for a profile name and connection settings, authenticates, lists accessible organizations/projects by name with numbered choices, and saves after confirmation. Cancellation, empty access lists and authentication/API errors preserve saved configuration. It uses service reads only and requires an interactive terminal without JSON output or root `--query`. For an existing profile, use `tp auth login` to sign in again and `tp auth whoami` to verify identity. Agents and scripts should use a prepared profile or [manual context setup](/cli/guides/context.md#manual-selection-for-scripts), including `configure --no-prompt` with explicit settings and IDs. Login resolves a token and saves effective profile defaults; it does not grant new permissions. `tp configure` reviews and saves settings offline. Workspace delegation requires an appropriately provisioned managed workspace. ## Saved context ```bash tp context show ``` Check the active profile, organization and project before starting work. The following commands use those saved defaults. ### Choose a project or switch profiles ```bash tp context orgs tp context projects --org-id ORG_ID tp context use --org-id ORG_ID --project-id PROJECT_ID tp profile list tp profile use work tp context show ``` `context use` checks access and persists both IDs. Its command-local ID options are needed for initial selection, rather than repeated on every resource command. Replace `work` with an existing configured profile. Verify effective context before writes: selecting a saved profile does not switch the signed-in account or establish permission. ## Preview, write, verify These commands change resources when run without `--dry-run`. Review the context and payload first. A preview does not prove server authorization or successful validation; some update previews read the current resource. ```bash tp home pages create --title "Runbook" --content-file ./runbook.md --dry-run tp home pages create --title "Runbook" --content-file ./runbook.md tp canvas pages get PAGE_ID ``` The local file must exist. Capture the returned page ID and use it for the final read. For an existing page, `--content-file` **replaces page blocks**; `--append-content-file` appends a text block. Updates use `updatedAt` conflict protection unless `--force` is supplied. Resolve a conflict by reading and reconciling the current page before trying again. ### Preview an append or task creation ```bash tp home pages update PAGE_ID --append-content-file ./notes.md --dry-run tp tasks create --title "Review the runbook" --description "Verify the published steps." --dry-run ``` Do not blindly retry a create, append, run, invoke, or delete after a timeout: the server may have completed it. Inspect resource state or operation status first. Retry reads only when appropriate for the error, with bounded backoff. A command's presence or dry-run response does not imply idempotency. ## Optional global settings Keep the short commands above for ordinary use. To change a setting for one invocation, put global options **before** the command path: ```bash tp --profile staging canvas pages list ``` This uses the existing `staging` profile for one invocation. To activate it for later short commands, use `tp profile use staging`. ### All global options and precedence ```text tp [GLOBAL_OPTIONS] COMMAND [ARGS]... ``` | Option | Meaning | | --- | --- | | `--profile TEXT` | Select a saved local profile for one invocation. | | `--base-url TEXT` | Override the API base URL. | | `--audience TEXT` | Override the API audience. | | `--auth-mode MODE` | `azure-cli`, `device-code`, `interactive-browser`, or `workspace-delegation`. | | `--org-id INTEGER` | Override the default organization ID. | | `--project-id INTEGER` | Override the default project ID. | | `--output auto\|json\|table` | Output format; default `auto`. `--format` is an alias. | | `--json` | Select JSON output; takes precedence over `--output`. | | `--query PATH` | Select a nested output field, such as `user.username` or `[0].id`. | | `--version` | Print the CLI version and exit. | | `-h`, `--help` | Show root help. Use `--help` after a command for its options. | Profile selection resolves from `--profile`, then the profile environment setting, then the active saved profile. Individual connection/context settings resolve from explicit flags, then environment settings, then the selected profile. Check `tp context show` if a saved setting appears to be ignored. ```bash tp --org-id ORG_ID --project-id PROJECT_ID canvas pages list ``` These global ID overrides affect only that invocation. They differ from the command-local required options after `context use`, which persist the selected context. ## JSON, errors, and query behavior You do not need `--json` for terminal reads. Request it explicitly when another program must parse a JSON result: ```bash tp --json canvas pages list ``` Keep stderr separate and check exit status before parsing. See [scripting and output](/cli/guides/automation.md) for an executable capture-and-parse example. ### JSON errors and exit status Handled authentication, API, missing-context, and value errors exit with status `1`. In JSON mode they emit an error object on **stderr**, with `ok: false` and `error`; API errors may also include `status_code` and `response_body`. Command syntax errors typically exit `2` with text on stderr, even in JSON mode. Unexpected failures are not guaranteed to follow the handled-error schema. Downloads, logs, JSONL, help, and command-specific output modes may have different output contracts; inspect their help before piping to a JSON parser. ### Select one output field ```bash tp --json --query 'user.username' auth whoami ``` `--query` supports object keys and nonnegative list indices, **not** filters, wildcards, or full JSONPath/JMESPath. Quote expressions so the shell does not expand brackets. With `--json`, an extracted string is still a JSON string. Missing keys, out-of-range indices, and wrong value types are errors, not empty results. Projection happens after obtaining the result. A projection failure after a mutation does **not** mean the mutation failed; verify state before retrying. Some commands stream or emit directly and do not use shared projection. ## Discover API operations Operation IDs depend on the connected application. Discover an ID, inspect it, and preview the resolved request: ```bash tp api operations tp api show OPERATION_ID tp api call OPERATION_ID --dry-run ``` Replace `OPERATION_ID` with a discovered ID and supply its required parameters. See [API requests](/cli/guides/api-requests.md) for an example with a required job ID. ### API parameters and URL rules `api call` accepts repeated `--path-param KEY=VALUE`, repeated `--query KEY=VALUE`, and `--body JSON` or `--body @file.json`. Here `--query` is an **HTTP query parameter** because it follows `api call`; root `--query` before the command is an **output projection**. Resolve required parameters from `api show` before invoking an operation. Effective context fills organization/project parameters only when the operation defines them. Authenticated `api call`, `raw`, and `rest` requests accept relative paths or absolute URLs whose HTTP(S) origin exactly matches the configured API origin. Explicitly configured HTTP deployments are supported; HTTPS cannot be downgraded per request. Invalid or ambiguous URLs and origin mismatches fail before credential acquisition. Redirects are not followed. ## Detailed workflow reference Expand a command below for a short example followed by its full syntax and options. All examples use your active profile. A default of “not supplied” means the declaration leaves it unset; profiles, environment settings or the server can supply effective values. “Omitted” means no default is listed. Repeatable options consume one value per occurrence; variadic arguments consume multiple words. Set `PLUGIN_ID` and `SKILL_ID` from `plugins list`; set `FLOW_ID` and `JOB_ID` from the corresponding list commands. Local upload sources must exist. Export and preview examples write local files, signed-URL commands issue access URLs, and polling performs network reads. Flow and Data Lake mutation examples use `--dry-run`. Data Lake `list --limit` and `--offset` shape fetched results locally. Use `--all` to collect continuation pages first, or pass a returned continuation token explicitly. JSONL emits one record per line. Signed URLs grant access until expiry; retain them only where needed for the transfer. Flow payload fields depend on the selected Flow. Inspect its definition and input requirements before authoring `flow-inputs.json`. In the current release, Flow dry-run output names a different endpoint from the actual SDK request; treat it as a payload aid. See [execution](/cli/guides/execution.md) for that limitation. ## Interactive profile setup For a person using a terminal, discover accessible organizations and projects by name, then confirm saving and activating the profile. Cancellation or discovery failure leaves saved configuration unchanged. JSON, query and non-terminal setup are rejected before authentication; agents and scripts should use context discovery and configure --no-prompt instead. ### tp profile setup Set up a saved profile without looking up organization or project IDs first. ```bash tp profile setup ``` ```text tp profile setup [OPTIONS] ``` | Parameter | Type and values | Required | Default | Multiplicity | Description | | --- | --- | --- | --- | --- | --- | | `-h, --help` | boolean | no | not supplied | flag; no value | Show help for this command path and exit. | ## Local plugin commands Inspect bundled plugin and skill IDs before choosing an installation or export target. These commands operate on local bundled content. Installation and export write local files; install and install-skill support --dry-run. Export does not support --dry-run. ### tp plugins list List the bundled plugin and its available skill IDs. ```bash tp plugins list ``` ```text tp plugins list [OPTIONS] ``` | Parameter | Type and values | Required | Default | Multiplicity | Description | | --- | --- | --- | --- | --- | --- | | `-h, --help` | boolean | no | not supplied | flag; no value | Show help for this command path and exit. | ### tp plugins show Display a bundled plugin manifest or a selected bundled file. ```bash tp plugins show "$PLUGIN_ID" ``` ```text tp plugins show [OPTIONS] PLUGIN_ID ``` | Parameter | Type and values | Required | Default | Multiplicity | Description | | --- | --- | --- | --- | --- | --- | | `PLUGIN_ID` | string | yes | not supplied | single | Plugin identifier accepted by this command. | | `--file` | string | no | not supplied | single | Relative bundled plugin file to display; omit to display its manifest. | | `-h, --help` | boolean | no | not supplied | flag; no value | Show help for this command path and exit. | ### tp plugins recommend Match a task or command phrase against bundled guidance. ```bash tp plugins recommend datalake upload ``` ```text tp plugins recommend [OPTIONS] [QUERY]... ``` | Parameter | Type and values | Required | Default | Multiplicity | Description | | --- | --- | --- | --- | --- | --- | | `QUERY` | string | no | not supplied | variadic | Zero or more words describing a command or task to match against bundled guidance. | | `-h, --help` | boolean | no | not supplied | flag; no value | Show help for this command path and exit. | ### tp plugins doctor Inspect the local installation destinations for an agent target. ```bash tp plugins doctor --target dir --dest ./agent-plugins ``` ```text tp plugins doctor [OPTIONS] ``` | Parameter | Type and values | Required | Default | Multiplicity | Description | | --- | --- | --- | --- | --- | --- | | `--target` | choice: `codex`, `claude`, `agents`, `dir` (case-insensitive) | no | `"codex"` | single | Local agent installation target. | | `--dest` | string | no | not supplied | single | Explicit local destination; doctor inspects it without installing. | | `-h, --help` | boolean | no | not supplied | flag; no value | Show help for this command path and exit. | ### tp plugins install Install a bundled plugin into a selected local agent destination. ```bash tp plugins install "$PLUGIN_ID" --target dir --dest ./agent-plugins --dry-run ``` ```text tp plugins install [OPTIONS] PLUGIN_ID ``` | Parameter | Type and values | Required | Default | Multiplicity | Description | | --- | --- | --- | --- | --- | --- | | `PLUGIN_ID` | string | yes | not supplied | single | Plugin identifier accepted by this command. | | `--target` | choice: `codex`, `claude`, `agents`, `dir` (case-insensitive) | no | `"codex"` | single | Local agent installation target. | | `--dest` | string | no | not supplied | single | Explicit local destination parent or exact item directory. | | `--dry-run` | boolean | no | not supplied | flag; no value | Preview the planned operation without performing its writes. | | `--force` | boolean | no | not supplied | flag; no value | Replace an existing installation after creating a backup. | | `-h, --help` | boolean | no | not supplied | flag; no value | Show help for this command path and exit. | ### tp plugins install-skill Install one bundled skill into a local skill destination. ```bash tp plugins install-skill "$SKILL_ID" --target dir --dest ./agent-skills --dry-run ``` ```text tp plugins install-skill [OPTIONS] SKILL_ID ``` | Parameter | Type and values | Required | Default | Multiplicity | Description | | --- | --- | --- | --- | --- | --- | | `SKILL_ID` | string | yes | not supplied | single | Skill identifier accepted by this command. | | `--target` | choice: `codex`, `claude`, `agents`, `dir` (case-insensitive) | no | `"codex"` | single | Local agent installation target. | | `--dest` | string | no | not supplied | single | Explicit local destination parent or exact item directory. | | `--dry-run` | boolean | no | not supplied | flag; no value | Preview the planned operation without performing its writes. | | `--force` | boolean | no | not supplied | flag; no value | Replace an existing installation after creating a backup. | | `-h, --help` | boolean | no | not supplied | flag; no value | Show help for this command path and exit. | ### tp plugins export Export a bundled plugin or skill as a directory or archive. ```bash tp plugins export "$PLUGIN_ID" --format zip --output ./plugin-export ``` ```text tp plugins export [OPTIONS] ITEM_ID ``` | Parameter | Type and values | Required | Default | Multiplicity | Description | | --- | --- | --- | --- | --- | --- | | `ITEM_ID` | string | yes | not supplied | single | Item identifier accepted by this command. | | `--format` | choice: `codex-plugin`, `skill-folder`, `zip` (case-insensitive) | no | `"codex-plugin"` | single | Export a plugin, a skill folder, or a ZIP archive. | | `--output` | string | yes | not supplied | single | Local destination directory; an archive or item folder is created inside it. | | `--force` | boolean | no | not supplied | flag; no value | Replace an existing export destination. | | `-h, --help` | boolean | no | not supplied | flag; no value | Show help for this command path and exit. | ## Data Lake file commands Use the organization and project saved in your active profile. List and tree accept an empty read root; project-relative paths resolve in the active project for the read, upload and signed-URL helpers. Upload helpers reject another project namespace, parent traversal and writes to legacy/. Upload previews inspect local files, so their source paths must exist. The raw move and delete commands pass supplied paths to the API; use paths returned by a listing. ### tp datalake tree List child directories under a remote path. ```text tp datalake tree [OPTIONS] ``` | Parameter | Type and values | Required | Default | Multiplicity | Description | | --- | --- | --- | --- | --- | --- | | `--path` | string | no | `""` | single | Remote directory to list; empty string selects the read root. | | `--fields` | string | no | not supplied | single | Comma-separated output field names. | | `--limit` | integer (0 to unbounded) | no | not supplied | single | Maximum entries to emit; this alone does not fetch all backend pages. | | `--offset` | integer (0 to unbounded) | no | `0` | single | Number of entries to skip; pagination behavior depends on the command. | | `--path-contains` | string | no | not supplied | single | Case-insensitive path substring filter. | | `-h, --help` | boolean | no | not supplied | flag; no value | Show help for this command path and exit. | ### tp datalake list List remote files and directories with continuation support. ```bash tp datalake list ``` ```text tp datalake list [OPTIONS] ``` | Parameter | Type and values | Required | Default | Multiplicity | Description | | --- | --- | --- | --- | --- | --- | | `--path` | string | no | `""` | single | Remote directory to list; empty string selects the read root. | | `--continuation-token` | string | no | not supplied | single | Continuation token from a previous list response. | | `--fields` | string | no | not supplied | single | Comma-separated output field names. | | `--limit` | integer (0 to unbounded) | no | not supplied | single | Maximum entries to emit; this alone does not fetch all backend pages. | | `--offset` | integer (0 to unbounded) | no | `0` | single | Number of entries to skip; pagination behavior depends on the command. | | `--path-contains` | string | no | not supplied | single | Case-insensitive path substring filter. | | `--all` | boolean | no | not supplied | flag; no value | Fetch successive continuation pages before shaping output. | | `--format` | choice: `json`, `jsonl` (case-insensitive) | no | `"json"` | single | Emit the list as JSON or one record per line as JSONL. | | `-h, --help` | boolean | no | not supplied | flag; no value | Show help for this command path and exit. | ### tp datalake preview Preview remote file content or save the response locally. ```bash tp datalake preview --path project/datasets/dataset.csv --output ./preview.csv ``` ```text tp datalake preview [OPTIONS] ``` | Parameter | Type and values | Required | Default | Multiplicity | Description | | --- | --- | --- | --- | --- | --- | | `--path` | string | yes | not supplied | single | Remote file or directory path accepted by this operation. | | `--output` | string | no | not supplied | single | Local file destination for the preview response. | | `-h, --help` | boolean | no | not supplied | flag; no value | Show help for this command path and exit. | ### tp datalake resolve-uri Resolve a remote path to its storage URI. ```text tp datalake resolve-uri [OPTIONS] ``` | Parameter | Type and values | Required | Default | Multiplicity | Description | | --- | --- | --- | --- | --- | --- | | `--path` | string | yes | not supplied | single | Remote file or directory path accepted by this operation. | | `-h, --help` | boolean | no | not supplied | flag; no value | Show help for this command path and exit. | ### tp datalake upload-file Plan or upload one local file. ```bash tp datalake upload-file --local-path ./dataset.csv --remote-path project/datasets/dataset.csv --dry-run ``` ```text tp datalake upload-file [OPTIONS] ``` | Parameter | Type and values | Required | Default | Multiplicity | Description | | --- | --- | --- | --- | --- | --- | | `--local-path` | string | yes | not supplied | single | Local source file path. | | `--remote-path` | string | yes | not supplied | single | Destination path for one uploaded file. | | `--expires-in-minutes` | integer | no | `180` | single | Requested signed URL lifetime in minutes. | | `--upload-mode` | choice: `auto`, `sas`, `azcopy` (case-insensitive) | no | `"auto"` | single | Upload transport to use. | | `--upload-concurrency` | integer (1 to unbounded) | no | `4` | single | Maximum concurrent file-level AzCopy uploads. | | `--dry-run` | boolean | no | not supplied | flag; no value | Preview the planned operation without performing its writes. | | `-h, --help` | boolean | no | not supplied | flag; no value | Show help for this command path and exit. | ### tp datalake upload-dir Plan or upload the files in a local directory. ```bash tp datalake upload-dir --local-dir ./dataset --remote-prefix project/datasets/example --dry-run ``` ```text tp datalake upload-dir [OPTIONS] ``` | Parameter | Type and values | Required | Default | Multiplicity | Description | | --- | --- | --- | --- | --- | --- | | `--local-dir` | string | yes | not supplied | single | Local source directory path. | | `--remote-prefix` | string | yes | not supplied | single | Destination prefix for files in an uploaded directory. | | `--expires-in-minutes` | integer | no | `180` | single | Requested signed URL lifetime in minutes. | | `--upload-mode` | choice: `auto`, `sas`, `azcopy` (case-insensitive) | no | `"auto"` | single | Upload transport to use. | | `--upload-concurrency` | integer (1 to unbounded) | no | `4` | single | Maximum concurrent file-level AzCopy uploads. | | `--dry-run` | boolean | no | not supplied | flag; no value | Preview the planned operation without performing its writes. | | `-h, --help` | boolean | no | not supplied | flag; no value | Show help for this command path and exit. | ### tp datalake move Preview or request a remote file or directory move. ```bash tp datalake move --source-path project/datasets/old.csv --destination-path project/datasets/new.csv --dry-run ``` ```text tp datalake move [OPTIONS] ``` | Parameter | Type and values | Required | Default | Multiplicity | Description | | --- | --- | --- | --- | --- | --- | | `--source-path` | string | yes | not supplied | single | Source path for the move operation. | | `--destination-path` | string | yes | not supplied | single | Destination path for the move operation. | | `--directory, --file` | boolean | no | `false` | flag; no value | Treat the target as a directory instead of a file. | | `--overwrite` | boolean | no | not supplied | flag; no value | Allow replacement at the destination. | | `--dry-run` | boolean | no | not supplied | flag; no value | Preview the planned operation without performing its writes. | | `-h, --help` | boolean | no | not supplied | flag; no value | Show help for this command path and exit. | ### tp datalake delete Preview or request deletion of a remote file or directory. ```bash tp datalake delete --path project/datasets/old.csv --file --dry-run ``` ```text tp datalake delete [OPTIONS] ``` | Parameter | Type and values | Required | Default | Multiplicity | Description | | --- | --- | --- | --- | --- | --- | | `--path` | string | yes | not supplied | single | Remote file or directory path accepted by this operation. | | `--directory, --file` | boolean | no | `false` | flag; no value | Treat the target as a directory instead of a file. | | `--dry-run` | boolean | no | not supplied | flag; no value | Preview the planned operation without performing its writes. | | `-h, --help` | boolean | no | not supplied | flag; no value | Show help for this command path and exit. | ### tp datalake sas Request signed download or upload URLs for one or more remote paths. ```bash tp datalake sas --path project/datasets/a.csv --path project/datasets/b.csv --operation download --expires-in-minutes 30 ``` ```text tp datalake sas [OPTIONS] ``` | Parameter | Type and values | Required | Default | Multiplicity | Description | | --- | --- | --- | --- | --- | --- | | `--path` | string | yes | not supplied | repeatable | Remote path to sign; repeat --path once per file. | | `--operation` | choice: `download`, `upload` (case-insensitive) | no | `"download"` | single | Select signed download or upload access. | | `--expires-in-minutes` | integer | no | `180` | single | Requested signed URL lifetime in minutes. | | `-h, --help` | boolean | no | not supplied | flag; no value | Show help for this command path and exit. | ### tp datalake sas-folder Request a signed URL for reading and listing a folder prefix. ```text tp datalake sas-folder [OPTIONS] ``` | Parameter | Type and values | Required | Default | Multiplicity | Description | | --- | --- | --- | --- | --- | --- | | `--folder-path` | string | yes | not supplied | single | Remote folder prefix for read and list access. | | `--expires-in-minutes` | integer | no | `60` | single | Requested signed URL lifetime in minutes. | | `-h, --help` | boolean | no | not supplied | flag; no value | Show help for this command path and exit. | ### tp datalake sas-upload Request a signed URL for uploading under a folder prefix. ```text tp datalake sas-upload [OPTIONS] ``` | Parameter | Type and values | Required | Default | Multiplicity | Description | | --- | --- | --- | --- | --- | --- | | `--folder-path` | string | yes | not supplied | single | Remote folder prefix for upload access. | | `--expires-in-minutes` | integer | no | `120` | single | Requested signed URL lifetime in minutes. | | `-h, --help` | boolean | no | not supplied | flag; no value | Show help for this command path and exit. | ## Flow execution and job monitoring Flow run starts work; jobs commands inspect existing jobs. Job wait and watch poll until a recognized terminal state or a supplied timeout. Both return exit status 1 for an unsuccessful terminal state or timeout. Log streaming can continue until the backend closes the stream and has no CLI timeout option. Log content uses a command-specific output path rather than the shared JSON result renderer. ### tp flows save Save the definition of an existing Flow and refresh its schemas. ```text tp flows save [OPTIONS] FLOW_ID ``` | Parameter | Type and values | Required | Default | Multiplicity | Description | | --- | --- | --- | --- | --- | --- | | `FLOW_ID` | string | yes | not supplied | single | Flow identifier accepted by this command. | | `--data` | string | yes | not supplied | single | Flow definition JSON object, inline or loaded from @path.json. | | `--dry-run` | boolean | no | not supplied | flag; no value | Preview the planned operation without performing its writes. | | `-h, --help` | boolean | no | not supplied | flag; no value | Show help for this command path and exit. | `flow_data`: JSON object, inline or `@file`. Flow-specific definition; no universal server schema is asserted here. ### tp flows run Start an existing Flow with runtime inputs; the current dry-run preview has the limitation described below. ```bash tp flows run "$FLOW_ID" --input @flow-inputs.json --dry-run ``` ```text tp flows run [OPTIONS] FLOW_ID ``` | Parameter | Type and values | Required | Default | Multiplicity | Description | | --- | --- | --- | --- | --- | --- | | `FLOW_ID` | string | yes | not supplied | single | Flow identifier accepted by this command. | | `--input` | string | no | `"{}"` | single | Runtime input JSON object, inline or loaded from @path.json. | | `--device` | string | no | not supplied | single | Optional device ID override for a device-backed Flow. | | `--dry-run` | boolean | no | not supplied | flag; no value | Preview the planned operation without performing its writes. | | `-h, --help` | boolean | no | not supplied | flag; no value | Show help for this command path and exit. | `inputs`: JSON object, inline or `@file`. Defined by the selected Flow; inspect that Flow before supplying inputs. In the current release the dry-run preview names a different endpoint from the actual SDK request; it is not an authoritative wire preview. See the execution guide. ### tp mlops jobs list Discover jobs in the selected context. ```bash tp mlops jobs list ``` ```text tp mlops jobs list [OPTIONS] ``` | Parameter | Type and values | Required | Default | Multiplicity | Description | | --- | --- | --- | --- | --- | --- | | `--fields` | string | no | not supplied | single | Comma-separated output field names. | | `--limit` | integer (0 to unbounded) | no | not supplied | single | Maximum entries to emit; this alone does not fetch all backend pages. | | `--offset` | integer (0 to unbounded) | no | `0` | single | Number of entries to skip; pagination behavior depends on the command. | | `--name` | string | no | not supplied | single | Case-insensitive job name substring filter. | | `--status` | string | no | not supplied | single | Case-insensitive job status substring filter. | | `-h, --help` | boolean | no | not supplied | flag; no value | Show help for this command path and exit. | ### tp mlops jobs get Read details for an existing job. ```bash tp mlops jobs get "$JOB_ID" ``` ```text tp mlops jobs get [OPTIONS] JOB_ID ``` | Parameter | Type and values | Required | Default | Multiplicity | Description | | --- | --- | --- | --- | --- | --- | | `JOB_ID` | string | yes | not supplied | single | Job identifier accepted by this command. | | `-h, --help` | boolean | no | not supplied | flag; no value | Show help for this command path and exit. | ### tp mlops jobs logs Fetch logs with optional text filtering and a local output file. ```bash tp mlops jobs logs "$JOB_ID" --tail 100 --output ./job.log ``` ```text tp mlops jobs logs [OPTIONS] JOB_ID ``` | Parameter | Type and values | Required | Default | Multiplicity | Description | | --- | --- | --- | --- | --- | --- | | `JOB_ID` | string | yes | not supplied | single | Job identifier accepted by this command. | | `--tail` | integer (0 to unbounded) | no | not supplied | single | Emit only the final N log lines. | | `--contains` | string | no | not supplied | single | Emit only log lines containing this text. | | `--output` | string | no | not supplied | single | Local destination file for log content. | | `-h, --help` | boolean | no | not supplied | flag; no value | Show help for this command path and exit. | ### tp mlops jobs stream-logs Stream logs until the backend completes the stream. ```text tp mlops jobs stream-logs [OPTIONS] JOB_ID ``` | Parameter | Type and values | Required | Default | Multiplicity | Description | | --- | --- | --- | --- | --- | --- | | `JOB_ID` | string | yes | not supplied | single | Job identifier accepted by this command. | | `--output` | string | no | not supplied | single | Local destination file for log content. | | `-h, --help` | boolean | no | not supplied | flag; no value | Show help for this command path and exit. | ### tp mlops jobs metrics Fetch metrics for an existing job. ```text tp mlops jobs metrics [OPTIONS] JOB_ID ``` | Parameter | Type and values | Required | Default | Multiplicity | Description | | --- | --- | --- | --- | --- | --- | | `JOB_ID` | string | yes | not supplied | single | Job identifier accepted by this command. | | `-h, --help` | boolean | no | not supplied | flag; no value | Show help for this command path and exit. | ### tp mlops jobs wait Poll an existing job until terminal status or timeout. ```bash tp mlops jobs wait "$JOB_ID" --interval-seconds 10 --timeout-seconds 600 ``` ```text tp mlops jobs wait [OPTIONS] JOB_ID ``` | Parameter | Type and values | Required | Default | Multiplicity | Description | | --- | --- | --- | --- | --- | --- | | `JOB_ID` | string | yes | not supplied | single | Job identifier accepted by this command. | | `--interval-seconds` | number | no | `10.0` | single | Seconds between status polls. | | `--timeout-seconds` | number | no | not supplied | single | Stop polling unsuccessfully after this many seconds; omitted means no time limit. | | `-h, --help` | boolean | no | not supplied | flag; no value | Show help for this command path and exit. | ### tp mlops jobs watch Poll an existing job and display progress in human output mode. ```bash tp mlops jobs watch "$JOB_ID" --interval-seconds 10 --timeout-seconds 600 ``` ```text tp mlops jobs watch [OPTIONS] JOB_ID ``` | Parameter | Type and values | Required | Default | Multiplicity | Description | | --- | --- | --- | --- | --- | --- | | `JOB_ID` | string | yes | not supplied | single | Job identifier accepted by this command. | | `--interval-seconds` | number | no | `10.0` | single | Seconds between status polls. | | `--timeout-seconds` | number | no | not supplied | single | Stop polling unsuccessfully after this many seconds; omitted means no time limit. | | `-h, --help` | boolean | no | not supplied | flag; no value | Show help for this command path and exit. | ## Complete command catalog The catalog below lists command syntax, including aliases. Expand a family to find its precise positional syntax, then inspect the detailed workflow reference above, the downloadable metadata, or that path with `--help` for required options and accepted values. `[OPTIONS]` does not mean every option is optional: options marked `[required]` in help must be supplied. [Download command and option metadata](/assets/cli-commands.json) ### tp agents ```text tp agents [OPTIONS] COMMAND [ARGS]... tp agents create [OPTIONS] tp agents delete [OPTIONS] AGENT_ID tp agents issue-workspace-upload [OPTIONS] AGENT_ID tp agents list [OPTIONS] tp agents memories [OPTIONS] COMMAND [ARGS]... tp agents memories create [OPTIONS] AGENT_ID tp agents memories delete [OPTIONS] AGENT_ID MEMORY_ID tp agents memories export [OPTIONS] AGENT_ID tp agents memories import [OPTIONS] AGENT_ID tp agents memories search [OPTIONS] AGENT_ID tp agents memories update [OPTIONS] AGENT_ID MEMORY_ID tp agents models [OPTIONS] tp agents system-tools [OPTIONS] tp agents tasks [OPTIONS] COMMAND [ARGS]... tp agents tasks checkpoints [OPTIONS] THREAD_ID tp agents tasks create [OPTIONS] tp agents tasks list [OPTIONS] tp agents teams [OPTIONS] COMMAND [ARGS]... tp agents teams create [OPTIONS] tp agents teams delete [OPTIONS] TEAM_ID tp agents teams list [OPTIONS] tp agents teams update [OPTIONS] TEAM_ID tp agents update [OPTIONS] AGENT_ID tp agents workspaces [OPTIONS] COMMAND [ARGS]... tp agents workspaces create [OPTIONS] tp agents workspaces delete [OPTIONS] WORKSPACE_ID tp agents workspaces get [OPTIONS] WORKSPACE_ID tp agents workspaces list [OPTIONS] tp agents workspaces rollout-image [OPTIONS] WORKSPACE_ID tp agents workspaces update [OPTIONS] WORKSPACE_ID ``` ### tp api ```text tp api [OPTIONS] COMMAND [ARGS]... tp api call [OPTIONS] OPERATION_ID tp api operations [OPTIONS] tp api show [OPTIONS] OPERATION_ID ``` ### tp apps ```text tp apps [OPTIONS] COMMAND [ARGS]... tp apps list [OPTIONS] tp apps publish [OPTIONS] APP_ID tp apps show [OPTIONS] APP_ID tp apps stop [OPTIONS] APP_ID ``` ### tp auth ```text tp auth [OPTIONS] COMMAND [ARGS]... tp auth login [OPTIONS] tp auth whoami [OPTIONS] ``` ### tp automation ```text tp automation [OPTIONS] COMMAND [ARGS]... tp automation hooks [OPTIONS] COMMAND [ARGS]... tp automation hooks create [OPTIONS] tp automation hooks delete [OPTIONS] HOOK_ID tp automation hooks deliveries [OPTIONS] HOOK_ID tp automation hooks invoke [OPTIONS] ENDPOINT_KEY tp automation hooks list [OPTIONS] tp automation hooks rotate-secret [OPTIONS] HOOK_ID tp automation hooks update [OPTIONS] HOOK_ID tp automation schedules [OPTIONS] COMMAND [ARGS]... tp automation schedules agent-log [OPTIONS] APP_ID tp automation schedules create [OPTIONS] tp automation schedules delete [OPTIONS] APP_ID tp automation schedules list [OPTIONS] tp automation schedules log [OPTIONS] APP_ID tp automation schedules status [OPTIONS] APP_ID {running|stop|error} tp automation schedules update [OPTIONS] APP_ID tp automation webhooks [OPTIONS] COMMAND [ARGS]... tp automation webhooks create [OPTIONS] tp automation webhooks delete [OPTIONS] SUBSCRIPTION_ID tp automation webhooks deliveries [OPTIONS] SUBSCRIPTION_ID tp automation webhooks event-types [OPTIONS] tp automation webhooks list [OPTIONS] tp automation webhooks retry-delivery [OPTIONS] DELIVERY_ID tp automation webhooks test [OPTIONS] SUBSCRIPTION_ID tp automation webhooks update [OPTIONS] SUBSCRIPTION_ID ``` ### tp canvas ```text tp canvas [OPTIONS] COMMAND [ARGS]... tp canvas dashboard [OPTIONS] COMMAND [ARGS]... tp canvas dashboard extract [OPTIONS] PAGE_ID tp canvas dashboard lint [OPTIONS] tp canvas dashboard query [OPTIONS] DATASET_ID tp canvas dashboard scaffold [OPTIONS] tp canvas dashboard schema [OPTIONS] DATASET_ID tp canvas dashboard validate-page [OPTIONS] PAGE_ID tp canvas pages [OPTIONS] COMMAND [ARGS]... tp canvas pages create [OPTIONS] tp canvas pages export [OPTIONS] tp canvas pages get [OPTIONS] PAGE_ID tp canvas pages list [OPTIONS] tp canvas pages reorder [OPTIONS] tp canvas pages search [OPTIONS] QUERY tp canvas pages tree [OPTIONS] tp canvas pages update [OPTIONS] PAGE_ID tp canvas visualizations [OPTIONS] COMMAND [ARGS]... tp canvas visualizations describe [OPTIONS] VISUALIZATION_ID tp canvas visualizations list [OPTIONS] ``` ### tp commands ```text tp commands [OPTIONS] [COMMAND_PATH]... ``` ### tp completion ```text tp completion [OPTIONS] {bash|zsh|fish} ``` ### tp configure ```text tp configure [OPTIONS] ``` ### tp context ```text tp context [OPTIONS] COMMAND [ARGS]... tp context orgs [OPTIONS] tp context projects [OPTIONS] tp context show [OPTIONS] tp context use [OPTIONS] ``` ### tp costs ```text tp costs [OPTIONS] COMMAND [ARGS]... tp costs allocation [OPTIONS] tp costs budgets [OPTIONS] tp costs overview [OPTIONS] ``` ### tp dash ```text tp dash [OPTIONS] ``` ### tp dashboard ```text tp dashboard [OPTIONS] COMMAND [ARGS]... tp dashboard data [OPTIONS] ``` ### tp datalake ```text tp datalake [OPTIONS] COMMAND [ARGS]... tp datalake delete [OPTIONS] tp datalake list [OPTIONS] tp datalake move [OPTIONS] tp datalake preview [OPTIONS] tp datalake resolve-uri [OPTIONS] tp datalake sas [OPTIONS] tp datalake sas-folder [OPTIONS] tp datalake sas-upload [OPTIONS] tp datalake tree [OPTIONS] tp datalake upload-dir [OPTIONS] tp datalake upload-file [OPTIONS] ``` ### tp db ```text tp db [OPTIONS] COMMAND [ARGS]... tp db import [OPTIONS] COMMAND [ARGS]... tp db import apply [OPTIONS] tp db rows [OPTIONS] COMMAND [ARGS]... tp db rows create [OPTIONS] tp db rows create-many [OPTIONS] tp db rows delete [OPTIONS] tp db rows delete-many [OPTIONS] tp db rows get [OPTIONS] tp db rows query [OPTIONS] tp db rows update [OPTIONS] tp db rows update-many [OPTIONS] tp db tables [OPTIONS] COMMAND [ARGS]... tp db tables create [OPTIONS] tp db tables get [OPTIONS] tp db tables list [OPTIONS] tp db tables update [OPTIONS] ``` ### tp device ```text tp device [OPTIONS] COMMAND [ARGS]... tp device acr [OPTIONS] COMMAND [ARGS]... tp device acr repositories [OPTIONS] tp device acr tags [OPTIONS] tp device create [OPTIONS] tp device delete [OPTIONS] tp device deployments [OPTIONS] COMMAND [ARGS]... tp device deployments create [OPTIONS] tp device deployments default-config [OPTIONS] tp device deployments delete [OPTIONS] tp device deployments get [OPTIONS] tp device deployments list-device [OPTIONS] tp device list [OPTIONS] tp device module [OPTIONS] COMMAND [ARGS]... tp device module call [OPTIONS] tp device module restart [OPTIONS] tp device modules [OPTIONS] tp device modules-status [OPTIONS] tp device setup [OPTIONS] COMMAND [ARGS]... tp device setup download [OPTIONS] tp device tags [OPTIONS] COMMAND [ARGS]... tp device tags get [OPTIONS] tp device tags update [OPTIONS] tp device twin [OPTIONS] COMMAND [ARGS]... tp device twin get [OPTIONS] tp device twin update [OPTIONS] ``` ### tp dynamic-ui ```text tp dynamic-ui [OPTIONS] COMMAND [ARGS]... tp dynamic-ui create [OPTIONS] tp dynamic-ui create-html [OPTIONS] tp dynamic-ui delete [OPTIONS] UI_ID tp dynamic-ui get [OPTIONS] UI_ID tp dynamic-ui list [OPTIONS] tp dynamic-ui update [OPTIONS] UI_ID ``` ### tp flows ```text tp flows [OPTIONS] COMMAND [ARGS]... tp flows create [OPTIONS] tp flows list [OPTIONS] tp flows run [OPTIONS] FLOW_ID tp flows save [OPTIONS] FLOW_ID ``` ### tp help ```text tp help [OPTIONS] [COMMAND_PATH]... ``` ### tp home ```text tp home [OPTIONS] COMMAND [ARGS]... tp home data [OPTIONS] tp home pages [OPTIONS] COMMAND [ARGS]... tp home pages apply [OPTIONS] tp home pages create [OPTIONS] tp home pages delete [OPTIONS] PAGE_ID tp home pages get [OPTIONS] PAGE_ID tp home pages list [OPTIONS] tp home pages update [OPTIONS] PAGE_ID ``` ### tp hooks ```text tp hooks [OPTIONS] COMMAND [ARGS]... tp hooks create [OPTIONS] tp hooks delete [OPTIONS] HOOK_ID tp hooks deliveries [OPTIONS] HOOK_ID tp hooks invoke [OPTIONS] ENDPOINT_KEY tp hooks list [OPTIONS] tp hooks rotate-secret [OPTIONS] HOOK_ID tp hooks update [OPTIONS] HOOK_ID ``` ### tp jobs ```text tp jobs [OPTIONS] COMMAND [ARGS]... tp jobs get [OPTIONS] JOB_ID tp jobs list [OPTIONS] tp jobs logs [OPTIONS] JOB_ID tp jobs metrics [OPTIONS] JOB_ID tp jobs stream-logs [OPTIONS] JOB_ID tp jobs wait [OPTIONS] JOB_ID tp jobs watch [OPTIONS] JOB_ID ``` ### tp lakehouse ```text tp lakehouse [OPTIONS] COMMAND [ARGS]... tp lakehouse ai-functions [OPTIONS] COMMAND [ARGS]... tp lakehouse ai-functions describe [OPTIONS] NAME tp lakehouse ai-functions list [OPTIONS] tp lakehouse catalog [OPTIONS] COMMAND [ARGS]... tp lakehouse catalog bootstrap [OPTIONS] tp lakehouse catalog show [OPTIONS] tp lakehouse compute [OPTIONS] COMMAND [ARGS]... tp lakehouse compute list [OPTIONS] tp lakehouse costs [OPTIONS] COMMAND [ARGS]... tp lakehouse costs overview [OPTIONS] tp lakehouse jobs [OPTIONS] COMMAND [ARGS]... tp lakehouse jobs get [OPTIONS] JOB_ID tp lakehouse jobs list [OPTIONS] tp lakehouse jobs run [OPTIONS] JOB_ID tp lakehouse jobs schedule [OPTIONS] JOB_ID tp lakehouse jobs upsert-multitask [OPTIONS] tp lakehouse jobs upsert-notebook [OPTIONS] tp lakehouse notebooks [OPTIONS] COMMAND [ARGS]... tp lakehouse notebooks get [OPTIONS] PATH tp lakehouse notebooks run [OPTIONS] PATH tp lakehouse notebooks upsert [OPTIONS] PATH tp lakehouse pipelines [OPTIONS] COMMAND [ARGS]... tp lakehouse pipelines list [OPTIONS] tp lakehouse query-history [OPTIONS] COMMAND [ARGS]... tp lakehouse query-history list [OPTIONS] tp lakehouse runs [OPTIONS] COMMAND [ARGS]... tp lakehouse runs get [OPTIONS] RUN_ID tp lakehouse runs list [OPTIONS] tp lakehouse runs output [OPTIONS] RUN_ID tp lakehouse runs wait [OPTIONS] RUN_ID tp lakehouse schemas [OPTIONS] COMMAND [ARGS]... tp lakehouse schemas create [OPTIONS] SCHEMA_NAME tp lakehouse schemas list [OPTIONS] tp lakehouse sql [OPTIONS] COMMAND [ARGS]... tp lakehouse sql execute [OPTIONS] tp lakehouse sql preview [OPTIONS] tp lakehouse statements [OPTIONS] COMMAND [ARGS]... tp lakehouse statements cancel [OPTIONS] STATEMENT_ID tp lakehouse statements execute [OPTIONS] tp lakehouse statements get [OPTIONS] STATEMENT_ID tp lakehouse statements result-chunk [OPTIONS] STATEMENT_ID CHUNK_INDEX tp lakehouse status [OPTIONS] tp lakehouse tables [OPTIONS] COMMAND [ARGS]... tp lakehouse tables get [OPTIONS] TABLE_NAME tp lakehouse tables list [OPTIONS] tp lakehouse tables preview [OPTIONS] TABLE_NAME tp lakehouse warehouses [OPTIONS] COMMAND [ARGS]... tp lakehouse warehouses list [OPTIONS] tp lakehouse workspace [OPTIONS] COMMAND [ARGS]... tp lakehouse workspace ls [OPTIONS] [PATH] ``` ### tp mlops ```text tp mlops [OPTIONS] COMMAND [ARGS]... tp mlops bundles [OPTIONS] COMMAND [ARGS]... tp mlops bundles submit [OPTIONS] tp mlops bundles upload [OPTIONS] tp mlops bundles validate [OPTIONS] tp mlops cloud [OPTIONS] COMMAND [ARGS]... tp mlops cloud create-online [OPTIONS] tp mlops cloud delete [OPTIONS] tp mlops cloud get [OPTIONS] tp mlops cloud invoke-online [OPTIONS] tp mlops cloud list [OPTIONS] tp mlops cloud set-online-traffic [OPTIONS] tp mlops cloud update-online [OPTIONS] tp mlops cloud wait [OPTIONS] tp mlops computes [OPTIONS] COMMAND [ARGS]... tp mlops computes list [OPTIONS] tp mlops data [OPTIONS] COMMAND [ARGS]... tp mlops data datastores [OPTIONS] tp mlops data delete [OPTIONS] DATA_ASSET_NAME tp mlops data files [OPTIONS] DATA_ASSET_NAME VERSION tp mlops data list [OPTIONS] tp mlops data next-version [OPTIONS] NAME tp mlops data register [OPTIONS] tp mlops data sas [OPTIONS] tp mlops data sas-folder [OPTIONS] tp mlops data upload-dir [OPTIONS] tp mlops data upload-file [OPTIONS] tp mlops data versions [OPTIONS] DATA_ASSET_NAME tp mlops deploy [OPTIONS] COMMAND [ARGS]... tp mlops deploy delete [OPTIONS] tp mlops deploy get [OPTIONS] tp mlops deploy set [OPTIONS] tp mlops environments [OPTIONS] COMMAND [ARGS]... tp mlops environments list [OPTIONS] tp mlops hyperparameters [OPTIONS] COMMAND [ARGS]... tp mlops hyperparameters architectures [OPTIONS] tp mlops hyperparameters get [OPTIONS] ARCHITECTURE tp mlops jobs [OPTIONS] COMMAND [ARGS]... tp mlops jobs get [OPTIONS] JOB_ID tp mlops jobs list [OPTIONS] tp mlops jobs logs [OPTIONS] JOB_ID tp mlops jobs metrics [OPTIONS] JOB_ID tp mlops jobs stream-logs [OPTIONS] JOB_ID tp mlops jobs wait [OPTIONS] JOB_ID tp mlops jobs watch [OPTIONS] JOB_ID tp mlops models [OPTIONS] COMMAND [ARGS]... tp mlops models artifacts [OPTIONS] MODEL_NAME MODEL_VERSION tp mlops models download [OPTIONS] MODEL_NAME MODEL_VERSION tp mlops models list [OPTIONS] tp mlops models register [OPTIONS] tp mlops models upload-dir [OPTIONS] tp mlops models upload-file [OPTIONS] tp mlops models validate-online [OPTIONS] tp mlops models versions [OPTIONS] MODEL_NAME tp mlops models versions-detail [OPTIONS] tp mlops train [OPTIONS] COMMAND [ARGS]... tp mlops train submit [OPTIONS] ``` ### tp modules ```text tp modules [OPTIONS] COMMAND [ARGS]... tp modules describe [OPTIONS] IDENTIFIER tp modules get [OPTIONS] MODULE_ID tp modules invoke [OPTIONS] MODULE_ID tp modules list [OPTIONS] tp modules search [OPTIONS] [QUERY] ``` ### tp orgs ```text tp orgs [OPTIONS] ``` ### tp plugins ```text tp plugins [OPTIONS] COMMAND [ARGS]... tp plugins doctor [OPTIONS] tp plugins export [OPTIONS] ITEM_ID tp plugins install [OPTIONS] PLUGIN_ID tp plugins install-skill [OPTIONS] SKILL_ID tp plugins list [OPTIONS] tp plugins recommend [OPTIONS] [QUERY]... tp plugins show [OPTIONS] PLUGIN_ID ``` ### tp profile ```text tp profile [OPTIONS] COMMAND [ARGS]... tp profile delete [OPTIONS] PROFILE_NAME tp profile list [OPTIONS] tp profile setup [OPTIONS] tp profile show [OPTIONS] [PROFILE_NAME] tp profile use [OPTIONS] PROFILE_NAME ``` ### tp projects ```text tp projects [OPTIONS] ``` ### tp raw ```text tp raw [OPTIONS] COMMAND [ARGS]... tp raw delete [OPTIONS] PATH tp raw get [OPTIONS] PATH tp raw post [OPTIONS] PATH tp raw put [OPTIONS] PATH ``` ### tp registry ```text tp registry [OPTIONS] COMMAND [ARGS]... tp registry pull [OPTIONS] IMAGE tp registry push [OPTIONS] LOCAL_IMAGE tp registry repositories [OPTIONS] tp registry tags [OPTIONS] REPOSITORY ``` ### tp rest ```text tp rest [OPTIONS] METHOD PATH ``` ### tp skills ```text tp skills [OPTIONS] COMMAND [ARGS]... tp skills delete [OPTIONS] SKILL_ID tp skills download [OPTIONS] SKILL_ID tp skills get [OPTIONS] SKILL_ID tp skills list [OPTIONS] tp skills upload [OPTIONS] ``` ### tp tasks ```text tp tasks [OPTIONS] COMMAND [ARGS]... tp tasks cancel-followup [OPTIONS] TASK_ID FOLLOWUP_ID tp tasks create [OPTIONS] tp tasks delete [OPTIONS] TASK_ID tp tasks followups [OPTIONS] TASK_ID tp tasks followups-bulk [OPTIONS] tp tasks get [OPTIONS] TASK_ID tp tasks goal [OPTIONS] COMMAND [ARGS]... tp tasks goal create [OPTIONS] TASK_ID tp tasks goal delete [OPTIONS] TASK_ID tp tasks goal get [OPTIONS] TASK_ID tp tasks goal pause [OPTIONS] TASK_ID tp tasks goal resume [OPTIONS] TASK_ID tp tasks list [OPTIONS] tp tasks messages [OPTIONS] TASK_ID tp tasks post-message [OPTIONS] TASK_ID tp tasks prepare-runtime [OPTIONS] tp tasks status [OPTIONS] TASK_ID tp tasks update [OPTIONS] TASK_ID ``` ### tp webhooks ```text tp webhooks [OPTIONS] COMMAND [ARGS]... tp webhooks create [OPTIONS] tp webhooks delete [OPTIONS] SUBSCRIPTION_ID tp webhooks deliveries [OPTIONS] SUBSCRIPTION_ID tp webhooks event-types [OPTIONS] tp webhooks list [OPTIONS] tp webhooks retry-delivery [OPTIONS] DELIVERY_ID tp webhooks test [OPTIONS] SUBSCRIPTION_ID tp webhooks update [OPTIONS] SUBSCRIPTION_ID ``` ### tp whoami ```text tp whoami [OPTIONS] ``` This catalog targets CLI **0.6.134**. The connected service determines which operations your account can perform. Use each command’s `--help` to inspect required inputs and output modes. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /python-sdk/overview.md # Python SDK Read and update ThinkPlatform resources from synchronous Python applications. Use the `thinkplatform.sdk` client to read and update project resources from Python. See [Installation](/cli/get-started/installation.md) to install the CLI and SDK. ## List your projects Sign in using a `work` profile as described in [CLI authentication](/cli/get-started/authentication.md), then load that profile in Python. The SDK acquires credentials through the configured provider. This example only reads resources. ```python from thinkplatform.sdk import client_from_profile with client_from_profile("work") as client: for organization in client.organizations.list(): if organization.id is not None: projects = client.projects.list(org_id=organization.id) print(organization.name, [(p.id, p.name) for p in projects]) ``` `client_from_profile()` explicitly reads local CLI configuration. `client_from_env()` and direct `ThinkPlatformClient(...)` construction do not load profiles automatically. See [SDK authentication](/python-sdk/authentication.md) for environment configuration and explicit bearer-token credentials. ## Context and lifecycle Set `org_id` and `project_id` when constructing the client, or pass them to resource methods that accept those keywords. Missing required context raises `MissingContextError` before a request. See [organization and project context](/cli/guides/context.md) for the corresponding CLI settings. `client.with_context(org_id=..., project_id=...)` returns another client sharing the credential and HTTP connection pool. It preserves an existing context value when the corresponding argument is `None`; it does not clear it. Keep the original client open while using derived clients. The SDK is synchronous: calls block and there is no public async client. Use `with ThinkPlatformClient(...)` or call `close()` to release its HTTP connections. The default request timeout is 30 seconds; set `timeout_seconds` at construction to change it. ## Choose a workflow Continue with [authentication](/python-sdk/authentication.md), [resource methods and examples](/python-sdk/resources.md), [database workflows](/python-sdk/database.md), and [error handling](/python-sdk/errors.md). Use the [API reference](/python-sdk/api-reference.md) to look up exact method signatures and the [models reference](/python-sdk/models.md) to interpret typed results. The SDK and CLI support different sets of operations; some CLI commands have no equivalent SDK method. In client 0.6.133 and later, use [Hosted Apps](/python-sdk/hosted-apps.md) for current-request data access and [Lakehouse statements](/python-sdk/lakehouse.md) for SQL submission, status and chunks. See [Upgrade and migration](/cli/guides/upgrading.md) for compatibility with earlier clients. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /python-sdk/authentication.md # SDK authentication Choose explicit credentials, environment settings, or a CLI profile. Import credentials and client factories from `thinkplatform.sdk`. The client normally acquires credentials when it makes a request, so authentication can fail even after client creation succeeds. ## Choose a credential | Credential | Use and requirements | | --- | --- | | `StaticTokenCredential(token)` | A bearer token obtained outside the SDK. It does not renew the supplied token. Optional `expires_on`, `source`, and `claims` metadata can be supplied. | | `AzureCliCredential()` | Uses Azure CLI authentication through Azure Identity. Requires an authenticated Azure CLI session and the API audience. | | `DeviceCodeCredential(client_id=..., tenant_id=...)` | Uses an Azure Identity device-code flow. Requires an application client ID and audience. | | `InteractiveBrowserCredential(client_id=..., tenant_id=...)` | Uses Azure Identity browser authentication. Requires an application client ID and audience. | | `WorkspaceDelegationCredential(...)` | For a provisioned managed workspace: the managed identity, workspace ID or name, and workspace assertion are used to obtain a delegated token. Use the settings supplied by your workspace operator. | Azure user credentials accept `env`, `tenant_id`, `client_id`, and `refresh_buffer_seconds`. Tenant and client IDs can also come from `THINKPLATFORM_AZURE_TENANT_ID` / `THINKPLATFORM_AZURE_CLIENT_ID`, falling back to their `AZURE_` equivalents. The audience is the API resource, not an arbitrary application ID; credentials append `/.default` when needed. These flows require Azure Identity dependencies and suitable tenant configuration. The deployment must allow the application identity used by the selected credential. `AzureCliCredential` uses Azure CLI's application identity rather than the shared ThinkPlatform CLI registration; the deployment must explicitly allow Azure CLI. Browser and device-code flows require an approved public-client registration, not a web-only registration. Administrator consent for one API audience does not grant access to a different API audience. A custom credential can implement the public `ThinkPlatformCredential` protocol: `get_token_info(*, base_url, audience, org_id=None, project_id=None, force_refresh=False)` returns `AccessTokenInfo`; `invalidate_cache()` clears its cached token. Keep token values out of logs. The bearer-token examples in [resource workflows](/python-sdk/resources.md) read `THINKPLATFORM_ACCESS_TOKEN` themselves and pass it to `StaticTokenCredential`. This variable is used by the examples; `client_from_env()` does not automatically consume it. ## Environment configuration ```python from thinkplatform.sdk import client_from_env with client_from_env() as client: print(client.base_url, client.org_id, client.project_id) ``` `client_from_env()` reads these settings; explicit factory arguments take precedence: | Setting | Behavior | | --- | --- | | `THINKPLATFORM_API_BASE_URL` | API endpoint; falls back to `THINKPLATFORM_BASE_URL`, then `http://127.0.0.1:8000` for ordinary user auth. Set it explicitly for your deployment. | | `THINKPLATFORM_API_AUDIENCE` | Falls back to `AZURE_API_AUDIENCE`; Azure credential scope resolution can also use `AZURE_CLIENT_ID`. | | `THINKPLATFORM_AUTH_MODE` | Defaults to `azure-cli`; also accepts `device-code`, `interactive-browser`, `workspace-delegation`, or `execution-delegation`. | | `THINKPLATFORM_ORG_ID`, `THINKPLATFORM_PROJECT_ID` | Integer context IDs. Values that cannot be parsed as integers leave the context unset. | Workspace delegation requires an explicit API endpoint, `THINKPLATFORM_WORKSPACE_ASSERTION`, and `THINKPLATFORM_WORKSPACE_ID` or `THINKPLATFORM_WORKSPACE_NAME`. Name-based lookup also requires organization and project context. Requested scopes can be supplied through `THINKPLATFORM_WORKSPACE_SCOPES` or `THINKPLATFORM_REQUESTED_SCOPES`. Execution delegation uses the `THINKPLATFORM_EXECUTION_TOKEN`, endpoint, and positive organization and project IDs injected by a trusted caller. It is bound to that context, requires relative request paths, and cannot renew an expired execution credential by falling back to a user login. Use the injected token; do not construct execution tokens yourself or embed them in source code. ## Reuse a CLI profile explicitly ```python from thinkplatform.sdk import client_from_profile with client_from_profile("work") as client: print(client.org_id, client.project_id) ``` `client_from_profile()` loads local CLI profile configuration and uses the CLI's connection defaults when the profile has no value for a setting. For the production URL and audience, browser and device-code credentials use the same encrypted OS token cache and non-secret account record as the CLI. The OS credential store must be available; the SDK does not fall back to plaintext token storage. It accepts `config_path`, `env`, and explicit `base_url`, `audience`, `auth_mode`, `org_id`, `project_id`, and `timeout_seconds` overrides. If you omit the profile name, it selects a profile using the CLI rules, including the profile selected through the environment or the active profile. It creates the credential configured in the profile rather than converting the profile to a static bearer token. `ThinkPlatformClient(...)` and `client_from_env()` do **not** automatically load CLI profiles or inherit the CLI's public-service defaults. The constructor uses values you pass directly; `client_from_env()` follows the SDK environment table above, including its `http://127.0.0.1:8000` base URL and `azure-cli` auth defaults. See [CLI authentication](/cli/get-started/authentication.md) and [context](/cli/guides/context.md). Exact constructor and factory signatures are in the [API reference](/python-sdk/api-reference.md). ## Hosted App requests Inside a configured Hosted App, use `client_from_hosted_request(request.headers)` for each authenticated request and close the client before the request ends. Do not inject a personal CLI token or reuse an invocation in background work. See [Hosted Apps](/python-sdk/hosted-apps.md) for grants and lifecycle requirements. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /python-sdk/resources.md # Resource workflows Read project resources, update a page title, and page through data lake files. For every resource method and default, see the [API reference](/python-sdk/api-reference.md). For returned fields and JSON aliases, see [models and results](/python-sdk/models.md). The [database workflow](/python-sdk/database.md) covers schema inspection, row queries, and verified writes. Start with a known organization and project. Resource calls enforce the permissions of your credential; setting context does not grant access. ## Essential methods Signatures below omit `self`. Unless noted, context-aware methods accept keyword-only `org_id=None, project_id=None`, falling back to the client context. | Method | Return and behavior | | --- | --- | | `auth.whoami()` | `AuthenticatedUser` with optional `id` and `username`. | | `organizations.list()` | `list[Organization]`; optional `id`, `name` fields. No pagination arguments. | | `projects.list(*, org_id=None)` | `list[Project]`; optional `id`, `name`, `organization_id`, `user_role`. Requires organization context; no pagination arguments. | | `home.data(*, org_id=None, project_id=None)` | Mapping containing dashboard data. | | `home.pages.list(...)` | `list[Mapping[str, Any]]`; no pagination arguments. | | `home.pages.get(page_id, ...)` | A page mapping. | | `home.pages.create(payload, ...)` | Created page mapping; writes data. | | `home.pages.update(page_id, payload, ...)` | Updated page mapping; writes data. | | `home.pages.delete(page_id, ...)` | `None`; deletes a page. | | `datalake.list(*, path="", continuation_token=None, org_id=None, project_id=None)` | `DatalakeListPage`; consume `items`, then pass `continuation_token` into another call. No automatic iteration. | | `datalake.preview_text(path, ...)` | `DatalakeTextPreview`. | `home`, `dashboard`, and `canvas` refer to the same resource namespace. For example, `client.canvas.pages.list()` and `client.home.pages.list()` use the same page API. See [Canvas pages](/cli/guides/canvas-pages.md) for the CLI workflow. For container-backed apps, use [`client.hosted_apps`](/python-sdk/hosted-apps.md) for publication management and a request-bound client for delegated data access inside an app. [`client.lakehouse.statements`](/python-sdk/lakehouse.md) submits SQL and retrieves status and result chunks. These namespaces require client 0.6.133 or later and the corresponding deployment services. ## Read, then conditionally update a page Set `THINKPLATFORM_ORG_ID`, `THINKPLATFORM_PROJECT_ID`, and `THINKPLATFORM_PAGE_ID` along with `THINKPLATFORM_API_BASE_URL` and a bearer token in `THINKPLATFORM_ACCESS_TOKEN` as described in [authentication](/python-sdk/authentication.md). The example reads the page first and changes its title only when `THINKPLATFORM_APPLY_UPDATE=yes`; leave that flag unset to inspect without writing. Confirm the page ID and intended title before enabling it. After the update, a separate GET checks the stored title. These requests are not an atomic compare-and-swap; another writer can change the page between them. ```python import os from thinkplatform.sdk import StaticTokenCredential, ThinkPlatformClient with ThinkPlatformClient( base_url=os.environ["THINKPLATFORM_API_BASE_URL"], credential=StaticTokenCredential(os.environ["THINKPLATFORM_ACCESS_TOKEN"]), org_id=int(os.environ["THINKPLATFORM_ORG_ID"]), project_id=int(os.environ["THINKPLATFORM_PROJECT_ID"]), ) as client: page_id = os.environ["THINKPLATFORM_PAGE_ID"] page = client.home.pages.get(page_id) desired_title = "Project status" print(page.get("title")) if os.environ.get("THINKPLATFORM_APPLY_UPDATE") == "yes": if page.get("title") != desired_title: client.home.pages.update(page_id, {"title": desired_title}) verified = client.home.pages.get(page_id) if verified.get("title") != desired_title: raise RuntimeError("The stored page title does not match the requested title.") print(verified.get("title")) ``` ## Follow a continuation token ```python import os from thinkplatform.sdk import StaticTokenCredential, ThinkPlatformClient with ThinkPlatformClient( base_url=os.environ["THINKPLATFORM_API_BASE_URL"], credential=StaticTokenCredential(os.environ["THINKPLATFORM_ACCESS_TOKEN"]), org_id=int(os.environ["THINKPLATFORM_ORG_ID"]), project_id=int(os.environ["THINKPLATFORM_PROJECT_ID"]), ) as client: token = None seen_tokens = set() for _ in range(20): page = client.datalake.list(path="", continuation_token=token) for item in page.items: print(item.path, item.is_directory, item.size) token = page.continuation_token if not token: break if token in seen_tokens: raise RuntimeError("The server repeated a continuation token.") seen_tokens.add(token) else: raise RuntimeError("Stopped at the 20-page budget; the inventory is incomplete.") ``` This example makes at most 20 page requests and rejects repeated continuation tokens. If more pages remain after the limit, it raises an error to indicate that the inventory is incomplete. Adjust the limit for your workload. Pagination is method-specific. A list return value is not a page object; do not assume `has_more`, `next_cursor`, or a common paginator exists. ## Other resource families The client also exposes `agents` (including tasks, teams, workspaces and memories), `tasks`, `flows`, `apps`, `hooks`, `webhooks`, `skills`, `modules`, `devices`, `db.tables`, `db.rows`, and `mlops`. See the [API reference](/python-sdk/api-reference.md) for their methods and return types. Some CLI operations have no equivalent SDK method. Many resource methods return Pydantic models with attribute access, optional fields, and support for additional server fields. Canvas pages and some other endpoints return mappings instead: use `page.get("title")`, not `page.title`. Raw download methods return `RawResponse` with `status_code`, `body` bytes, `headers`, and `content_type`. Low-level `request_json()`, `request_raw()`, and `request_multipart()` are available when you already know the API contract; they do not infer resource payload schemas. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /python-sdk/database.md # Database tables and rows Inspect shared database tables, query sample rows, and update a row. The SDK works with existing shared database tables through `client.db.tables` and `client.db.rows`. Table creation, schema changes, and row deletion are not exposed by these resource namespaces. For every method and its exact defaults, see the [API reference](/python-sdk/api-reference.md#database-tables); field types are in [models and results](/python-sdk/models.md#shareddbtable). Use an API credential with access to the selected organization, project, and table. Context selects the scope; it does not grant database permissions. ## Inspect schema and query a sample `db.tables.list()` returns `list[SharedDbTableSummary]` with no pagination arguments. `db.tables.get(table_id)` returns the full `SharedDbTable`, including `columns`, `schema_version`, and access metadata. Column definitions expose keys, types, required flags, options, and lifecycle metadata. Inspect them before choosing a column to read or write. `db.rows.query(table_id, query)` forwards a query mapping to the deployed endpoint. The example below requests up to five rows using empty `filters` and `sort` arrays with `page` and `page_size`. Before adding filters or sorting, check which operators and sort directions your deployed API supports. The result is `SharedDbRowQueryResult`: rows are in `items`, user column values are in each row's `data`, and optional page metadata is in `meta.page`, `meta.page_size`, and `meta.total`. These metadata fields can be absent; inspect them before traversing pages. Request each page explicitly; the SDK does not convert this query to offset or continuation-token pagination. ## Update a known row and read it back Set `THINKPLATFORM_API_BASE_URL`, `THINKPLATFORM_ACCESS_TOKEN`, `THINKPLATFORM_ORG_ID`, `THINKPLATFORM_PROJECT_ID`, and `THINKPLATFORM_DB_TABLE_ID`. The sample first prints the schema and up to five rows. To update a row, additionally set `THINKPLATFORM_DB_ROW_ID`, `THINKPLATFORM_DB_COLUMN_KEY`, and `THINKPLATFORM_DB_COLUMN_VALUE`. Choose an existing text column whose schema accepts the supplied string. Set `THINKPLATFORM_APPLY_UPDATE=yes` only after checking the table, row, key, and intended value. With that flag unset, the code only reads. ```python import os from thinkplatform.sdk import StaticTokenCredential, ThinkPlatformClient with ThinkPlatformClient( base_url=os.environ["THINKPLATFORM_API_BASE_URL"], credential=StaticTokenCredential(os.environ["THINKPLATFORM_ACCESS_TOKEN"]), org_id=int(os.environ["THINKPLATFORM_ORG_ID"]), project_id=int(os.environ["THINKPLATFORM_PROJECT_ID"]), ) as client: table_id = os.environ["THINKPLATFORM_DB_TABLE_ID"] table = client.db.tables.get(table_id) print(table.name, table.schema_version) for column in table.columns: print(column.key, column.type, column.required, column.status) sample = client.db.rows.query( table_id, {"filters": [], "sort": [], "page": 1, "page_size": 5}, ) for row in sample.items: print(row.id, row.data) print(sample.meta.page, sample.meta.page_size, sample.meta.total) if os.environ.get("THINKPLATFORM_APPLY_UPDATE") == "yes": row_id = os.environ["THINKPLATFORM_DB_ROW_ID"] column_key = os.environ["THINKPLATFORM_DB_COLUMN_KEY"] desired_value = os.environ["THINKPLATFORM_DB_COLUMN_VALUE"] if column_key not in {column.key for column in table.columns}: raise ValueError("The requested column key is absent from the table schema.") before = client.db.rows.get(table_id, row_id) desired_data = dict(before.data) desired_data[column_key] = desired_value client.db.rows.update(table_id, row_id, desired_data) verified = client.db.rows.get(table_id, row_id) if verified.data.get(column_key) != desired_value: raise RuntimeError("The stored value does not match the requested update.") print(verified.id, verified.data.get(column_key)) ``` The example copies the current row data before changing one key. The SDK sends `data` inside the endpoint's `{"data": ...}` envelope; pass column-value mappings directly rather than wrapping them again. `update()` has no `expected_schema_version`, row-version, or compare-and-swap parameter. A read followed by an update can race with another writer, including when resending copied data. The final GET verifies the observed stored value at that moment; it does not make the sequence atomic. When multiple clients write to the same rows, use the concurrency controls supported by your deployed service. ## Create one row or a batch `db.rows.create(table_id, data)` returns a `SharedDbRow`. Supply the complete column-value mapping required by your table, without a surrounding `data` key. The server validates the table schema and permissions. `db.rows.create_many(table_id, rows, *, expected_schema_version=None, org_id=None, project_id=None)` accepts an iterable of plain column-value mappings. The SDK wraps each mapping in a `data` envelope and sends the batch as `items`, together with `expected_schema_version`. Its result is a mapping, not `list[SharedDbRow]`; check your deployed batch endpoint documentation for the result keys and whether the batch is atomic. If your deployment uses the batch schema-version check, obtain the current version from `db.tables.get(table_id).schema_version` and pass it as `expected_schema_version` to `create_many()`. This argument is specific to batch creation; `create()` and `update()` do not accept it. A schema version describes table structure and is not a row-concurrency token. ## Handle failures See [SDK errors](/python-sdk/errors.md). Missing context raises `MissingContextError`; rejected HTTP requests raise `ThinkPlatformApiError` with a status and decoded error body. Do not assume every validation, access, or conflict failure has the same status across deployments. Re-read the table schema after a schema mismatch, and verify stored rows before retrying an uncertain write. A connection failure does not establish whether a write reached the service. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /python-sdk/errors.md # Errors and retries Handle missing context, credential failures, connection problems, and API errors. Import SDK exceptions from `thinkplatform.sdk`. If the CLI succeeds but Python or a managed workspace fails, use the shared [troubleshooting workflow](/cli/guides/troubleshooting.md). The [API reference](/python-sdk/api-reference.md) and [models reference](/python-sdk/models.md) document resource-specific inputs and results. | Exception | What it means | Next step | | --- | --- | --- | | `MissingContextError` | Required organization/project context is missing, or a request URL is invalid, ambiguous, or outside the configured API origin. Restricted execution requests also reject absolute paths. Subclasses `ValueError`. | Correct the context or URL before retrying. | | `TokenAcquisitionError` | Credential configuration, acquisition, exchange, expiry, or execution-context validation failed. Subclasses `RuntimeError`. | Correct the credential setup or obtain a new authorized credential. | | `ThinkPlatformApiError` | API returned HTTP 400 or higher, or the API transport raised an `httpx.HTTPError`. Subclasses `RuntimeError`. | Inspect `status_code`; it is `None` for wrapped transport failures. | | `ValueError` / Pydantic validation errors | An endpoint returned an unexpected shape or model validation failed; some invalid input is also rejected locally. | Check the input and confirm that your SDK version is compatible with the server. | `ThinkPlatformApiError.response_body` contains the parsed error response when available. It can include sensitive information; do not log it indiscriminately. An HTTP error's message is derived from `message`, `detail`, or `error`, or the HTTP reason. Wrapped transport errors preserve the original `httpx` exception as `__cause__`; SDK API calls do not expose an `httpx.HTTPStatusError` for an unsuccessful status. ## Handle a read failure This example uses the explicit bearer-token and context environment settings from [resource workflows](/python-sdk/resources.md). It avoids printing tokens or response bodies. ```python import os from thinkplatform.sdk import ( MissingContextError, StaticTokenCredential, ThinkPlatformApiError, ThinkPlatformClient, TokenAcquisitionError, ) try: with ThinkPlatformClient( base_url=os.environ["THINKPLATFORM_API_BASE_URL"], credential=StaticTokenCredential(os.environ["THINKPLATFORM_ACCESS_TOKEN"]), org_id=int(os.environ["THINKPLATFORM_ORG_ID"]), project_id=int(os.environ["THINKPLATFORM_PROJECT_ID"]), ) as client: print(len(client.home.pages.list())) except MissingContextError: print("Set the required organization and project context.") except TokenAcquisitionError: print("Check the credential configuration.") except ThinkPlatformApiError as exc: if exc.status_code is None: print("The API could not be reached.") else: print(f"API request failed with HTTP {exc.status_code}.") ``` ## Retry behavior For normal API requests, the SDK reacts to HTTP **401** by invalidating the credential cache, requesting a token with `force_refresh=True`, and sending the request once more. A second failure is raised. Static tokens are unchanged by refresh. This retry can replay a write request too. The SDK does not automatically retry transport failures, HTTP 429, or HTTP 5xx responses in this request path. Design any application retry policy around the operation's safety. A timeout after a write does not prove the server rejected it; read the resource state before repeating a mutation. Handle authorization failures by checking permissions and context rather than repeatedly retrying. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /python-sdk/hosted-apps.md # Use the SDK inside a Hosted App Access project data through the current app request with narrowly declared permissions. Use **ThinkPlatform-client 0.6.134** inside a published Hosted App. The deployment must enable Hosted Apps and its SDK gateway, and the app must declare its required permissions at publication. See [Publish a web app](/cli/guides/apps.md) before adding data access. ## Create a client for one request Import `client_from_hosted_request` from `thinkplatform.sdk` and pass the incoming backend request headers. The platform supplies the gateway address and short-lived invocation information; no personal token or client secret belongs in your app image. ```python from thinkplatform.sdk import client_from_hosted_request def read_items(request_headers, table_id): with client_from_hosted_request(request_headers) as client: result = client.db.rows.query(table_id, {"page_size": 5}) return [{"id": row.id, "data": row.data} for row in result.items] ``` Call `read_items` inside your application's current authenticated request. Pass the actual request headers and a configured Table ID covered by `--table-read`. It returns up to five row IDs and their business values. The SDK is synchronous; an async server should run this work through its framework's supported thread-pool adapter. Close the client before that request finishes. Do not keep the headers, invocation handle or client in global state or background jobs. A browser cookie or a caller-supplied header from an arbitrary public endpoint is not a substitute for the configured Hosted App gateway. Missing or invalid invocation information raises `TokenAcquisitionError`. ## Match the app's permission grant | App operation | Publication permission | Verification | | --- | --- | --- | | Read selected Table rows | `--table-read TABLE_ID` | Query an allowed Table and check the returned row values. | | Write selected Table rows | `--table-write TABLE_ID` | Write the intended record and perform a separate authorized readback. | | Read the project Lakehouse | `--lakehouse-read` | Submit a read-only statement and inspect its status and results. | | Supported project API reads | Repeated `--project-permission` values | Check the accepted values in `tp apps publish --help` and test the intended read. | The user's current permissions and the app's declared grant must both allow the operation. A method appearing in the SDK does not mean the delegated gateway permits every operation in that namespace. Do not retry 401/403 with an operator token or a stronger identity. Review the grant, consent, project and user's access instead. ## Query the Lakehouse Within the same request, use `client.lakehouse.statements.execute("SELECT 1 AS example", wait_timeout="0s")`, then inspect the returned statement ID and state. Submission and completion are separate. Fetch status or chunks only within a valid authenticated app request; make a fresh request if the earlier invocation has ended. See [Lakehouse statements](/python-sdk/lakehouse.md) for the SDK methods and result representation. ## Publish from an external SDK client Outside the app, an authorized developer client can use `client.hosted_apps.publish(...)` for an image, `publish_source(...)` for a gzip source context, `list()`, `get(app_id)` and `stop(app_id, release)`. These are management calls; the request-bound app client is for the supported delegated data operations. The [API reference](/python-sdk/api-reference.md#hosted-apps) lists exact signatures. Source publication accepts a compressed context of at most 50 MiB and supports resumption with the same UUID and inputs. A submission returns a `HostedAppDeployment`; it is not proof of readiness. Inspect the recorded release and application URL before reporting success. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /python-sdk/lakehouse.md # Execute and inspect Lakehouse statements Submit SQL, inspect completion, read result chunks, and cancel an unfinished statement. These methods are available in **ThinkPlatform-client 0.6.133 and later**. Your project needs a configured SQL warehouse and permission for the intended operation. Select your project with a saved `work` profile as described in [Authentication](/cli/get-started/authentication.md). ## Submit a read-only statement ```python from thinkplatform.sdk import client_from_profile with client_from_profile("work") as client: statement = client.lakehouse.statements.execute( "SELECT 1 AS example", wait_timeout="0s" ) print(statement.statement_id, statement.status.state) ``` Save the returned ID. `wait_timeout="0s"` requests immediate submission status, so the statement may still be pending or running. The sample returns one value when successful; it does not create or change a table. ## Check status and read results Set `THINKPLATFORM_STATEMENT_ID` to your returned ID, then inspect it in a later call: ```python import os from thinkplatform.sdk import client_from_profile with client_from_profile("work") as client: statement = client.lakehouse.statements.get( os.environ["THINKPLATFORM_STATEMENT_ID"] ) print(statement.status.state) if statement.status.state == "SUCCEEDED": if statement.result is not None: print(statement.result.data_array) print("Next chunk:", statement.result.next_chunk_index) elif statement.status.error is not None: print(statement.status.error) ``` For the sample query, check that the successful result contains the value `1`. Native SQL results can represent numbers as strings. Inspect `manifest` for column and result metadata instead of assuming Python numeric types. If `next_chunk_index` is present, call `client.lakehouse.statements.result_chunk(statement_id, next_chunk_index)` and continue using each returned next index. A first chunk is not a complete multi-chunk result. Bound polling and chunk collection for your application, and retain the statement ID if it does not finish within that bound. Avoid resubmitting SQL merely because a status or connection request timed out. To request cancellation, call `client.lakehouse.statements.cancel(statement_id)`, then inspect the returned state and later status if necessary. A cancellation request does not prove a query stopped before all of its effects. ## Parameters and Hosted Apps `execute()` also accepts typed `LakehouseStatementParameter` values and an optional `schema`; see the [API reference](/python-sdk/api-reference.md#lakehouse-statements). Bind untrusted values through parameters rather than interpolating them into SQL. A Hosted App with `--lakehouse-read` uses the same statement methods through [request-bound SDK access](/python-sdk/hosted-apps.md). That grant is read-only and does not permit SQL writes. Inspect or poll only during a valid authenticated app request. For recurring Databricks jobs, inspect `tp lakehouse jobs schedule --help`. It accepts a Quartz schedule, timezone, pause state, or explicit removal. This is a Lakehouse job schedule; [ThinkPlatform scheduled automations](/guides/automation/schedules-and-webhooks.md) are configured separately. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /python-sdk/api-reference.md # Python API reference Look up client setup, credentials, resource methods, defaults, and return types in client 0.6.134. Import the client, credentials, factories, and response models from `thinkplatform.sdk`. Follow [Installation](/cli/get-started/installation.md) to install the SDK. This reference describes the synchronous SDK. For runnable examples, start with [resource workflows](/python-sdk/resources.md) and [database tables](/python-sdk/database.md). Response fields, aliases, and defaults are listed separately in [models and results](/python-sdk/models.md). | Area | Reference | | --- | --- | | Client setup | [Lifecycle](#create-and-close-a-client), [factories](#factories), [credentials](#credentials), [raw requests](#low-level-requests-and-uploads) | | Identity and scope | [User](#authenticated-user), [organizations](#organizations), [projects](#projects) | | Canvas | [Home](#home), [pages](#home-pages), [dashboard](#home-dashboard), [visualizations](#home-visualizations), [dynamic UI](#home-dynamic-ui) | | Shared database | [Tables](#database-tables), [rows](#database-rows), [workflow](/python-sdk/database.md) | | Data lake | [Paths, listing, transfer, and signed access](#data-lake) | | Agents | [Agents](#agents), [teams](#agent-teams), [workspaces](#agent-workspaces), [memories](#agent-memories) | | Tasks | [Tasks, messages, goals, and follow-ups](#tasks), [agent task checkpoints](#agent-tasks) | | Apps and delivery | [Cycle apps](#cycle-apps), [UI apps](#ui-apps), [inbound hooks](#inbound-hooks), [outbound webhooks](#outbound-webhooks) | | Reusable execution | [Modules](#modules), [skills](#skills), [flows](#flows), [CodeFlow](#codeflow-entrypoints) | | MLOps | [Models](#mlops-models), [jobs](#mlops-jobs), [data](#mlops-data), [environments](#mlops-environments), [hyperparameters](#mlops-hyperparameters) | | Devices | [Devices, modules, twins, and tags](#devices) | ## Reading signatures Signatures omit `self`. A `*` makes every following parameter keyword-only. Parameters without a default are required. `Optional[T]` means `T` or `None`; `Mapping` and `Iterable` are standard Python typing interfaces. `Any` means the SDK does not impose a more specific result schema. The signature blocks show how to call each method; use the workflow guides for executable examples. Where present, `org_id=None` and `project_id=None` fall back independently to the client's context. Project-scoped methods require both values and raise `MissingContextError` when they are absent. Organization-scoped methods require `org_id`. Context selects a scope; the credential and server still determine access. Methods whose signatures omit these keywords do not accept them. A `Mapping[str, Any]` payload is an endpoint-specific request object. Returned models describe responses. Before using their data to create or update a resource, check the deployed endpoint schema for required write fields. Mapping results use key access; models use attributes. ## Create and close a client ```text ThinkPlatformClient( *, base_url: str, credential: ThinkPlatformCredential, audience: Optional[str]=None, org_id: Optional[int]=None, project_id: Optional[int]=None, timeout_seconds: float=30.0, ) -> None ``` `base_url` is your API endpoint and `credential` supplies tokens. `timeout_seconds` configures HTTP request timeouts. `audience` identifies the API token audience where required by the credential. Use `with ThinkPlatformClient(...) as client:` to close the client on exit, or call `close()` in `finally`. `with_context()` returns a client with the supplied context; `None` preserves the existing value, so it cannot clear a context value. Context clients share the original HTTP connection pool. Keep the original client open until every context client has finished, then close the original. ```text close() -> None with_context(*, org_id: Optional[int]=None, project_id: Optional[int]=None) -> ThinkPlatformClient ``` ## Factories `client_from_env` and `client_from_profile` are available from `thinkplatform.sdk`. Pass an explicit endpoint or configure `THINKPLATFORM_API_BASE_URL`. Do not rely on a development endpoint default. `env=None` reads the process environment; an explicit mapping provides the environment source for the factory. ```text client_from_env( *, env: Optional[Mapping[str, str]]=None, base_url: Optional[str]=None, audience: Optional[str]=None, auth_mode: Optional[str]=None, org_id: Optional[int]=None, project_id: Optional[int]=None, timeout_seconds: float=30.0, ) -> ThinkPlatformClient client_from_profile( profile_name: Optional[str]=None, *, config_path: Optional[Any]=None, env: Optional[Mapping[str, str]]=None, base_url: Optional[str]=None, audience: Optional[str]=None, auth_mode: Optional[str]=None, org_id: Optional[int]=None, project_id: Optional[int]=None, timeout_seconds: float=30.0, ) -> ThinkPlatformClient ``` `client_from_env()` resolves supplied settings before environment settings and defaults its authentication mode to `azure-cli` when none is selected. `client_from_profile()` resolves a saved CLI profile and explicit overrides; see [authentication](/python-sdk/authentication.md) for configuration. Both return clients with the same lifecycle as the constructor. Import the token convenience factory from the client submodule: `from thinkplatform.sdk.client import client_from_token`. It is not exported from `thinkplatform.sdk` itself. ```text client_from_token( *, base_url: str, token: str, org_id: Optional[int]=None, project_id: Optional[int]=None, timeout_seconds: float=30.0, ) -> ThinkPlatformClient ``` ## Credentials All classes below are exported from `thinkplatform.sdk`. Credentials are used by the client; creating one does not verify token acquisition or API permissions. Token acquisition may fail when a request first needs it. See [authentication](/python-sdk/authentication.md) and [errors](/python-sdk/errors.md). ### StaticTokenCredential ```text StaticTokenCredential( token: str, *, expires_on: Optional[int]=None, source: str='static', claims: Optional[Mapping[str, Any]]=None, ) -> None ``` ### AzureCliCredential ```text AzureCliCredential( *, env: Optional[Mapping[str, str]]=None, tenant_id: Optional[str]=None, client_id: Optional[str]=None, refresh_buffer_seconds: int=300, ) -> None ``` ### DeviceCodeCredential ```text DeviceCodeCredential( *, env: Optional[Mapping[str, str]]=None, tenant_id: Optional[str]=None, client_id: Optional[str]=None, refresh_buffer_seconds: int=300, ) -> None ``` ### InteractiveBrowserCredential ```text InteractiveBrowserCredential( *, env: Optional[Mapping[str, str]]=None, tenant_id: Optional[str]=None, client_id: Optional[str]=None, refresh_buffer_seconds: int=300, ) -> None ``` ### WorkspaceDelegationCredential ```text WorkspaceDelegationCredential( *, env: Optional[Mapping[str, str]]=None, managed_identity_client_id: Optional[str]=None, workspace_id: Optional[int]=None, workspace_name: Optional[str]=None, workspace_assertion: Optional[str]=None, requested_scopes: Optional[list[str]]=None, refresh_buffer_seconds: int=300, timeout_seconds: float=30.0, ) -> None ``` `StaticTokenCredential` returns the supplied token information; cache invalidation does not refresh a static token. Replace it with a current token when needed. `expires_on` is an optional expiry timestamp in Unix seconds; `source` and `claims` describe token metadata. `AzureCliCredential` uses an existing Azure CLI login. `DeviceCodeCredential` and `InteractiveBrowserCredential` require an appropriate application client ID and may require a user to sign in. Their `env`, `tenant_id`, and `client_id` parameters select configuration; `refresh_buffer_seconds` controls cached-token refresh timing. `WorkspaceDelegationCredential` is for a configured managed workspace. Supply workspace configuration through its supported parameters or the environment provided to that workspace. `requested_scopes` specifies the scopes to request; it does not grant additional permissions. Consult your deployment's workspace setup before choosing this credential. ### Custom credentials Implement the exported `ThinkPlatformCredential` protocol. Return an [AccessTokenInfo](/python-sdk/models.md#accesstokeninfo) from `get_token_info()`. `invalidate_cache()` lets the client invalidate cached token state before a refresh attempt. ```text get_token_info( *, base_url: str, audience: Optional[str], org_id: Optional[int]=None, project_id: Optional[int]=None, force_refresh: bool=False, ) -> AccessTokenInfo invalidate_cache() -> None ``` ## Low-level requests and uploads Use these methods when you already know the API contract. `path` is an API request path. They do not discover payload schemas. `request_json()` and `request_multipart()` decode JSON; an empty body becomes `None`, and a non-JSON body becomes text. `request_raw()` preserves bytes in `RawResponse`. `MultipartFieldItems` means a mapping of field names to values or an iterable of `(name, value)` pairs. `MultipartFileItems` means the same structure with `MultipartFile` values; pairs permit repeated field names. `MultipartFile(filename, content, content_type=None)` takes bytes; `MultipartFile.from_text(filename, content, *, content_type=None, encoding="utf-8")` encodes text. ```text request_json( method: str, path: str, *, params: Optional[Mapping[str, Any]]=None, json_body: Optional[Any]=None, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> Any request_multipart( method: str, path: str, *, fields: Optional[MultipartFieldItems]=None, files: Optional[MultipartFileItems]=None, params: Optional[Mapping[str, Any]]=None, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> Any request_raw( method: str, path: str, *, params: Optional[Mapping[str, Any]]=None, json_body: Optional[Any]=None, multipart_fields: Optional[MultipartFieldItems]=None, multipart_files: Optional[MultipartFileItems]=None, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> RawResponse upload_to_url( url: str, *, content: bytes, content_type: Optional[str]=None, headers: Optional[Mapping[str, str]]=None, method: str='PUT', ) -> RawResponse ``` Authenticated requests accept relative paths or absolute URLs whose HTTP(S) origin exactly matches the configured API origin (scheme, normalized host, and effective port). Explicitly configured HTTP deployments are supported; a request cannot downgrade an HTTPS API. Invalid or ambiguous URLs and origin mismatches are rejected before credential acquisition. Redirects are not followed. Injected HTTP-client default headers, cookies, query parameters, and authentication are not inherited; explicit request headers and parameters still apply. `request_raw()` raises `ValueError` if a JSON body is combined with nonempty multipart fields or files. `upload_to_url()` sends bytes directly to a signed storage URL without API credentials. It preserves ordinary explicitly supplied storage headers and signed query parameters, but rejects `Authorization`, `Proxy-Authorization`, `Cookie`, and `X-TP-*` headers. Authorization-based storage transfers are unsupported; use the storage provider's client for those schemes. ## Resource namespaces Use namespace attributes on the client; do not construct resource implementation classes. The top-level namespaces are `auth`, `home`, `organizations`, `projects`, `mlops`, `datalake`, `skills`, `modules`, `flows`, `devices`, `db`, `agents`, `tasks`, `apps`, `hosted_apps`, `lakehouse`, `hooks`, and `webhooks`. `dashboard` and `canvas` are aliases of `home`. The nested containers are `home.pages`, `home.dashboard`, `home.visualizations`, `home.dynamic_ui`; `db.tables`, `db.rows`; `agents.tasks`, `agents.teams`, `agents.workspaces`, `agents.memories`; `apps.cycle`, `apps.ui`; `lakehouse.statements`; and `mlops.models`, `mlops.jobs`, `mlops.data`, `mlops.environments`, `mlops.hyperparameters`. Containers such as `db`, `apps`, and `mlops` have no create, read, update, or delete methods of their own. ### Authenticated user Namespace: `client.auth`. `whoami()` identifies the authenticated user. It has no context arguments. ```text whoami() -> AuthenticatedUser ``` ### Home Namespace: `client.home`. `data()` returns dashboard data for the selected project. `client.dashboard` and `client.canvas` refer to this same namespace. ```text data(*, org_id: Optional[int]=None, project_id: Optional[int]=None) -> Mapping[str, Any] ``` ### Home pages Namespace: `client.home.pages`. Page results are mappings. `create`, `update`, and `delete` write to the server. `update()` sends your payload without automatically fetching an `updated_at` value or adding an optimistic concurrency condition. A separate read and write are not atomic. ```text list(*, org_id: Optional[int]=None, project_id: Optional[int]=None) -> list[Mapping[str, Any]] get(page_id: str, *, org_id: Optional[int]=None, project_id: Optional[int]=None) -> Mapping[str, Any] create( payload: Mapping[str, Any], *, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> Mapping[str, Any] update( page_id: str, payload: Mapping[str, Any], *, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> Mapping[str, Any] delete(page_id: str, *, org_id: Optional[int]=None, project_id: Optional[int]=None) -> None ``` ### Home dashboard Namespace: `client.home.dashboard`. `lint()` validates a supplied dashboard definition. `query_dataset()` requests data for one dataset; `limit=500` bounds that request and `use_cache=True` permits caching. `inspect_schema()` requests its schema. These return mappings rather than typed dataset models. ```text lint( dashboard_definition: Mapping[str, Any], *, widgets: Optional[list[Mapping[str, Any]]]=None, ) -> Mapping[str, Any] query_dataset( dashboard_definition: Mapping[str, Any], dataset_id: str, *, filter_values: Optional[Mapping[str, Any]]=None, limit: int=500, use_cache: bool=True, warehouse_id: Optional[str]=None, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> Mapping[str, Any] inspect_schema( dashboard_definition: Mapping[str, Any], dataset_id: str, *, warehouse_id: Optional[str]=None, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> Mapping[str, Any] ``` ### Home visualizations Namespace: `client.home.visualizations`. Read visualization collections and individual visualization records. `list()` returns a mapping, not a Python list. ```text list(*, org_id: Optional[int]=None, project_id: Optional[int]=None) -> Mapping[str, Any] get(visualization_id: str, *, org_id: Optional[int]=None, project_id: Optional[int]=None) -> Mapping[str, Any] ``` ### Home dynamic UI Namespace: `client.home.dynamic_ui`. Read and write dynamic UI records. `list()` can filter by thread or canvas page and omits payloads by default (`include_payload=False`). ```text list( *, org_id: Optional[int]=None, project_id: Optional[int]=None, thread_id: Optional[str]=None, canvas_page_id: Optional[str]=None, include_payload: bool=False, ) -> list[Mapping[str, Any]] get(ui_id: str, *, org_id: Optional[int]=None, project_id: Optional[int]=None) -> Mapping[str, Any] create( payload: Mapping[str, Any], *, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> Mapping[str, Any] update( ui_id: str, payload: Mapping[str, Any], *, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> Mapping[str, Any] delete(ui_id: str, *, org_id: Optional[int]=None, project_id: Optional[int]=None) -> None ``` ### Organizations Namespace: `client.organizations`. List accessible organizations. No pagination parameters are accepted. ```text list() -> list[Organization] ``` ### Projects Namespace: `client.projects`. List accessible projects in an organization. `org_id` falls back to client context; no pagination parameters are accepted. ```text list(*, org_id: Optional[int]=None) -> list[Project] ``` ### Database tables Namespace: `client.db.tables`. Discover existing tables and retrieve their schema, columns, access metadata, and schema version. See the [database workflow](/python-sdk/database.md). Table creation and schema mutation are not exposed by this namespace. ```text list(*, org_id: Optional[int]=None, project_id: Optional[int]=None) -> list[SharedDbTableSummary] get(table_id: str, *, org_id: Optional[int]=None, project_id: Optional[int]=None) -> SharedDbTable ``` ### Database rows Namespace: `client.db.rows`. Read, query, create, and update rows in an existing table. `data` is a mapping of column keys to values; the SDK wraps it in a `data` envelope. For `create_many`, pass an iterable of these plain column-value mappings. Only `create_many()` accepts `expected_schema_version`. There is no row delete method. ```text get(table_id: str, row_id: str, *, org_id: Optional[int]=None, project_id: Optional[int]=None) -> SharedDbRow query( table_id: str, query: Mapping[str, Any], *, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> SharedDbRowQueryResult create( table_id: str, data: Mapping[str, Any], *, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> SharedDbRow create_many( table_id: str, rows: Iterable[Mapping[str, Any]], *, expected_schema_version: Optional[int]=None, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> Mapping[str, Any] update( table_id: str, row_id: str, data: Mapping[str, Any], *, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> SharedDbRow ``` ### Agents Namespace: `client.agents`. List and maintain agents, discover available models and system tools, and request workspace upload metadata. `list()` uses `limit` and `offset`. `create()` and `update()` reject nonempty legacy `knowledge_store` attachments with `ValueError` before writing. You can still read this field in historical records. `issue_workspace_upload()` requests upload metadata; it does not itself transfer file bytes. ```text list( *, q: Optional[str]=None, limit: int=50, offset: int=0, include_tools: bool=False, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> list[AgentSummary] create(payload: Mapping[str, Any], *, org_id: Optional[int]=None, project_id: Optional[int]=None) -> AgentDetail update( agent_id: int, payload: Mapping[str, Any], *, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> AgentDetail delete(agent_id: int, *, org_id: Optional[int]=None, project_id: Optional[int]=None) -> Mapping[str, Any] models() -> AgentAvailableModels system_tools_catalog(*, org_id: Optional[int]=None, project_id: Optional[int]=None) -> SystemToolCatalog issue_workspace_upload( agent_id: int, files: Iterable[Mapping[str, Any]], *, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> AgentWorkspaceUpload ``` ### Agent tasks Namespace: `client.agents.tasks`. Create and list tasks for agents or teams. Listing uses `limit` and `offset`. `checkpoints()` takes a thread ID and a direction, and returns messages and count metadata; it has no offset or continuation-token argument. Prefer the top-level `tasks` namespace for task status, messages, follow-ups, and goals. ```text create( *, title: str, description: Optional[str]=None, agent_id: Optional[int]=None, team_id: Optional[int]=None, thread_id: Optional[str]=None, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> Task list( *, agent_id: Optional[int]=None, team_id: Optional[int]=None, user_id: Optional[int]=None, task_type: Optional[str]=None, status: Optional[str]=None, q: Optional[str]=None, limit: int=100, offset: int=0, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> list[Task] checkpoints( thread_id: str, *, limit: int=100, direction: str='newest', org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> TaskCheckpointPage ``` ### Agent teams Namespace: `client.agents.teams`. List, create, update, or delete agent teams. `Team.agents` and `Team.subteams` contain numeric IDs. ```text list(*, org_id: Optional[int]=None, project_id: Optional[int]=None) -> list[Team] create(payload: Mapping[str, Any], *, org_id: Optional[int]=None, project_id: Optional[int]=None) -> Team update( team_id: int, payload: Mapping[str, Any], *, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> Team delete(team_id: int, *, org_id: Optional[int]=None, project_id: Optional[int]=None) -> None ``` ### Agent workspaces Namespace: `client.agents.workspaces`. List and maintain managed agent workspaces. `rollout_image()` requests an image rollout; track completion using the returned workspace status and the monitoring process for your deployment. ```text list(*, org_id: Optional[int]=None, project_id: Optional[int]=None) -> list[AgentWorkspace] get(workspace_id: int, *, org_id: Optional[int]=None, project_id: Optional[int]=None) -> AgentWorkspace create( payload: Mapping[str, Any], *, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> AgentWorkspace update( workspace_id: int, payload: Mapping[str, Any], *, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> AgentWorkspace rollout_image( workspace_id: int, *, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> AgentWorkspace delete(workspace_id: int, *, org_id: Optional[int]=None, project_id: Optional[int]=None) -> None ``` ### Agent memories Namespace: `client.agents.memories`. Search and maintain an agent’s memories, or import and export memory items. `context` defaults to `"all"`; search and export limits apply to a single response. These methods expose no continuation token or offset. `import_items()` returns counts of imported and failed items, along with any errors. ```text search( agent_id: int, *, q: str='', context: str='all', limit: int=20, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> MemorySearchResponse create( agent_id: int, payload: Mapping[str, Any], *, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> MemoryItem update( agent_id: int, memory_id: str, payload: Mapping[str, Any], *, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> MemoryItem delete( agent_id: int, memory_id: str, *, context: str='all', org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> None export( agent_id: int, *, context: str='all', limit: int=500, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> MemoryExportResponse import_items( agent_id: int, items: Iterable[Mapping[str, Any]], *, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> MemoryImportResponse ``` ### Tasks Namespace: `client.tasks`. `list()` supports filters and offset pagination; `status` can be a string or iterable of strings. `create()` creates a task, and `prepare_runtime()` requests runtime preparation. Methods for a known task ID such as `get`, `update`, `status`, `messages`, and goal operations do not accept context override keywords. `post_message()` sends a prompt and/or event; it does not return a typed completion stream. Follow-up methods return mappings; `include_inactive=False` is the default. Goal methods return a wrapper whose `goal` may be absent. ```text list( *, user_id: Optional[int]=None, agent_id: Optional[int]=None, team_id: Optional[int]=None, thread_id: Optional[str]=None, status: Optional[str | Iterable[str]]=None, q: Optional[str]=None, activity_from: Optional[str]=None, activity_to: Optional[str]=None, include_legacy_chat: bool=False, limit: int=100, offset: int=0, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> list[Task] create( *, title: Optional[str]=None, description: Optional[str]=None, agent_id: Optional[int]=None, team_id: Optional[int]=None, thread_id: Optional[str]=None, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> Task prepare_runtime( *, agent_id: Optional[int]=None, team_id: Optional[int]=None, is_private: bool=False, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> TaskRuntimePrepareResponse get(task_id: int) -> Task update(task_id: int, payload: Mapping[str, Any]) -> Task delete(task_id: int) -> Mapping[str, Any] status(task_id: int) -> Mapping[str, Any] messages(task_id: int) -> Mapping[str, Any] post_message(task_id: int, *, prompt: Optional[str]=None, event: Optional[str]=None) -> Mapping[str, Any] scheduled_followups(task_id: int, *, include_inactive: bool=False, limit: int=100) -> Mapping[str, Any] scheduled_followups_for_tasks( task_ids: Iterable[int], *, include_inactive: bool=False, limit: int=10, ) -> Mapping[str, Any] cancel_scheduled_followup(task_id: int, followup_id: int) -> Mapping[str, Any] goal(task_id: int) -> TaskGoalResponse create_goal(task_id: int, *, objective: str, token_budget: Optional[int]=None) -> TaskGoalResponse pause_goal(task_id: int) -> TaskGoalResponse resume_goal(task_id: int) -> TaskGoalResponse delete_goal(task_id: int) -> TaskGoalResponse ``` ### Cycle apps Namespace: `client.apps.cycle`. Maintain cycle apps, change status, and retrieve logs. `log()` requires `device_id`; `agent_log()` supports a time range and limit. Your deployed API determines accepted status strings and validates payloads. ```text list(*, org_id: Optional[int]=None, project_id: Optional[int]=None) -> list[CycleApp] create(payload: Mapping[str, Any], *, org_id: Optional[int]=None, project_id: Optional[int]=None) -> CycleApp update( app_id: int, payload: Mapping[str, Any], *, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> CycleApp update_status( app_id: int, status: str, *, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> CycleApp delete(app_id: int, *, org_id: Optional[int]=None, project_id: Optional[int]=None) -> Mapping[str, Any] log( app_id: int, *, device_id: str, flow_id: str='', tail: int=100, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> Mapping[str, Any] agent_log( app_id: int, *, limit: int=50, from_date: Optional[str]=None, to_date: Optional[str]=None, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> Mapping[str, Any] ``` ### UI apps Namespace: `client.apps.ui`. Maintain UI apps and load or save their layout. `save_layout()` takes an iterable of layout mappings; `load_layout()` returns a list of dictionaries. ```text list(*, org_id: Optional[int]=None, project_id: Optional[int]=None) -> list[UiApp] create(payload: Mapping[str, Any], *, org_id: Optional[int]=None, project_id: Optional[int]=None) -> UiApp update( app_id: int, payload: Mapping[str, Any], *, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> UiApp delete(app_id: int, *, org_id: Optional[int]=None, project_id: Optional[int]=None) -> Mapping[str, Any] load_layout(app_id: int, *, org_id: Optional[int]=None, project_id: Optional[int]=None) -> list[dict[str, Any]] save_layout( app_id: int, layout: Iterable[Mapping[str, Any]], *, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> Mapping[str, Any] ``` ### Inbound hooks Namespace: `client.hooks`. Manage inbound hook apps, rotate secrets, and inspect recent deliveries. `invoke()` addresses an endpoint key with a body and optional headers and query parameters; it does not accept organization/project override keywords. The hook configuration determines endpoint authorization. Delivery listing accepts a limit but no cursor. ```text list(*, org_id: Optional[int]=None, project_id: Optional[int]=None) -> list[HookApp] create(payload: Mapping[str, Any], *, org_id: Optional[int]=None, project_id: Optional[int]=None) -> HookApp update( hook_id: int, payload: Mapping[str, Any], *, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> HookApp delete(hook_id: int, *, org_id: Optional[int]=None, project_id: Optional[int]=None) -> Mapping[str, Any] rotate_secret(hook_id: int, *, org_id: Optional[int]=None, project_id: Optional[int]=None) -> HookApp deliveries( hook_id: int, *, limit: int=50, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> list[HookDelivery] invoke( endpoint_key: str, *, body: Any=None, headers: Optional[Mapping[str, str]]=None, params: Optional[Mapping[str, Any]]=None, ) -> HookInvokeAccepted ``` ### Outbound webhooks Namespace: `client.webhooks`. Manage outbound webhook subscriptions, discover event types, inspect deliveries, send tests, or retry one delivery. `send_test()` and `retry_delivery()` can cause outbound requests. Delivery listing accepts a limit but no cursor. ```text list(*, org_id: Optional[int]=None, project_id: Optional[int]=None) -> list[WebhookSubscription] event_types(*, org_id: Optional[int]=None, project_id: Optional[int]=None) -> list[WebhookEventTypeOption] create( payload: Mapping[str, Any], *, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> WebhookSubscription update( subscription_id: int, payload: Mapping[str, Any], *, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> WebhookSubscription delete(subscription_id: int, *, org_id: Optional[int]=None, project_id: Optional[int]=None) -> Mapping[str, Any] deliveries( subscription_id: int, *, limit: int=50, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> list[WebhookDelivery] send_test( subscription_id: int, payload: Optional[Mapping[str, Any]]=None, *, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> WebhookTestSendResponse retry_delivery( delivery_id: int, *, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> WebhookDelivery ``` ### MLOps models Namespace: `client.mlops.models`. Discover model assets and versions, inspect or download artifacts, request upload and download metadata, and register an asset. `download()` returns bytes and headers in `RawResponse`; `file_name=None` leaves file selection to the endpoint. Organization-scoped methods have no `project_id` parameter. Registration returns asset metadata; it does not upload model bytes. ```text list(*, org_id: Optional[int]=None, project_id: Optional[int]=None) -> list[MLOpsAsset] versions(model_name: str, *, org_id: Optional[int]=None) -> list[str] artifacts(model_name: str, model_version: str, *, org_id: Optional[int]=None) -> MLOpsArtifact download( model_name: str, model_version: str, *, file_name: Optional[str]=None, org_id: Optional[int]=None, ) -> RawResponse next_version(name: str, *, org_id: Optional[int]=None, project_id: Optional[int]=None) -> str sas( paths: Iterable[str], *, expires_in_minutes: int=180, datastore: Optional[str]=None, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> list[Mapping[str, Any]] register( *, name: str, version: str, base_path: str, model_type: str='custom_model', datastore: Optional[str]=None, description: str='', tags: Optional[Mapping[str, str]]=None, properties: Optional[Mapping[str, str]]=None, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> MLOpsAsset ``` ### MLOps jobs Namespace: `client.mlops.jobs`. Job listing returns `jobs` plus a continuation token. `get()` and `metrics()` preserve the decoded endpoint result as `Any`. Individual job reads are organization-scoped. ```text list( *, continuation_token: Optional[str]=None, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> MLOpsJobsPage get(job_id: str, *, org_id: Optional[int]=None) -> Any logs(job_id: str, *, org_id: Optional[int]=None) -> MLOpsJobLogs metrics(job_id: str, *, org_id: Optional[int]=None) -> Any ``` ### MLOps data Namespace: `client.mlops.data`. List data assets and versions, page through asset files, discover datastores, and request folder access metadata. `files()` returns `items`, `continuation_token`, and `root_prefix`; preserve the asset name, version, and path when following a token. ```text list(*, org_id: Optional[int]=None, project_id: Optional[int]=None) -> list[MLOpsAsset] versions(data_asset_name: str, *, org_id: Optional[int]=None, project_id: Optional[int]=None) -> list[str] files( data_asset_name: str, version: str, *, path: Optional[str]=None, continuation_token: Optional[str]=None, page_size: Optional[int]=None, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> MLOpsDataFilesPage datastores(*, org_id: Optional[int]=None) -> list[str] sas_folder( folder_path: str, *, data_asset_name: str, version: str, expires_in_minutes: int=180, datastore: Optional[str]=None, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> MLOpsFolderSas ``` ### MLOps environments Namespace: `client.mlops.environments`. List project MLOps environments. No pagination parameters are accepted. ```text list(*, org_id: Optional[int]=None, project_id: Optional[int]=None) -> list[MLOpsEnvironment] ``` ### MLOps hyperparameters Namespace: `client.mlops.hyperparameters`. Discover architecture names and the schema for one architecture. These methods have no organization/project override parameters; `schema()` preserves the decoded response as `Any`. ```text architectures() -> list[str] schema(architecture: str) -> Any ``` ### Data lake Namespace: `client.datalake`. Resolve paths; list a tree or one file-list page; preview, download, or upload content; and request signed access metadata. `list()` returns `items` plus a continuation token. `preview_text()` returns a preview model, while `download_text()` decodes downloaded bytes using `encoding` and `errors`. `upload_text()` encodes text first. Upload methods write content and return the storage response as `RawResponse`. Requested access durations are in minutes. ```text resolve(path: str, *, org_id: Optional[int]=None, project_id: Optional[int]=None) -> DatalakeResolvedPath list_tree(*, path: str='', org_id: Optional[int]=None, project_id: Optional[int]=None) -> list[DatalakeTreeItem] list( *, path: str='', continuation_token: Optional[str]=None, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> DatalakeListPage preview_text(path: str, *, org_id: Optional[int]=None, project_id: Optional[int]=None) -> DatalakeTextPreview preview_raw(path: str, *, org_id: Optional[int]=None, project_id: Optional[int]=None) -> RawResponse sas( paths: Iterable[str], *, operation: str='download', expires_in_minutes: int=60, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> list[Mapping[str, Any]] download_bytes( path: str, *, expires_in_minutes: int=30, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> bytes download_text( path: str, *, encoding: str='utf-8', errors: str='replace', expires_in_minutes: int=30, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> str upload_bytes( path: str, content: bytes, *, content_type: Optional[str]=None, expires_in_minutes: int=60, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> RawResponse upload_text( path: str, text: str, *, content_type: str='text/plain; charset=utf-8', encoding: str='utf-8', expires_in_minutes: int=60, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> RawResponse sas_folder( folder_path: str, *, expires_in_minutes: int=60, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> DatalakeFolderSas ``` ### Skills Namespace: `client.skills`. List, inspect, download, upload, or delete skills. `download()` returns `RawResponse`; read the downloaded bytes from its `body` attribute. `upload()` accepts multipart fields and files in the format required by your deployed API and returns `SkillMetadata`. ```text list(*, org_id: Optional[int]=None, project_id: Optional[int]=None) -> list[SkillMetadata] get(skill_id: str, *, org_id: Optional[int]=None, project_id: Optional[int]=None) -> SkillDetail download(skill_id: str, *, org_id: Optional[int]=None, project_id: Optional[int]=None) -> RawResponse upload( *, fields: Optional[MultipartFieldItems]=None, files: Optional[MultipartFileItems]=None, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> SkillMetadata delete(skill_id: str, *, org_id: Optional[int]=None, project_id: Optional[int]=None) -> Mapping[str, Any] ``` ### Modules Namespace: `client.modules`. List or search modules, retrieve details, resolve tool schemas, and invoke tools. `search()` filters the fetched module list locally and truncates it to `limit`; it is not a server paginator. `describe()` resolves an ID or name and raises `ValueError` for missing or ambiguous identifiers. `resolve()` may require `tool_name` when a module has multiple tools. `invoke_tool()` resolves an identifier before invocation, preserves its original result in `raw_result`, and normalizes `result`. `invoke()` returns the endpoint response without that additional normalization. Invocation returns `ModuleInvocationResult`; use `result`, `raw_result`, or the computed `normalized_result` according to the endpoint response. ```text list(*, org_id: Optional[int]=None, project_id: Optional[int]=None) -> list[ModuleSummary] search( query: str='', *, limit: int=20, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> list[ModuleSummary] get(module_id: str, *, org_id: Optional[int]=None, project_id: Optional[int]=None) -> ModuleDetail describe(identifier: str | int, *, org_id: Optional[int]=None, project_id: Optional[int]=None) -> ModuleDetail resolve( identifier: str | int, *, tool_name: Optional[str]=None, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> ModuleResolvedTool invoke( module_id: str, tool_name: str, *, input_data: Optional[Mapping[str, Any]]=None, config: Optional[Mapping[str, Any]]=None, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> ModuleInvocationResult invoke_tool( identifier: str | int, tool_name: str, *, input_data: Optional[Mapping[str, Any]]=None, config: Optional[Mapping[str, Any]]=None, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> ModuleInvocationResult ``` ### Flows Namespace: `client.flows`. List or create flows, save a flow definition, or run a flow with inputs and optional execution settings. `save()` and `run()` return dictionaries. `timeout_seconds` is an optional run request parameter, separate from the client HTTP timeout. ```text list(*, org_id: Optional[int]=None, project_id: Optional[int]=None) -> list[FlowSummary] create(payload: Mapping[str, Any], *, org_id: Optional[int]=None, project_id: Optional[int]=None) -> FlowDetail save( flow_id: str, flow_data: Mapping[str, Any], *, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> dict[str, Any] run( flow_id: str, *, inputs: Optional[Mapping[str, Any]]=None, device: Optional[str]=None, trigger: Optional[Mapping[str, Any]]=None, target: Optional[Mapping[str, Any]]=None, timeout_seconds: Optional[int]=None, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> dict[str, Any] ``` ### Devices Namespace: `client.devices`. List devices and modules, read module status and twins, and retrieve device tags. Status and twin results are untyped decoded values. The SDK exposes no device mutation methods here. ```text list(*, org_id: Optional[int]=None, project_id: Optional[int]=None) -> list[IoTDevice] modules(device_id: str, *, org_id: Optional[int]=None, project_id: Optional[int]=None) -> list[IoTModule] modules_status(device_id: str, *, org_id: Optional[int]=None, project_id: Optional[int]=None) -> Any module_twin( device_id: str, module_id: str, *, org_id: Optional[int]=None, project_id: Optional[int]=None, ) -> Any tags(device_id: str, *, org_id: Optional[int]=None, project_id: Optional[int]=None) -> DeviceTag ``` ## Pagination Pagination settings vary by method and must be supplied explicitly. The SDK does not provide a universal paginator or automatically fetch all pages. | Method | Page input | Result and next request | | --- | --- | --- | | `datalake.list()` | `continuation_token=None` | Read `items`; pass a nonempty `continuation_token` back with the same path/context. | | `mlops.jobs.list()` | `continuation_token=None` | Read `jobs`; pass a nonempty `continuation_token` into the next call. | | `mlops.data.files()` | `continuation_token=None`, `page_size=None` | Read `items`; pass the returned token back with the same asset/version/path/context. | | `tasks.list()`, `agents.tasks.list()` | `limit=100`, `offset=0` | Return a plain list. Request another offset explicitly; no total or cursor is attached. | | `agents.list()` | `limit=50`, `offset=0` | Return a plain list with no cursor metadata. | | `db.rows.query()` | The supplied query mapping | Read `items` and `meta.page`, `meta.page_size`, `meta.total`; see [database tables](/python-sdk/database.md). No SDK page arguments are added. | Methods with only a `limit` parameter do not accept an offset or continuation token. Other lists and mapping responses have only the arguments shown in their signatures. Use bounded loops and, for token pagination, guard against repeated tokens. ## CodeFlow entrypoints These helpers are exported from `thinkplatform.sdk` for Python Code Flow entrypoints. They attach and inspect metadata; decorating a function does not deploy, register, or execute it. ```text codeflow( *, input_schema: Optional[dict[str, Any]]=None, output_schema: Optional[dict[str, Any]]=None, name: Optional[str]=None, ) -> Callable[[F], F] get_codeflow_definition(func: Callable[..., Any]) -> Optional[CodeFlowDefinition] ``` `codeflow()` accepts optional JSON-schema dictionaries and a name, and returns a decorator that preserves the original function. A non-dictionary schema raises `TypeError`. `get_codeflow_definition()` returns `CodeFlowDefinition` for a decorated function, or `None`. `CodeFlowContext(org_id=None, project_id=None, workspace_url=None, metadata=...)` provides a lazily created `client` and a `tools` helper. Its organization and project fields are optional strings. The metadata mapping defaults to a fresh dictionary. The lazily created client uses SDK environment configuration; close `ctx.client` when your code owns that client’s lifecycle. `CodeFlowTools(ctx)` describes the tools selected for the entrypoint: ```text list() -> list[dict[str, Any]] get(alias: str) -> dict[str, Any] invoke( alias: str, input_data: Optional[Mapping[str, Any]]=None, *, config: Optional[Mapping[str, Any]]=None, ) -> ModuleInvocationResult ``` `list()` returns selected tool metadata; `get(alias)` raises `KeyError` when the alias is unavailable. `invoke()` calls the selected module tool and returns `ModuleInvocationResult`, preserving the original result in `raw_result` and normalizing `result`. It can raise `ValueError` when selected tool metadata lacks a module identifier. ## Errors and retry behavior Resource methods use the same [SDK exceptions](/python-sdk/errors.md): `MissingContextError` for absent required context, `TokenAcquisitionError` for credential failures, and `ThinkPlatformApiError` for HTTP or transport failures. HTTP errors expose `status_code` and `response_body`; transport errors may have no status. Unexpected response structures can raise `ValueError` or Pydantic validation errors. Local validation and identifier resolution can raise errors before any request. The API request path retries once after an HTTP 401 by asking the credential to refresh. A static token remains the same token. There is no general retry policy for rate limits, server errors, or failed writes; check whether the endpoint can safely repeat an operation before adding retries. Direct signed-URL transfers do not refresh API credentials. ## Hosted Apps Namespace: `client.hosted_apps`. Available since client 0.6.133. Management calls require an authorized developer client and an enabled deployment. These methods use the client's organization/project context; they do not accept per-call context overrides. ```text publish(app_id: str, *, name: str, image: str, ui_id: str, request_id: str, cpu: float=0.5, memory: str="1Gi", table_id: Optional[str]=None, replaces: Optional[str]=None, replaces_stopped: bool=False, permissions: Optional[HostedAppPermissions]=None) -> HostedAppDeployment publish_source(app_id: str, *, name: str, ui_id: str, request_id: str, source: bytes | None=None, cpu: float=0.5, memory: str="1Gi", table_id: str | None=None, replaces: str | None=None, replaces_stopped: bool=False, permissions: HostedAppPermissions | None=None) -> HostedAppDeployment list() -> list[HostedAppPublication] get(app_id: str) -> HostedAppPublication stop(app_id: str, release: str) -> None ``` `request_id` is a UUID. `publish_source()` accepts a gzip context of at most 50 MiB; use `source=None` to advance a build that already has its source, retaining the same options and request ID. Retain the expected previous release for updates. A returned deployment is not confirmation of readiness; read publication state. See [Publish a web app](/cli/guides/apps.md). ### Request-bound client factory ```text client_from_hosted_request(headers: Mapping[str, str], *, env: Optional[Mapping[str, str]]=None) -> ThinkPlatformClient ``` Import from `thinkplatform.sdk`. The factory validates current invocation information and the configured gateway before creating a project-bound client with a 20-second request timeout. It raises `TokenAcquisitionError` for missing or invalid invocation configuration. Close it within the current app request; method availability does not establish delegated API permission. See [Hosted App authentication](/python-sdk/hosted-apps.md). ## Lakehouse statements Namespace: `client.lakehouse.statements`. Available since client 0.6.133. Methods use the client's organization/project context and the configured warehouse. ```text execute(statement: str, *, parameters: Iterable[LakehouseStatementParameter]=(), schema: Optional[str]=None, wait_timeout: str="0s") -> LakehouseStatement get(statement_id: str) -> LakehouseStatement result_chunk(statement_id: str, chunk_index: int) -> LakehouseStatementResult cancel(statement_id: str) -> LakehouseStatement ``` The chunk index must be nonnegative. Submission, completion and cancellation are distinct observations; inspect status and retain the statement ID when polling times out. Results can include further chunks and numeric strings. See [Lakehouse statements](/python-sdk/lakehouse.md) for a complete submission/status example and the [result models](/python-sdk/models.md#lakehousestatement). ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /python-sdk/models.md # Models and results Look up SDK response fields, types, defaults, and JSON aliases. Import the named types on this page from `thinkplatform.sdk`. Find the method returning a type in the [API reference](/python-sdk/api-reference.md). These types describe decoded results. Check the endpoint schema for required fields when creating or updating resources. | Area | Common result types | | --- | --- | | Identity and scope | [AuthenticatedUser](#authenticateduser), [Organization](#organization), [Project](#project) | | Agents and workspaces | [AgentSummary](#agentsummary), [AgentDetail](#agentdetail), [AgentAvailableModels](#agentavailablemodels), [AgentWorkspace](#agentworkspace), [AgentWorkspaceUpload](#agentworkspaceupload) | | Tasks and teams | [Task](#task), [TaskGoalResponse](#taskgoalresponse), [TaskCheckpointPage](#taskcheckpointpage), [TaskRuntimePrepareResponse](#taskruntimeprepareresponse), [Team](#team) | | Apps and delivery | [CycleApp](#cycleapp), [UiApp](#uiapp), [HookApp](#hookapp), [WebhookSubscription](#webhooksubscription), [WebhookDelivery](#webhookdelivery) | | Hosted Apps | [HostedAppPermissions](#hostedapppermissions), [HostedAppDeployment](#hostedappdeployment), [HostedAppPublication](#hostedapppublication) | | Lakehouse SQL | [LakehouseStatement](#lakehousestatement), [LakehouseStatementStatus](#lakehousestatementstatus), [LakehouseStatementResult](#lakehousestatementresult), [LakehouseStatementParameter](#lakehousestatementparameter) | | Memory | [MemoryItem](#memoryitem), [MemorySearchResponse](#memorysearchresponse), [MemoryImportResponse](#memoryimportresponse) | | Shared database | [SharedDbTable](#shareddbtable), [SharedDbColumnDefinition](#shareddbcolumndefinition), [SharedDbRow](#shareddbrow), [SharedDbRowQueryResult](#shareddbrowqueryresult) | | Data lake | [DatalakeListPage](#datalakelistpage), [DatalakeListItem](#datalakelistitem), [DatalakeResolvedPath](#datalakeresolvedpath) | | MLOps | [MLOpsAsset](#mlopsasset), [MLOpsJobsPage](#mlopsjobspage), [MLOpsDataFilesPage](#mlopsdatafilespage), [MLOpsEnvironment](#mlopsenvironment) | | Modules, skills, flows | [ModuleDetail](#moduledetail), [ModuleInvocationResult](#moduleinvocationresult), [ModuleResolvedTool](#moduleresolvedtool), [SkillDetail](#skilldetail), [FlowDetail](#flowdetail) | | Devices | [IoTDevice](#iotdevice), [IoTModule](#iotmodule), [DeviceTag](#devicetag) | | Transport and credentials | [RawResponse](#rawresponse), [MultipartFile](#multipartfile), [AccessTokenInfo](#accesstokeninfo) | ## Model conventions Resource models are Pydantic models with attribute access. The tables describe fields declared by this client version; the server can add other fields, which these models allow. Optional response fields default to `None` unless another default is shown. Empty list/dictionary defaults are fresh per instance. An absent field may therefore appear as `None`, `[]`, or `{}` after parsing rather than indicating that the server explicitly returned that value. The Python field name is shown first. A JSON alias is the field name used in the response JSON; use the Python name when reading attributes. For example, `DatalakeListPage.continuation_token` reads JSON `continuationToken`, and `ModuleSummary.schema_` reads JSON `schema`. When producing JSON from a model, use Pydantic’s `model_dump(by_alias=True)` (v2) or `dict(by_alias=True)` (v1). A serialized response is not automatically a valid write payload. `Optional[T]` means `T` or `None`; `Any` leaves the value untyped. A union such as `AgentToolConfig | dict[str, Any]` permits either representation, so check the value before relying on nested attribute access. Timestamps are strings unless the field explicitly declares another type; the SDK does not convert them into Python `datetime` objects. Canvas pages, visualization records, dashboard results, and other methods returning `Mapping[str, Any]` use key access such as `page.get("title")`. `Any` results retain the endpoint’s decoded value without a named model. ## Read a JSON alias This example reads a JSON field through its Python attribute, then serializes the model using the JSON alias. It runs locally without a network request. ```python from thinkplatform.sdk import DatalakeListPage page = DatalakeListPage(items=[], continuationToken="example-next-page") assert page.continuation_token == "example-next-page" if hasattr(page, "model_dump"): wire = page.model_dump(by_alias=True) else: wire = page.dict(by_alias=True) assert wire["continuationToken"] == "example-next-page" print(page.items, page.continuation_token) ``` ## AuthenticatedUser | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `id` | `Optional[int]` | `None` | — | | `username` | `Optional[str]` | `None` | — | ## Organization | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `id` | `Optional[int]` | `None` | — | | `name` | `Optional[str]` | `None` | — | ## Project | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `id` | `Optional[int]` | `None` | — | | `name` | `Optional[str]` | `None` | — | | `organization_id` | `Optional[int]` | `None` | — | | `user_role` | `Optional[str]` | `None` | — | ## AgentToolConfig Use `schema_` for attribute access; its JSON alias is `schema`. | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `path` | `Optional[str]` | `None` | — | | `url` | `Optional[str]` | `None` | — | | `config` | `dict[str, Any]` | `{}` | — | | `schema_` | `Optional[dict[str, Any]]` | `None` | `schema` | | `description` | `Optional[str]` | `None` | — | | `title` | `Optional[str]` | `None` | — | | `device` | `Optional[str]` | `None` | — | | `name` | `Optional[str]` | `None` | — | | `type` | `Optional[str]` | `None` | — | | `spec` | `dict[str, Any]` | `{}` | — | | `approval_required` | `Optional[bool]` | `None` | — | | `icon_url` | `Optional[str]` | `None` | — | ## AgentDatabaseRef | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `kind` | `Optional[str]` | `None` | — | | `provider` | `Optional[str]` | `None` | — | | `id` | `Optional[str]` | `None` | — | ## AgentWorkspaceUploadFile | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `path` | `Optional[str]` | `None` | — | | `size` | `Optional[int]` | `None` | — | | `content_type` | `Optional[str]` | `None` | `contentType` | ## AgentWorkspaceUpload | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `upload_id` | `Optional[str]` | `None` | `uploadId` | | `container` | `Optional[str]` | `None` | — | | `base_path` | `Optional[str]` | `None` | `basePath` | | `expires_at` | `Optional[str]` | `None` | `expiresAt` | | `files` | `list[AgentWorkspaceUploadFile \| dict[str, Any]]` | `[]` | — | ## AgentSummary `knowledge_store` supports reading historical records. Nonempty new attachments are rejected by agent create/update methods. `AgentDetail` inherits this response shape. | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `id` | `Optional[int]` | `None` | — | | `name` | `Optional[str]` | `None` | — | | `model` | `Optional[str]` | `None` | — | | `system_prompt` | `Optional[str]` | `None` | — | | `knowledge_store` | `list[str]` | `[]` | — | | `databases` | `list[AgentDatabaseRef \| dict[str, Any]]` | `[]` | — | | `voice` | `Optional[str]` | `None` | — | | `tools` | `list[AgentToolConfig \| dict[str, Any]]` | `[]` | — | | `skills` | `list[dict[str, Any]]` | `[]` | — | | `avatar_url` | `Optional[str]` | `None` | — | | `access` | `Optional[dict[str, Any]]` | `None` | — | | `project_id` | `Optional[int]` | `None` | — | | `owner_project_id` | `Optional[int]` | `None` | — | ## AgentDetail Inherits all fields from [AgentSummary](#agentsummary). No additional fields. ## AgentAvailableModels | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `models` | `list[str]` | `[]` | — | | `presets` | `list[dict[str, str]]` | `[]` | — | | `options` | `list[dict[str, Any]]` | `[]` | — | | `default_model` | `Optional[str]` | `None` | — | | `default_selection` | `Optional[str]` | `None` | — | | `llm_type` | `Optional[str]` | `None` | — | ## SystemToolCatalog | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `catalog` | `dict[str, Any]` | `{}` | — | | `default_selection` | `dict[str, Any]` | `{}` | — | | `project_role` | `Optional[str]` | `None` | — | ## Task | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `id` | `Optional[int]` | `None` | — | | `thread_id` | `Optional[str]` | `None` | — | | `title` | `Optional[str]` | `None` | — | | `description` | `Optional[str]` | `None` | — | | `org_id` | `Optional[int]` | `None` | — | | `project_id` | `Optional[int]` | `None` | — | | `user_id` | `Optional[int]` | `None` | — | | `agent_id` | `Optional[int]` | `None` | — | | `team_id` | `Optional[int]` | `None` | — | | `created_by_task_id` | `Optional[int]` | `None` | — | | `agent_spawn_depth` | `Optional[int]` | `None` | — | | `type` | `Optional[str]` | `None` | — | | `status` | `Optional[str]` | `None` | — | | `updated_at` | `Optional[str]` | `None` | — | ## TaskGoal | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `id` | `Optional[int]` | `None` | — | | `task_id` | `Optional[int]` | `None` | — | | `thread_id` | `Optional[str]` | `None` | — | | `goal_id` | `Optional[str]` | `None` | — | | `objective` | `Optional[str]` | `None` | — | | `status` | `Optional[str]` | `None` | — | | `token_budget` | `Optional[int]` | `None` | — | | `tokens_used` | `Optional[int]` | `None` | — | | `time_used_seconds` | `Optional[int]` | `None` | — | | `created_at` | `Optional[str]` | `None` | — | | `updated_at` | `Optional[str]` | `None` | — | | `completed_at` | `Optional[str]` | `None` | — | ## TaskGoalResponse | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `goal` | `Optional[TaskGoal \| dict[str, Any]]` | `None` | — | ## TaskRuntimePrepareResponse | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `task_id` | `Optional[int]` | `None` | — | | `thread_id` | `Optional[str]` | `None` | — | | `status` | `Optional[str]` | `None` | — | | `expires_at` | `Optional[str]` | `None` | — | | `is_private` | `Optional[bool]` | `None` | — | | `reused` | `Optional[bool]` | `None` | — | ## Team | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `id` | `Optional[int]` | `None` | — | | `name` | `Optional[str]` | `None` | — | | `description` | `Optional[str]` | `None` | — | | `org_id` | `Optional[int]` | `None` | — | | `project_id` | `Optional[int]` | `None` | — | | `agents` | `list[int]` | `[]` | — | | `subteams` | `list[int]` | `[]` | — | ## TaskCheckpointPage Contains checkpoint metadata and messages. It has no offset or continuation token. | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `count` | `Optional[int]` | `None` | — | | `returned` | `Optional[int]` | `None` | — | | `direction` | `Optional[str]` | `None` | — | | `messages` | `list[dict[str, Any]]` | `[]` | — | ## ScheduleConfig | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `type` | `Optional[str]` | `None` | — | | `time_of_day` | `Optional[str]` | `None` | `time` | | `days_of_week` | `Optional[list[int]]` | `None` | `daysOfWeek` | | `days_of_month` | `Optional[list[int \| str]]` | `None` | `daysOfMonth` | | `run_at` | `Optional[str]` | `None` | `runAt` | | `start_at` | `Optional[str]` | `None` | `startAt` | | `timezone` | `Optional[str]` | `None` | — | | `minute` | `Optional[int]` | `None` | — | | `second` | `Optional[int]` | `None` | — | | `interval_seconds` | `Optional[float]` | `None` | `intervalSeconds` | ## TriggerConfig | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `mode` | `Optional[str]` | `None` | — | | `interval_seconds` | `Optional[float]` | `None` | `intervalSeconds` | | `schedule` | `Optional[ScheduleConfig \| dict[str, Any]]` | `None` | — | | `catch_up_missed` | `Optional[bool]` | `None` | `catchUpMissed` | ## CycleApp | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `id` | `Optional[int]` | `None` | — | | `project_id` | `Optional[int]` | `None` | — | | `name` | `Optional[str]` | `None` | — | | `description` | `Optional[str]` | `None` | — | | `targetType` | `Optional[str]` | `None` | — | | `deviceId` | `Optional[str]` | `None` | — | | `flowId` | `Optional[str]` | `None` | — | | `agentId` | `Optional[int]` | `None` | — | | `agentPrompt` | `Optional[str]` | `None` | — | | `memoryEnabled` | `Optional[bool]` | `None` | — | | `interval` | `Optional[float]` | `None` | — | | `status` | `Optional[str]` | `None` | — | | `retry` | `Optional[int]` | `None` | — | | `inputs` | `list[Any]` | `[]` | — | | `trigger` | `Optional[TriggerConfig \| dict[str, Any]]` | `None` | — | | `runAsUserId` | `Optional[int]` | `None` | — | | `next_run_at` | `Optional[str]` | `None` | — | | `last_run_at` | `Optional[str]` | `None` | — | | `last_error` | `Optional[str]` | `None` | — | | `fail_count` | `Optional[int]` | `None` | — | | `schedule_metadata` | `Optional[dict[str, Any]]` | `None` | — | ## UiApp | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `id` | `Optional[int]` | `None` | — | | `project_id` | `Optional[int]` | `None` | — | | `name` | `Optional[str]` | `None` | — | | `description` | `Optional[str]` | `None` | — | | `show_on_dashboard` | `Optional[bool]` | `None` | — | | `dashboard_tab_label` | `Optional[str]` | `None` | — | | `is_default_on_dashboard` | `Optional[bool]` | `None` | — | ## AgentWorkspaceEnvVar | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `key` | `Optional[str]` | `None` | — | | `value` | `Optional[str]` | `None` | — | ## AgentWorkspaceStorageMount | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `storage_path` | `Optional[str]` | `None` | — | | `mount_path` | `Optional[str]` | `None` | — | ## AgentWorkspace The model includes legacy `secrets` and `internet_access` fields for reading existing records. Do not include them in create or update requests: the API rejects those write fields. See [Security and authentication](/admin/security-and-authentication.md) for runtime credentials and network policy. | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `id` | `Optional[int]` | `None` | — | | `name` | `Optional[str]` | `None` | — | | `description` | `Optional[str]` | `None` | — | | `type` | `Optional[str]` | `None` | — | | `workspace_url` | `Optional[str]` | `None` | — | | `container_image` | `Optional[str]` | `None` | — | | `image_policy` | `Optional[str]` | `None` | — | | `pinned_image` | `Optional[str]` | `None` | — | | `deployed_image_digest` | `Optional[str]` | `None` | — | | `latest_image_digest` | `Optional[str]` | `None` | — | | `update_available` | `Optional[bool]` | `None` | — | | `env_vars` | `list[AgentWorkspaceEnvVar \| dict[str, Any]]` | `[]` | — | | `secrets` | `list[AgentWorkspaceEnvVar \| dict[str, Any]]` | `[]` | — | | `internet_access` | `Optional[bool]` | `None` | — | | `github_repo` | `Optional[str]` | `None` | — | | `setup_script` | `Optional[str]` | `None` | — | | `cloud_storage_mounts` | `list[AgentWorkspaceStorageMount \| dict[str, Any]]` | `[]` | — | | `allowed_blob_paths` | `list[str]` | `[]` | — | | `provisioning_state` | `Optional[str]` | `None` | — | | `device_id` | `Optional[str]` | `None` | — | | `access` | `Optional[dict[str, Any]]` | `None` | — | | `cpu` | `Optional[float]` | `None` | — | | `memory` | `Optional[str]` | `None` | — | | `targetPort` | `Optional[int]` | `None` | — | | `owner_project_id` | `Optional[int]` | `None` | — | ## MemoryItem | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `id` | `Optional[str]` | `None` | — | | `context` | `Optional[str]` | `None` | — | | `text` | `Optional[str]` | `None` | — | | `metadata` | `Optional[dict[str, Any]]` | `None` | — | ## MemorySearchResponse | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `items` | `list[MemoryItem \| dict[str, Any]]` | `[]` | — | ## MemoryImportResponse | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `imported` | `Optional[int]` | `None` | — | | `failed` | `Optional[int]` | `None` | — | | `errors` | `list[str]` | `[]` | — | ## MemoryExportResponse | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `items` | `list[MemoryItem \| dict[str, Any]]` | `[]` | — | ## HookResolvedAuthInfo | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `tenant_id` | `Optional[str]` | `None` | `tenantId` | | `audience` | `Optional[str]` | `None` | — | | `token_scope` | `Optional[str]` | `None` | `tokenScope` | | `expected_caller_app_id` | `Optional[str]` | `None` | `expectedCallerAppId` | | `required_role` | `Optional[str]` | `None` | `requiredRole` | ## HookApp Some operations return secrets in credential fields. Protect these values as you would any other credential. | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `id` | `Optional[int]` | `None` | — | | `project_id` | `Optional[int]` | `None` | — | | `name` | `Optional[str]` | `None` | — | | `description` | `Optional[str]` | `None` | — | | `enabled` | `Optional[bool]` | `None` | — | | `target_type` | `Optional[str]` | `None` | `targetType` | | `agent_id` | `Optional[int]` | `None` | `agentId` | | `flow_id` | `Optional[str]` | `None` | `flowId` | | `run_as_user_id` | `Optional[int]` | `None` | `runAsUserId` | | `instruction_text` | `Optional[str]` | `None` | `instructionText` | | `payload_mode` | `Optional[str]` | `None` | `payloadMode` | | `mapping_mode` | `Optional[str]` | `None` | `mappingMode` | | `mapping_config` | `dict[str, Any]` | `{}` | `mappingConfig` | | `auth_mode` | `Optional[str]` | `None` | `authMode` | | `auth_config` | `dict[str, Any]` | `{}` | `authConfig` | | `endpoint_key` | `Optional[str]` | `None` | `endpointKey` | | `generated_secret` | `Optional[str]` | `None` | `generatedSecret` | | `last_delivery_at` | `Optional[str]` | `None` | `lastDeliveryAt` | | `last_error` | `Optional[str]` | `None` | `lastError` | | `resolved_auth_info` | `Optional[HookResolvedAuthInfo]` | `None` | `resolvedAuthInfo` | | `resolved_auth_error` | `Optional[str]` | `None` | `resolvedAuthError` | ## HookDelivery | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `id` | `Optional[int]` | `None` | — | | `hook_app_id` | `Optional[int]` | `None` | `hookAppId` | | `status` | `Optional[str]` | `None` | — | | `request_id` | `Optional[str]` | `None` | `requestId` | | `received_at` | `Optional[str]` | `None` | `receivedAt` | | `content_type` | `Optional[str]` | `None` | `contentType` | | `headers_json` | `Optional[dict[str, Any]]` | `None` | `headersJson` | | `query_json` | `Optional[dict[str, Any]]` | `None` | `queryJson` | | `body_text` | `Optional[str]` | `None` | `bodyText` | | `body_json` | `Any` | `None` | `bodyJson` | | `task_id` | `Optional[int]` | `None` | `taskId` | | `error_message` | `Optional[str]` | `None` | `errorMessage` | | `response_code` | `Optional[int]` | `None` | `responseCode` | ## HookInvokeAccepted | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `delivery_id` | `Optional[int]` | `None` | `deliveryId` | | `status` | `Optional[str]` | `None` | — | | `task_id` | `Optional[int]` | `None` | `taskId` | | `received_at` | `Optional[str]` | `None` | `receivedAt` | ## WebhookSubscription | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `id` | `Optional[int]` | `None` | — | | `project_id` | `Optional[int]` | `None` | `projectId` | | `name` | `Optional[str]` | `None` | — | | `description` | `Optional[str]` | `None` | — | | `enabled` | `Optional[bool]` | `None` | — | | `target_url` | `Optional[str]` | `None` | `targetUrl` | | `event_types` | `list[str]` | `[]` | `eventTypes` | | `timeout_seconds` | `Optional[int]` | `None` | `timeoutSeconds` | | `max_attempts` | `Optional[int]` | `None` | `maxAttempts` | | `retry_backoff_seconds` | `Optional[int]` | `None` | `retryBackoffSeconds` | | `auth_mode` | `Optional[str]` | `None` | `authMode` | | `custom_headers_json` | `dict[str, str]` | `{}` | `customHeadersJson` | | `has_auth_secret` | `Optional[bool]` | `None` | `hasAuthSecret` | | `has_signing_secret` | `Optional[bool]` | `None` | `hasSigningSecret` | | `last_delivery_at` | `Optional[str]` | `None` | `lastDeliveryAt` | | `last_error` | `Optional[str]` | `None` | `lastError` | | `created_at` | `Optional[str]` | `None` | `createdAt` | | `updated_at` | `Optional[str]` | `None` | `updatedAt` | ## WebhookEventTypeOption | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `event_type` | `Optional[str]` | `None` | `eventType` | | `label` | `Optional[str]` | `None` | — | | `description` | `Optional[str]` | `None` | — | | `category` | `Optional[str]` | `None` | — | | `test_only` | `Optional[bool]` | `None` | `testOnly` | ## WebhookDelivery | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `id` | `Optional[int]` | `None` | — | | `delivery_key` | `Optional[str]` | `None` | `deliveryKey` | | `subscription_id` | `Optional[int]` | `None` | `subscriptionId` | | `event_id` | `Optional[int]` | `None` | `eventId` | | `event_key` | `Optional[str]` | `None` | `eventKey` | | `event_type` | `Optional[str]` | `None` | `eventType` | | `status` | `Optional[str]` | `None` | — | | `attempt_count` | `Optional[int]` | `None` | `attemptCount` | | `next_attempt_at` | `Optional[str]` | `None` | `nextAttemptAt` | | `locked_at` | `Optional[str]` | `None` | `lockedAt` | | `locked_by` | `Optional[str]` | `None` | `lockedBy` | | `last_response_code` | `Optional[int]` | `None` | `lastResponseCode` | | `last_response_body` | `Optional[str]` | `None` | `lastResponseBody` | | `last_error` | `Optional[str]` | `None` | `lastError` | | `delivered_at` | `Optional[str]` | `None` | `deliveredAt` | | `created_at` | `Optional[str]` | `None` | `createdAt` | | `updated_at` | `Optional[str]` | `None` | `updatedAt` | ## WebhookTestSendResponse | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `subscription_id` | `Optional[int]` | `None` | `subscriptionId` | | `event_id` | `Optional[int]` | `None` | `eventId` | | `delivery_id` | `Optional[int]` | `None` | `deliveryId` | | `delivery_key` | `Optional[str]` | `None` | `deliveryKey` | | `status` | `Optional[str]` | `None` | — | ## SharedDbAccessProject | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `id` | `Optional[str]` | `None` | — | | `name` | `Optional[str]` | `None` | — | ## SharedDbAccessSpec | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `mode` | `Optional[str]` | `None` | — | | `projects` | `dict[str, SharedDbAccessProject]` | `{}` | — | ## SharedDbColumnDefinition | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `id` | `Optional[str]` | `None` | — | | `key` | `Optional[str]` | `None` | — | | `label` | `Optional[str]` | `None` | — | | `description` | `Optional[str]` | `None` | — | | `type` | `Optional[str]` | `None` | — | | `required` | `Optional[bool]` | `None` | — | | `options` | `Optional[list[str]]` | `None` | — | | `order` | `Optional[int]` | `None` | — | | `status` | `Optional[str]` | `None` | — | | `deleted_at` | `Optional[str]` | `None` | — | ## SharedDbQueryFilter The fields describe filter structure only. Check your deployed API for supported operators and their expected values; this model does not validate or enumerate them. | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `field` | `Optional[str]` | `None` | — | | `op` | `Optional[str]` | `None` | — | | `value` | `Any` | `None` | — | ## SharedDbQuerySort Sort field and direction are strings, not an SDK enumeration. Check your deployed API for supported values. | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `field` | `Optional[str]` | `None` | — | | `direction` | `Optional[str]` | `None` | — | ## SharedDbQueryMetadata Query page metadata is optional. It is distinct from continuation tokens used for data lake and MLOps listing. | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `page` | `Optional[int]` | `None` | — | | `page_size` | `Optional[int]` | `None` | — | | `total` | `Optional[int]` | `None` | — | ## SharedDbTableSummary | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `id` | `Optional[str]` | `None` | — | | `owner_project_id` | `Optional[int]` | `None` | — | | `name` | `Optional[str]` | `None` | — | | `description` | `Optional[str]` | `None` | — | | `access_mode` | `Optional[str]` | `None` | — | | `schema_version` | `Optional[int]` | `None` | — | | `updated_at` | `Optional[str]` | `None` | — | ## SharedDbTable Inspect `columns` and `schema_version` before a write. Table access metadata describes server-controlled sharing. | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `id` | `Optional[str]` | `None` | — | | `org_id` | `Optional[int]` | `None` | — | | `owner_project_id` | `Optional[int]` | `None` | — | | `name` | `Optional[str]` | `None` | — | | `description` | `Optional[str]` | `None` | — | | `access` | `SharedDbAccessSpec` | `SharedDbAccessSpec()` | — | | `schema_version` | `Optional[int]` | `None` | — | | `columns` | `list[SharedDbColumnDefinition]` | `[]` | — | | `created_at` | `Optional[str]` | `None` | — | | `updated_at` | `Optional[str]` | `None` | — | | `created_by` | `Optional[int]` | `None` | — | | `updated_by` | `Optional[int]` | `None` | — | ## SharedDbRow User columns are nested under `data`; `id`, `schema_version`, and audit fields are row metadata. | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `id` | `Optional[str]` | `None` | — | | `org_id` | `Optional[int]` | `None` | — | | `project_id` | `Optional[int]` | `None` | — | | `table_id` | `Optional[str]` | `None` | — | | `schema_version` | `Optional[int]` | `None` | — | | `data` | `dict[str, Any]` | `{}` | — | | `created_at` | `Optional[str]` | `None` | — | | `updated_at` | `Optional[str]` | `None` | — | | `created_by` | `Optional[int]` | `None` | — | | `updated_by` | `Optional[int]` | `None` | — | ## SharedDbRowQueryResult | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `items` | `list[SharedDbRow]` | `[]` | — | | `meta` | `SharedDbQueryMetadata` | `SharedDbQueryMetadata()` | — | ## DatalakeTreeItem | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `name` | `Optional[str]` | `None` | — | | `path` | `Optional[str]` | `None` | — | | `logical_path` | `Optional[str]` | `None` | — | | `physical_path` | `Optional[str]` | `None` | — | | `has_children` | `Optional[bool]` | `None` | — | ## DatalakeListItem | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `name` | `Optional[str]` | `None` | — | | `path` | `Optional[str]` | `None` | — | | `logical_path` | `Optional[str]` | `None` | — | | `physical_path` | `Optional[str]` | `None` | — | | `is_directory` | `Optional[bool]` | `None` | — | | `last_modified` | `Optional[str]` | `None` | — | | `size` | `Optional[int]` | `None` | — | ## DatalakeListPage Pass a nonempty `continuation_token` to the next `datalake.list()` call with the same path and context. | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `items` | `list[DatalakeListItem]` | `[]` | — | | `continuation_token` | `Optional[str]` | `None` | `continuationToken` | | `resolved_path` | `Optional[dict[str, Any]]` | `None` | — | | `warnings` | `list[str]` | `[]` | — | ## DatalakeTextPreview | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `content` | `Optional[str]` | `None` | — | ## DatalakeFolderSas Signed access metadata can contain a time-limited access URL. Use it only for the intended storage operation. | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `path` | `Optional[str]` | `None` | — | | `sas_url` | `Optional[str]` | `None` | — | | `expires_at` | `Optional[str]` | `None` | — | ## DatalakeResolvedPath | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `input_path` | `Optional[str]` | `None` | — | | `logical_path` | `Optional[str]` | `None` | — | | `physical_path` | `Optional[str]` | `None` | — | | `scope` | `Optional[str]` | `None` | — | | `abfss_uri` | `Optional[str]` | `None` | — | | `container` | `Optional[str]` | `None` | — | | `storage_account` | `Optional[str]` | `None` | — | ## MLOpsAsset | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `name` | `Optional[str]` | `None` | — | | `version` | `Optional[str]` | `None` | — | | `latest_version` | `Optional[str]` | `None` | — | | `tags` | `dict[str, Any]` | `{}` | — | | `path` | `Optional[str]` | `None` | — | | `type` | `Optional[str]` | `None` | — | | `auto_delete_setting` | `Optional[str]` | `None` | — | | `description` | `Optional[str]` | `None` | — | | `properties` | `dict[str, Any]` | `{}` | — | | `id` | `Optional[str]` | `None` | — | | `base_path` | `Optional[str]` | `None` | — | | `datastore` | `Optional[str]` | `None` | — | | `producer_job_name` | `Optional[str]` | `None` | — | ## MLOpsJob | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `id` | `Optional[str]` | `None` | — | | `name` | `Optional[str]` | `None` | — | | `status` | `Optional[str]` | `None` | — | | `experiment_name` | `Optional[str]` | `None` | — | | `run_id` | `Optional[str]` | `None` | — | | `job_name` | `Optional[str]` | `None` | — | | `experiment_id` | `Optional[str]` | `None` | — | | `created` | `Optional[str]` | `None` | — | ## MLOpsJobsPage The records are in `jobs`, rather than `items`. Pass a nonempty `continuation_token` to the next jobs list call. | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `jobs` | `list[MLOpsJob]` | `[]` | — | | `continuation_token` | `Optional[str]` | `None` | — | ## MLOpsJobLogs | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `logs` | `Optional[str]` | `None` | — | ## MLOpsArtifact | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `name` | `Optional[str]` | `None` | — | | `version` | `Optional[str]` | `None` | — | | `tags` | `dict[str, Any]` | `{}` | — | | `path` | `Optional[str]` | `None` | — | | `type` | `Optional[str]` | `None` | — | | `description` | `Optional[str]` | `None` | — | | `properties` | `dict[str, Any]` | `{}` | — | | `stage` | `Optional[str]` | `None` | — | | `files` | `list[str]` | `[]` | — | ## MLOpsDataFile | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `name` | `Optional[str]` | `None` | — | | `path` | `Optional[str]` | `None` | — | | `is_directory` | `Optional[bool]` | `None` | — | | `size` | `Optional[int]` | `None` | — | ## MLOpsDataFilesPage Pass a nonempty `continuation_token` to the next file-list call with the same asset, version, path, and context. | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `items` | `list[MLOpsDataFile]` | `[]` | — | | `continuation_token` | `Optional[str]` | `None` | `continuationToken` | | `root_prefix` | `Optional[str]` | `None` | `rootPrefix` | ## MLOpsFolderSas Signed access metadata can contain a time-limited access URL. Use it only for the intended storage operation. | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `path` | `Optional[str]` | `None` | — | | `sas_url` | `Optional[str]` | `None` | — | | `expires_at` | `Optional[str]` | `None` | — | ## MLOpsEnvironmentCreationContext | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `created_at` | `Optional[str]` | `None` | — | | `created_by` | `Optional[str]` | `None` | — | | `created_by_type` | `Optional[str]` | `None` | — | | `last_modified_at` | `Optional[str]` | `None` | — | | `last_modified_by` | `Optional[str]` | `None` | — | | `last_modified_by_type` | `Optional[str]` | `None` | — | ## MLOpsEnvironment | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `creation_context` | `Optional[MLOpsEnvironmentCreationContext]` | `None` | — | | `description` | `Optional[str]` | `None` | — | | `id` | `Optional[str]` | `None` | — | | `image` | `Optional[str]` | `None` | — | | `name` | `Optional[str]` | `None` | — | | `os_type` | `Optional[str]` | `None` | — | | `tags` | `dict[str, str]` | `{}` | — | | `version` | `Optional[str]` | `None` | — | ## SkillRef | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `id` | `Optional[str]` | `None` | — | | `name` | `Optional[str]` | `None` | — | | `description` | `Optional[str]` | `None` | — | | `blob_prefix` | `Optional[str]` | `None` | — | | `skill_md_path` | `Optional[str]` | `None` | — | ## SkillMetadata Inherits all fields from [SkillRef](#skillref). | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `created_at` | `Optional[str]` | `None` | — | | `updated_at` | `Optional[str]` | `None` | — | | `size_bytes` | `Optional[int]` | `None` | — | ## SkillDetail Inherits all fields from [SkillMetadata](#skillmetadata). | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `files` | `list[str]` | `[]` | — | | `skill_md_content` | `Optional[str]` | `None` | — | ## ModuleSummary | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `id` | `Optional[int]` | `None` | — | | `name` | `Optional[str]` | `None` | — | | `url` | `Optional[str]` | `None` | — | | `type` | `Optional[str]` | `None` | — | | `device` | `Optional[str]` | `None` | — | | `schema_` | `Optional[dict[str, Any]]` | `None` | `schema` | | `spec` | `Optional[dict[str, Any]]` | `None` | — | | `access` | `Optional[dict[str, Any]]` | `None` | — | | `project_id` | `Optional[int]` | `None` | — | | `owner_project_id` | `Optional[int]` | `None` | — | | `icon_url` | `Optional[str]` | `None` | — | ## ModuleDetail Inherits all fields from [ModuleSummary](#modulesummary). | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `spec_text` | `Optional[str]` | `None` | — | ## ModuleInvocationResult The computed read-only property `normalized_result: Any` normalizes common module/MCP content wrappers. It is derived from `result`; it is not a stored response field. | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `apiId` | `Optional[int]` | `None` | — | | `tool` | `Optional[str]` | `None` | — | | `result` | `Any` | `None` | — | | `raw_result` | `Any` | `None` | — | ## ModuleResolvedTool | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `module_id` | `Optional[int \| str]` | `None` | — | | `module_name` | `Optional[str]` | `None` | — | | `tool_name` | `Optional[str]` | `None` | — | | `input_schema` | `dict[str, Any]` | `{}` | — | | `output_schema` | `dict[str, Any]` | `{}` | — | | `description` | `Optional[str]` | `None` | — | ## FlowSummary | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `id` | `Optional[str]` | `None` | — | | `name` | `Optional[str]` | `None` | — | | `description` | `Optional[str]` | `None` | — | | `mode` | `Optional[str]` | `None` | — | | `device` | `Optional[str]` | `None` | — | | `path` | `Optional[str]` | `None` | — | | `tags` | `list[str]` | `[]` | — | | `nodes` | `list[dict[str, Any]]` | `[]` | — | | `edges` | `list[dict[str, Any]]` | `[]` | — | | `input_schema` | `dict[str, Any]` | `{}` | — | | `output_schema` | `dict[str, Any]` | `{}` | — | | `project_id` | `Optional[int]` | `None` | — | ## FlowDetail Inherits all fields from [FlowSummary](#flowsummary). No additional fields. ## DeviceShareProject | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `id` | `Optional[str]` | `None` | — | | `name` | `Optional[str]` | `None` | — | ## DeviceAccessTag | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `mode` | `Optional[str]` | `None` | — | | `projects` | `dict[str, DeviceShareProject]` | `{}` | — | ## DeviceTag | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `organization` | `dict[str, Any]` | `{}` | — | | `project` | `dict[str, Any]` | `{}` | — | | `site` | `dict[str, Any]` | `{}` | — | | `device` | `dict[str, Any]` | `{}` | — | | `network` | `dict[str, Any]` | `{}` | — | | `access` | `Optional[DeviceAccessTag]` | `None` | — | ## IoTDevice | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `device_id` | `Optional[str]` | `None` | — | | `device_name` | `Optional[str]` | `None` | — | | `status` | `Optional[str]` | `None` | — | | `tags` | `DeviceTag` | `DeviceTag()` | — | ## IoTModule | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `module_id` | `Optional[str]` | `None` | — | | `module_name` | `Optional[str]` | `None` | — | | `status` | `Optional[str]` | `None` | — | | `version` | `Optional[str]` | `None` | — | ## RawResponse A frozen dataclass returned by raw request, download, and upload methods. All fields are required at construction. | Field | Type | Meaning | | --- | --- | --- | | `status_code` | `int` | HTTP status. Failed HTTP requests raise an SDK error before returning this result. | | `body` | `bytes` | Unmodified response body. | | `headers` | `Mapping[str, str]` | Response headers. | | `content_type` | `str` | Content-Type header, or an empty string. | ## MultipartFile A frozen dataclass representing a file to upload. `filename: str` and `content: bytes` are required; `content_type: Optional[str]` defaults to `None`. `from_text(filename, content, *, content_type=None, encoding="utf-8")` returns a file with encoded byte content. When no content type is given, multipart requests infer one from the filename or use `application/octet-stream`. ## AccessTokenInfo A frozen dataclass containing a credential result. All fields are required at construction. | Field | Type | Meaning | | --- | --- | --- | | `token` | `str` | Bearer token; treat it as a credential. | | `expires_on` | `Optional[int]` | Expiry in Unix seconds, or `None`. | | `source` | `str` | Credential source label. | | `claims` | `Mapping[str, Any]` | Token claim metadata; its presence alone does not establish server authorization. | ## CodeFlowDefinition A frozen dataclass containing metadata for a decorated entrypoint: required `input_schema: Optional[dict[str, Any]]` and `output_schema: Optional[dict[str, Any]]`, plus `name: Optional[str] = None`. The decorator supplies omitted schemas as `None`. [CodeFlow entrypoints](/python-sdk/api-reference.md#codeflow-entrypoints) describes `CodeFlowContext`, `CodeFlowTools`, and metadata helpers. ## HostedAppPermissions | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `table_read` | `list[str]` | `[]` | — | | `table_write` | `list[str]` | `[]` | — | | `lakehouse_read` | `bool` | `False` | — | | `project_permissions` | `list[str]` | `[]` | — | ## HostedAppDeployment | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `creation_operation_id` | `str` | `Required` | — | | `readiness_stage` | `str` | `Required` | — | | `status` | `str` | `Required` | — | | `url` | `Optional[str]` | `None` | — | ## HostedAppPublication | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `app_id` | `str` | `Required` | — | | `title` | `str` | `Required` | — | | `release` | `str` | `Required` | — | | `published` | `bool` | `Required` | — | | `url` | `str` | `Required` | — | | `permissions` | `HostedAppPermissions` | `HostedAppPermissions()` | — | ## LakehouseStatementParameter | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `name` | `str` | `Required` | — | | `value` | `Optional[str]` | `None` | — | | `type` | `Optional[str]` | `None` | — | ## LakehouseStatementStatus | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `state` | `str` | `Required` | — | | `error` | `Optional[dict[str, Any]]` | `None` | — | ## LakehouseStatementResult | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `data_array` | `Optional[list[list[Any]]]` | `None` | — | | `next_chunk_index` | `Optional[int]` | `None` | — | ## LakehouseStatement | Python field | Type | Default | JSON alias | | --- | --- | --- | --- | | `statement_id` | `str` | `Required` | — | | `status` | `LakehouseStatementStatus` | `Required` | — | | `manifest` | `Optional[dict[str, Any]]` | `None` | — | | `result` | `Optional[LakehouseStatementResult]` | `None` | — | ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /developers/agent-skills.md # Use agent skills for developer workflows Find task guidance and examples for a coding agent working with ThinkPlatform. ThinkPlatform's developer skills give an external coding agent task-specific instructions, command references, and templates. They are separate from [project skills](/guides/agents/project-skills.md), which you upload and attach to ThinkPlatform Agents. ## Get started Install and authenticate the CLI, then select a project with [Agent setup](/cli/guides/agent-setup.md). In the terminal where the agent runs, a person can prepare a saved profile: ```bash tp profile setup tp context show ``` Ask the agent to read the skill guidance for its task and confirm the context before operating on project resources. Documentation and locally installed skills do not authenticate the agent or grant access. ## Try a read-only database task Ask the agent to find a table, inspect its columns, and return a small sample. With the saved profile selected, these commands provide a complete starting point: ```bash tp context show tp db tables list tp db tables get --table-id table-example tp db rows query --table-id table-example --body '{"filters":[],"sort":[],"page":1,"page_size":5}' ``` Replace `table-example` with an ID returned by the list. Check the columns before interpreting the rows; the query returns values under each row's `data`. See [Inspect a shared database table](/cli/guides/database-tables.md) for result shape and further examples. ## Find references and templates Use the [app development commands](/agent-skills/thinkplatform-app-development/references/commands.md) for source/image publication, Canvas application pages and request-bound data access. Browse the Agent skills section for the relevant task. For example, [data engineering commands](/agent-skills/thinkplatform-data-engineering/references/commands.md) cover data discovery and transformation; [agent operations commands](/agent-skills/thinkplatform-agent-ops/references/commands.md) cover agents and tasks. Commands containing placeholders or `@input.json` require your own values and files. Inspect the target resource's schema or tool definition and the relevant command guidance before constructing input; do not assume a placeholder file exists. Report templates, such as the [agent cost report](/agent-skills/thinkplatform-agent-cost-analysis/assets/agent-cost-analysis-report.md), are blank structures for organizing findings. Fill them with evidence from your own analysis; their empty fields are not example results. For discovery and installation options, see [Agent setup](/cli/guides/agent-setup.md). ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /agent-skills/thinkplatform-app-development/references/commands.md # App development commands Publish container apps, connect a Canvas application page, and use request-bound SDK access. These examples assume an authenticated active saved profile with the intended organization and project. Confirm it with `tp context show` before running commands. Add root `--json` before the command when machine parsing needs JSON output; use root `--profile ` only to override the active profile. ## CLI context and preparation Use the installed `tp --help` and `tp apps publish --help` when checking version support. Select the intended profile, organization and project through the usual global CLI options; do not copy credentials into the source tree. Examples below assume that context is already selected. The current publication API requires a companion HTML Dynamic UI in the same project. Create or select it with `tp dynamic-ui` or `client.canvas.dynamic_ui`. It is an access/resource anchor; the container provides the actual app UI: ```python ui = client.canvas.dynamic_ui.create({ "renderer": "html", "title": "My app", "owner": {"scope": "project"}, "html": "My app", }) ``` Use the returned `uiId` as `--ui-id`. Inspect the returned mapping rather than guessing an ID. Provision needed Tables with `tp db tables create --body @table.json` or reuse a suitable existing Table. Do not change existing column contracts to fit an unrelated demo. ## Publish source or an existing image ```sh tp apps publish my-app --name "My app" --source ./my-app \ --ui-id "$UI_ID" --request-id "$REQUEST_UUID" --wait 300 \ --table-read "$TABLE_ID" --table-write "$TABLE_ID" tp apps show my-app tp apps list ``` Generate a UUID once for a new publication; retain it before submitting. A wait limit or temporary transport error does not establish that a build failed. Resume with the same source, options and `--request-id`; inspect the recorded state before creating another request. `--wait 0` advances one step without polling. Do not automatically resubmit an operation explicitly reported as terminally failed. For a prebuilt image replace `--source` with `--image registry.example/projects/p4/apps/my-app@sha256:` using the actual organization Registry address. `tp registry push` returns an immutable digest when pushing from a Docker-capable environment. Source publication combines remote build, push and deployment; an Agent Workspace does not need Docker-in-Docker. The compressed context is limited to 50 MiB. The CLI archive does not interpret `.dockerignore`: in Git it includes tracked files and nonignored untracked files, subject to built-in exclusions for common credential/cache paths. Use `.gitignore` for local-only files and inspect tracked files separately. Outside Git, stage a dedicated source directory containing only intended build inputs. Keep `.dockerignore` for Docker's own context handling. Build the production frontend in a Docker stage rather than uploading `node_modules`. Include a wheel only when needed by the app; do not embed package-feed passwords in the Dockerfile. Optional SDK permissions: - Repeat `--table-read` / `--table-write` for exact Table IDs. - `--lakehouse-read` allows the delegated read-only statement API for the project. - Repeat `--project-permission` for supported Canvas, Flow or Module read scopes; inspect CLI help for the current accepted values. For updates, inspect `tp apps show my-app`, then publish using a new request UUID and `--replaces "$OLD_RELEASE"`. Use `--replaces-stopped` only if that exact release is stopped. `--replace-current` is a convenience for the initial submission; retain the resolved previous release for retries. Stop an exact release with: ```sh tp apps stop my-app --release "$RELEASE" ``` ## Canvas application page Use the existing configured SDK client to create a dedicated app page: ```python page = client.canvas.pages.create({ "title": "My app", "layout": {"surface": "application", "contentWidth": "full"}, "application": {"source": {"kind": "hosted-app", "appId": "my-app"}}, "blocks": [], }) ``` Use the returned page ID in `/canvas/` on the selected TP host. For an existing HTML-only app the source is `{"kind": "dynamic-ui", "uiId": ""}`. A dashboard/document embedding instead uses a widget of kind `hosted-app` with `config: {"appId": "my-app"}`. Dedicated application pages have no widget frames or document blocks. ## Backend Python SDK Install the released ThinkPlatform client available in the target environment. The private `ThinkPlatform` package also includes the SDK. Keep imports independent of Agent/Flow runtime modules. ```python from fastapi import FastAPI, Request from starlette.concurrency import run_in_threadpool from thinkplatform.sdk import client_from_hosted_request app = FastAPI() @app.get("/api/items") async def items(request: Request): def read(): with client_from_hosted_request(request.headers) as tp: return tp.db.rows.query(TABLE_ID, {"page_size": 100}) return await run_in_threadpool(read) ``` `TABLE_ID` is app configuration and must match the declared permissions. The headers include a short-lived invocation handle and bound org/project; retain neither headers nor client in global state or background jobs. The SDK routes via the platform-injected broker. The application receives no TP user access token. Use `tp.db.rows.create(TABLE_ID, values)` and `tp.db.rows.update(TABLE_ID, row_id, values)` for writes, following the installed method signatures. For a project Lakehouse read: ```python with client_from_hosted_request(request.headers) as tp: statement = tp.lakehouse.statements.execute("SELECT 1 AS example", wait_timeout="0s") current = tp.lakehouse.statements.get(statement.statement_id) ``` Poll within the current authenticated request or make another authenticated app request; use the returned statement ID and inspect its status. SQL result values follow the native API's representation, which may contain numeric strings. Read-only Lakehouse permission does not allow SQL writes, and SDK method existence does not imply that the delegated transport admits that operation. ## Verify the delivered app Verify publication readiness, launch through TP, the requested app action, and persisted readback after reload. For data apps include a denied operation outside the declared resource scope when a suitable test exists. Report separately any untested multi-user or revocation scenario; one successful operator request does not prove the user's app invocation path. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /agent-skills/thinkplatform-data-engineering/references/commands.md # Data engineering commands Inspect, transform, and validate data across the Data Lake, shared database, and Lakehouse. These examples assume an authenticated active saved profile with the intended organization and project. Confirm it with `tp context show` before running commands. Add root `--json` before the command when machine parsing needs JSON output; use root `--profile ` only to override the active profile. ## Check context and available resources ```bash tp auth whoami tp context show tp datalake tree --path data/ tp datalake list --path data/ tp db tables list tp mlops data datastores ``` ## Data Lake ```bash tp datalake preview --path raw/source.csv tp datalake preview --path raw/source.csv --output /tmp/source.csv tp datalake resolve-uri --path raw/source.csv tp datalake upload-file --local-path ./clean.csv --remote-path processed/clean.csv --dry-run tp datalake upload-file --local-path ./clean.csv --remote-path processed/clean.csv tp datalake upload-dir --local-dir ./outputs --remote-prefix processed/run-001 --dry-run tp datalake move --source-path staging/a.csv --destination-path archive/a.csv --dry-run tp datalake delete --path staging/old.csv --dry-run ``` ## Shared DB ```bash tp db tables list tp db tables get --table-id tp db tables create --body @table.json --dry-run tp db tables create --body @table.json tp db rows query --table-id --body '{"filters":[],"sort":[],"page":1,"page_size":5}' tp db rows create --table-id --body @row.json --dry-run tp db rows create-many --table-id --body @rows.json --dry-run tp db import apply --file ./import.xlsx --dry-run tp db import apply --file ./import.xlsx ``` ## Lakehouse and Databricks Default to `tp lakehouse` for Databricks/Lakehouse work. These commands call ThinkPlatform's project-scoped Databricks APIs and work in managed Agent Workspaces without requiring direct Databricks CLI auth. Inventory and context: ```bash tp lakehouse status tp lakehouse catalog show tp lakehouse schemas list tp lakehouse tables list --schema bronze tp lakehouse tables get bronze.example_table tp lakehouse compute list tp lakehouse workspace ls ``` SQL validation and project-scoped writes: ```bash tp lakehouse tables get bronze.example tp lakehouse sql preview --query "SELECT key, event_time FROM ${TP_DATABRICKS_CATALOG}.bronze.example WHERE event_date >= DATE '2026-01-01' LIMIT 100" tp lakehouse sql preview --file ./query.sql tp lakehouse sql preview --file ./query.sql --fresh tp lakehouse sql execute --statement "CREATE SCHEMA IF NOT EXISTS ${TP_DATABRICKS_CATALOG}.silver" --dry-run tp lakehouse schemas create silver --comment "Cleaned and conformed data" --dry-run ``` Preview uses the shared ThinkPlatform cache by default. Use `--fresh` only after a write when a new Databricks execution is required. In a managed ThinkPlatform Agent, call the corresponding SQL preview MCP system tool with `fresh=false` by default and `fresh=true` only for that explicit read-after-write case. Canvas dashboard handoff: ```bash tp canvas dashboard scaffold \ --title "Gold Metrics Dashboard" \ --dataset-id gold_metrics \ --query @gold_metrics.sql \ --filter dateRange:period:event_date \ --dry-run tp canvas dashboard schema gold_metrics --definition @page.json tp canvas dashboard query gold_metrics --definition @page.json --filters @filters.json --limit 100 tp canvas dashboard lint --definition @page.json ``` Use this handoff when a dashboard needs global filters across multiple widgets. The dataset query should include named SQL parameters that match each binding target, for example `:event_date_start` and `:event_date_end` for a `dateRange` binding with target `event_date`. Notebook and job workflows: ```bash tp lakehouse notebooks upsert "${TP_DATABRICKS_PROJECT_ROOT}/demo" --file ./demo.py --dry-run tp lakehouse notebooks upsert "${TP_DATABRICKS_PROJECT_ROOT}/demo" --file ./demo.py tp lakehouse notebooks run "${TP_DATABRICKS_PROJECT_ROOT}/demo" --compute serverless --wait tp lakehouse jobs list tp lakehouse jobs upsert-notebook --name daily-demo --notebook-path "${TP_DATABRICKS_PROJECT_ROOT}/demo" --compute serverless --dry-run tp lakehouse jobs upsert-notebook --name daily-demo --notebook-path "${TP_DATABRICKS_PROJECT_ROOT}/demo" --compute serverless tp lakehouse jobs run --wait tp lakehouse runs list --job-id tp lakehouse runs get tp lakehouse runs output --mode compact ``` Use `tp lakehouse runs list --job-id` with project-tagged jobs created or managed by `tp lakehouse jobs ...`. For a one-time `tp lakehouse notebooks run --wait`, inspect the returned run id directly with `tp lakehouse runs get ` and `tp lakehouse runs output ` instead of listing by the transient internal job id. Use direct `databricks ...` commands only when CLI auth is explicitly configured in the environment. This can be useful for local agents such as Codex, admin inspection, or temporary troubleshooting. Managed Agent Workspaces should still prefer `tp lakehouse`. ```bash databricks current-user me databricks catalogs list databricks schemas list "$TP_DATABRICKS_CATALOG" databricks tables list "$TP_DATABRICKS_CATALOG" bronze databricks workspace list "$TP_DATABRICKS_PROJECT_ROOT" databricks jobs list ``` If direct Databricks CLI auth fails but `tp lakehouse status` works, continue with `tp lakehouse`; do not switch to PATs or secrets unless the user explicitly approves that auth model. ## CLI and MCP execution routes | Intent | Local Agent / Codex | ThinkPlatform Agent | |---|---|---| | Metadata | `tp lakehouse tables get/list` | Databricks catalog/table MCP system tools | | Preview | `tp lakehouse sql preview` | SQL preview system tool, `fresh=false` | | Notebook | `tp lakehouse notebooks run --compute ...` | Notebook run system tool, `compute_mode=...` | | Job | `tp lakehouse jobs upsert-* --compute ...` | Job upsert system tool, `compute_mode=...` | | Cost check | `tp lakehouse costs overview` | `databricks_get_cost_overview` | If a managed Agent lacks the corresponding system tool, report the capability gap. Do not use shell credentials to bypass it. SQL conventions: ```sql CREATE SCHEMA IF NOT EXISTS ${project_catalog}.bronze; CREATE SCHEMA IF NOT EXISTS ${project_catalog}.silver; CREATE SCHEMA IF NOT EXISTS ${project_catalog}.gold; SELECT count(*) AS row_count FROM ${project_catalog}.gold.daily_kpi; SELECT * FROM ${project_catalog}.gold.daily_kpi LIMIT 20; SELECT table_name FROM ${project_catalog}.information_schema.tables WHERE table_schema = 'gold'; ``` Always qualify table references with the project catalog. This includes `information_schema`: use `${project_catalog}.information_schema.tables`, not unqualified `information_schema.tables`, so ThinkPlatform's project-catalog guard can validate the query. ## Prepare data for MLOps ```bash tp mlops data register --name --version --base-path --dry-run tp mlops data list tp mlops data versions ``` ## Verification checklist - Confirm source path/table and output path/table. - Show schema and row counts. - Show a limited sample. - Record data-quality caveats. - Confirm downstream query, import, dashboard, or model training can read the asset. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /agent-skills/thinkplatform-mlops/references/commands.md # MLOps commands Manage datasets, training bundles, jobs, models, and inference deployments. These examples assume an authenticated active saved profile with the intended organization and project. Confirm it with `tp context show` before running commands. Add root `--json` before the command when machine parsing needs JSON output; use root `--profile ` only to override the active profile. ## Check context and available resources ```bash tp auth whoami tp context show tp mlops data list tp mlops models list tp mlops jobs list tp mlops computes list tp mlops environments list tp mlops cloud list ``` ## Data assets ```bash tp mlops data datastores tp mlops data next-version tp mlops data upload-dir --name --version v001 --local-dir ./dataset --datastore datalake --upload-mode sas --dry-run tp mlops data upload-dir --name --version v001 --local-dir ./dataset --datastore datalake --upload-mode sas tp mlops data register --name --version --base-path --dry-run tp mlops data versions tp mlops data files ``` Use a short logical name for new datasets. The API may return an org/project-prefixed `assetName`; use that returned name for `versions`, `files`, and training commands. ## Bundles ```bash tp mlops bundles validate \ --dir ./bundle \ --dataset-name \ --dataset-version \ --environment-name tp-bundle-cpu-general \ --compute-name cpu-batch-cluster \ --local-smoke \ --local-dataset-dir ./dataset tp mlops bundles upload --dir ./bundle --version v001 --dry-run tp mlops bundles upload --dir ./bundle --version v001 tp mlops bundles submit \ --bundle-name \ --bundle-version v001 \ --model-name \ --dataset-name \ --dataset-version \ --environment-name tp-bundle-cpu-general \ --compute-name cpu-batch-cluster \ --parameters '{"max_train_rows":5000}' \ --timeout-seconds 180 ``` Bundle basics: - Include entrypoint/training code, dependency metadata, and output contract expected by ThinkPlatform. - `training-bundle.yaml` must include `schema_version`, `name`, and `entry.command`. - Declare a `dataset_contract` with required files when the bundle expects a dataset organized as a directory. - Write metrics and model outputs where ThinkPlatform registration can find them. - Always write scalar evaluation metrics to `TP_ARTIFACTS_OUTPUT_DIR/metrics.json`. - Use MLflow metric logging in training code when available so `tp mlops jobs metrics ` and the run UI can return scalar metrics. - Validate locally before starting a cloud job when possible. Recommended training code pattern: ```python import json import os from pathlib import Path metrics = { "rows": float(len(test_rows)), "mae": mae, "rmse": rmse, "baseline_mae": baseline_mae, "business_lift": business_lift, } artifacts_dir = Path(os.environ.get("TP_ARTIFACTS_OUTPUT_DIR", "outputs/artifacts")) artifacts_dir.mkdir(parents=True, exist_ok=True) (artifacts_dir / "metrics.json").write_text(json.dumps(metrics, indent=2), encoding="utf-8") try: import mlflow mlflow.log_metrics({key: float(value) for key, value in metrics.items()}) except Exception as exc: print(f"warning: failed to log mlflow metrics: {exc}") ``` Metric completion check: ```bash tp mlops jobs wait --timeout-seconds 900 tp mlops jobs metrics ``` If `jobs metrics` returns `{}` or the UI says no metrics are available, update the bundle to log metrics and rerun training. A `Completed` job without metrics is not a complete model validation. ## Training ```bash tp mlops train submit \ --model-name \ --architecture-name \ --dataset-name \ --dataset-version \ --dry-run tp mlops train submit \ --model-name \ --architecture-name \ --dataset-name \ --dataset-version tp mlops jobs wait --timeout-seconds 600 tp mlops jobs get tp mlops jobs metrics tp mlops jobs logs ``` After every training job, capture at least the primary metric, baseline metric, business metric, and row count from `tp mlops jobs metrics ` in the user-facing report. ## Models ```bash tp mlops models list tp mlops models versions tp mlops models validate-online --model-name --model-version --payload-file ./sample.json tp mlops models upload-dir --name --version v001 --local-dir ./model-package --model-type custom_model --upload-mode sas --dry-run tp mlops models upload-dir --name --local-dir ./model-package --model-type triton_model --dry-run ``` Model artifact upload and model registry promotion are separate operational checks. If `upload-dir` uploads files but registration fails, inspect the uploaded Data Lake path and retry `tp mlops models register --name --version --base-path --model-type ` to isolate the registration failure. ## Cloud deployment and inference ```bash tp mlops cloud create-online --logical-name --model-name --model-version --instance-type --dry-run tp mlops cloud create-online --logical-name --model-name --model-version --instance-type tp mlops cloud wait --endpoint-name --timeout-seconds 1800 tp mlops cloud get --endpoint-name tp mlops cloud invoke-online --endpoint-name --triton-model-name --payload-file ./sample.json tp mlops cloud update-online --endpoint-name --logical-name --model-name --model-version --dry-run tp mlops cloud set-online-traffic --endpoint-name --deployment-name --traffic 100 --dry-run ``` ## Verification checklist - Data asset exists and is readable. - Training job completed and `tp mlops jobs metrics ` returns non-empty metrics. - Metrics include a primary task metric, baseline comparison, business metric, and data volume. - Model version exists and passes deployability checks. - Endpoint/deployment state is healthy. - Inference sample returns expected schema and plausible output. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /agent-skills/thinkplatform-agent-ops/references/commands.md # Agent commands Manage agents, teams, tasks, workspaces, memories, and skills. These examples assume an authenticated active saved profile with the intended organization and project. Confirm it with `tp context show` before running commands. Add root `--json` before the command when machine parsing needs JSON output; use root `--profile ` only to override the active profile. ## Check context and discover resources ```bash tp auth whoami tp context show tp agents list tp agents models tp agents system-tools tp skills list tp modules list ``` ## Agent records ```bash tp agents create --body @agent.json --dry-run tp agents create --body @agent.json tp agents update --body @agent_patch.json --dry-run tp agents update --body @agent_patch.json tp agents delete --dry-run ``` Use `update` to change selected fields, such as the model, prompt, enabled tools, skills, knowledge stores, or workspace settings. Check the current API schema for accepted fields: ```bash tp api operations --tag Agents tp api show ``` ## Teams ```bash tp agents teams list tp agents teams create --body @team.json --dry-run tp agents teams create --body @team.json tp agents teams update --body @team_patch.json --dry-run tp agents teams update --body @team_patch.json ``` ## Tasks and execution ```bash tp tasks list tp tasks create --title "Review project results" --agent-id --dry-run tp tasks create --title "Review project results" --agent-id tp tasks get tp tasks status tp tasks messages tp tasks post-message --prompt "Continue with the approved plan." tp tasks prepare-runtime --agent-id tp tasks goal get tp tasks goal create --objective "Complete the approved task and verify its results." tp tasks goal pause tp tasks goal resume ``` ## Workspaces and uploads ```bash tp agents workspaces list tp agents workspaces get tp agents issue-workspace-upload --files @upload.json ``` ## Memories ```bash tp agents memories search --q "deployment lessons" tp agents memories export tp agents memories create --body @memory.json tp agents memories update --body @memory_patch.json tp agents memories delete ``` ## Skills ```bash tp skills list tp skills get tp skills upload --dir ./skills/ --dry-run tp skills upload --dir ./skills/ tp skills download --output /tmp/skill.zip tp skills delete --dry-run ``` ## Verification checklist - Read back Agent/team after updates. - Confirm expected model, tools, skills, and knowledge sources. - Prepare or run a small validation task when behavior changed. - Inspect messages/status and report any missing capability. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /agent-skills/thinkplatform-automation-ops/references/commands.md # Automation commands Manage schedules, hooks, webhooks, and agent follow-up tasks. These examples assume an authenticated active saved profile with the intended organization and project. Confirm it with `tp context show` before running commands. Add root `--json` before the command when machine parsing needs JSON output; use root `--profile ` only to override the active profile. Use these command patterns before falling back to `tp api` or `tp raw`. ## Check context and available resources ```bash tp auth whoami tp context show tp automation schedules list tp automation hooks list tp automation webhooks list tp hooks list tp webhooks list tp tasks list tp agents list tp flows list ``` ## Scheduled automations Discover exact options first when creating because schedule payload fields may evolve: ```bash tp help automation schedules tp help automation schedules create tp automation schedules list ``` Use dry-run when available: ```bash tp automation schedules create --body @schedule.json --dry-run tp automation schedules create --body @schedule.json tp automation schedules update --body @schedule.json --dry-run tp automation schedules update --body @schedule.json tp automation schedules status stop tp automation schedules log --device-id tp automation schedules agent-log ``` ## Inbound hooks ```bash tp automation hooks list tp automation hooks create --body @hook.json --dry-run tp automation hooks create --body @hook.json tp automation hooks deliveries tp automation hooks invoke --body @payload.json tp automation hooks rotate-secret --dry-run ``` ## Outbound webhooks ```bash tp automation webhooks event-types tp automation webhooks list tp automation webhooks create --body @webhook.json --dry-run tp automation webhooks create --body @webhook.json tp automation webhooks test --body @event.json tp automation webhooks deliveries tp automation webhooks retry-delivery ``` ## Agent follow-ups and tasks ```bash tp tasks create --title "Review project results" --agent-id --dry-run tp tasks create --title "Review project results" --agent-id tp tasks followups tp tasks followups-bulk --task-ids "," tp tasks cancel-followup tp tasks status tp tasks messages ``` ## Verification checklist - Read back the created resource by ID. - Confirm trigger, target, auth context, and output location. - Run a dry-run, test event, or controlled manual invocation. - Inspect delivery/run/task status after the test. - Report the next expected execution time or event condition. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /agent-skills/thinkplatform-business-workflows/references/commands.md # Business workflow commands Build workflows with database tables, files, flows, and user interfaces. These examples assume an authenticated active saved profile with the intended organization and project. Confirm it with `tp context show` before running commands. Add root `--json` before the command when machine parsing needs JSON output; use root `--profile ` only to override the active profile. ## Check context and available resources ```bash tp auth whoami tp context show tp db tables list tp datalake tree --path data/ tp flows list tp home pages list tp dynamic-ui list ``` ## Shared database state ```bash tp db tables create --body @table.json --dry-run tp db tables create --body @table.json tp db rows create --table-id --body @row.json --dry-run tp db rows update --table-id --row-id --body @patch.json --dry-run tp db rows query --table-id --body '{"filters":[],"sort":[],"page":1,"page_size":5}' ``` ## Files and Data Lake ```bash tp datalake upload-file --local-path ./input.csv --remote-path workflows/demo/input.csv --dry-run tp datalake preview --path workflows/demo/input.csv tp datalake upload-dir --local-dir ./outputs --remote-prefix workflows/demo/outputs --dry-run tp datalake list --path workflows/demo/ ``` ## Flows and actions ```bash tp flows create --name "Example flow" --body @flow.json --dry-run tp flows create --name "Example flow" --body @flow.json tp flows save --data @flow-data.json --dry-run tp flows run --input @input.json tp modules invoke --tool --input @payload.json ``` ## Canvas or Dynamic UI ```bash tp home pages apply --spec @workflow-page.json --create-if-missing --dry-run tp home pages apply --spec @workflow-page.json --create-if-missing tp dynamic-ui create --body @workflow-ui.json --dry-run tp dynamic-ui create-html --html-file ./workflow.html --title "Workflow Panel" --dry-run ``` ## Smoke test checklist - Create or upload a sample input. - Run the action through Flow/Module/Agent path. - Confirm DB row state changed as expected. - Confirm output file/report exists. - Confirm Canvas/Dynamic UI shows action and output. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /agent-skills/thinkplatform-canvas-interface/references/commands.md # Canvas commands Create and update pages, build dashboards, and embed interactive interfaces. These examples assume an authenticated active saved profile with the intended organization and project. Confirm it with `tp context show` before running commands. Add root `--json` before the command when machine parsing needs JSON output; use root `--profile ` only to override the active profile. ## Check context and available resources ```bash tp auth whoami tp context show tp home pages list tp canvas pages list tp dynamic-ui list tp db tables list tp flows list ``` ## Home and Canvas pages Prefer idempotent apply by title for repeatable page creation: ```bash tp home pages apply --spec @page.json --create-if-missing --dry-run tp home pages apply --spec @page.json --create-if-missing tp home pages get tp home pages get --markdown ``` Use this path for recurring agent-created reports so reruns update the same titled page instead of creating duplicate pages. Use direct `canvas pages create` only for one-off pages, experiments, or exact REST payload checks. Canvas renders the page `title` as the visible page heading. Do not duplicate that title as the first body H1. For document pages, begin body content with an introductory paragraph or a second-level section heading. For example, use: ```json { "title": "Operations Review", "surface": "document", "contentWidth": "default", "blocks": [ { "type": "markdown", "content": "This page summarizes the latest run.\n\n## Current status\n\n- Waiting for first run." } ] } ``` Do not use: ```json { "title": "Operations Review", "surface": "document", "blocks": [ { "type": "markdown", "content": "# Operations Review\n\nThis page summarizes the latest run." } ] } ``` Use direct Canvas create/update when exact REST behavior is needed: ```bash tp canvas pages create --body @page.json --dry-run tp canvas pages create --body @page.json tp canvas pages update --body @page.json --dry-run tp canvas pages update --body @page.json tp canvas pages reorder --page-id --page-id ``` ## Minimal page specification ```json { "title": "Operations Review", "surface": "document", "contentWidth": "default", "blocks": [ { "id": "summary", "type": "markdown", "content": "This page summarizes the latest run.\n\n## Current status\n\n- Waiting for first run." } ] } ``` Use `contentWidth: "wide"` or `"full"` only when the user asks for it or the page needs more horizontal room, such as dense dashboards, large tables, or embedded apps. Dashboard pages commonly use `"full"`: ```json { "title": "Operations Dashboard", "surface": "dashboard", "contentWidth": "full", "dashboardSettings": { "showOnDashboard": true, "tabLabel": "Ops" }, "blocks": [ { "type": "raw", "block": { "id": "ops-summary", "type": "widget", "widgetKind": "markdown", "title": "Summary", "frame": { "x": 0, "y": 0, "w": 6, "h": 4, "minW": 4, "minH": 3 }, "config": { "markdown": "## Current status\n\n- Waiting for first run." } } } ] } ``` ## Dashboard widgets ```json { "widgetKind": "system-summary", "config": { "preset": "overview" } } { "widgetKind": "resource-list", "config": { "source": "agents", "limit": 6 } } { "widgetKind": "notification-list", "config": { "mode": "active", "limit": 8 } } { "widgetKind": "quick-actions", "config": { "actions": ["create-agent", "new-job", "open-data-lake"] } } { "widgetKind": "lakehouse-query", "config": { "query": "SELECT ...", "visualization": "table", "limit": 100, "refreshSeconds": 0 } } ``` Lakehouse-backed analysis dashboards should keep visualizations live with `lakehouse-query` widgets. Common configs: Discover the backend-supported visualization catalog before choosing a config: ```bash tp canvas visualizations list tp canvas visualizations describe bubble ``` Use the explicit field roles below. The backend retains legacy column-order and `yFields` fallbacks for compatibility, but newly generated dashboards should not depend on them. | Visualization | Use | Required roles | Main optional roles/options | |---|---|---|---| | `table` | Detailed records | none | `tooltipFields` | | `stat` | Single current value | `valueField` | `yFields` | | `kpi` | Value versus comparison/target | `valueField` | `comparisonField`, `targetField` | | `line` | Trend over an ordered axis | `xField`, `yFields` | `seriesField` | | `bar` | Category comparison | `xField`, `yFields` | `seriesField` | | `area` | Trend and magnitude | `xField`, `yFields` | `seriesField` | | `pie` | Part-to-whole composition | `xField`, `yFields` | `seriesField` | | `combo` | Measures with separate scales | `xField`, `yFields`, `secondaryYFields` | `seriesField` | | `scatter` | Relationship between two measures | `xField`, `valueField` | `seriesField` | | `bubble` | Relationship plus a third magnitude | `xField`, `valueField`, `sizeField` | `seriesField` | | `histogram` | Numeric distribution | `valueField` | `histogramBins` | | `heatmap` | Intensity across two dimensions | `xField`, `seriesField`, `valueField` | `aggregation` | | `pivot` | Cross-tab aggregation | `rowFields`, `columnField`, `valueField` | `aggregation` | | `box` | Distribution and outliers by group | `xField`, `valueField` | none | | `gantt` | Activities across time | `xField`, `startField`, `endField` | `seriesField` | Standard agent procedure: 1. Run `tp canvas visualizations list`. 2. Run `tp canvas visualizations describe ` when details are needed. 3. Inspect the Lakehouse schema and preview the SQL. 4. Create or apply the dashboard JSON using the documented camelCase roles. 5. Run `tp canvas dashboard lint`, `schema`, `query`, and `validate-page`. ```json { "widgetKind": "lakehouse-query", "title": "Total trips", "config": { "query": "SELECT SUM(trip_count) AS trips FROM .gold.daily_trip_metrics", "visualization": "stat", "yFields": ["trips"], "limit": 1, "refreshSeconds": 0 } } ``` ```json { "widgetKind": "lakehouse-query", "title": "Daily trend", "config": { "query": "SELECT pickup_date, trip_count, gross_revenue FROM .gold.daily_trip_metrics ORDER BY pickup_date", "visualization": "line", "xField": "pickup_date", "yFields": ["trip_count", "gross_revenue"], "limit": 100, "refreshSeconds": 0 } } ``` ```json { "widgetKind": "lakehouse-query", "title": "Revenue by segment", "config": { "query": "SELECT segment, gross_revenue FROM .gold.segment_metrics ORDER BY gross_revenue DESC", "visualization": "bar", "xField": "segment", "yFields": ["gross_revenue"], "limit": 20, "refreshSeconds": 0 } } ``` ```json { "widgetKind": "lakehouse-query", "title": "Top records", "config": { "query": "SELECT * FROM .gold.top_records ORDER BY score DESC LIMIT 20", "visualization": "table", "limit": 20, "refreshSeconds": 0 } } ``` Validate Lakehouse SQL before creating a widget: ```bash tp lakehouse catalog show tp lakehouse tables list --schema gold tp lakehouse sql preview --query "SELECT * FROM ${TP_DATABRICKS_CATALOG}.gold.metrics LIMIT 100" ``` Preview is cached by default. Use `--fresh` only to verify a newly written Gold table. During layout changes, reuse the schema and preview result rather than reissuing SQL. For dashboards with global filters, prefer `dashboardDefinition` datasets and bindings. Generate or validate the spec before creating the page: ```bash tp canvas dashboard scaffold \ --title "Operations Metrics" \ --dataset-id daily_metrics \ --query @daily_metrics.sql \ --filter dateRange:period:event_date \ --dry-run tp canvas dashboard lint --definition @page.json tp canvas dashboard schema daily_metrics --definition @page.json tp canvas dashboard query daily_metrics --definition @page.json --filters @filters.json --limit 100 tp canvas pages create --body @page.json --dry-run tp canvas pages create --body @page.json tp canvas dashboard validate-page ``` Minimal filtered Lakehouse dashboard pattern: ```json { "title": "Operations Metrics", "surface": "dashboard", "contentWidth": "full", "dashboardDefinition": { "version": 1, "datasets": [ { "id": "daily_metrics", "name": "Daily metrics", "source": "lakehouse", "query": "SELECT event_date, SUM(value) AS value FROM .gold.metrics WHERE event_date >= :event_date_start AND event_date <= :event_date_end GROUP BY event_date ORDER BY event_date", "limit": 100, "parameters": [], "columns": [] } ], "filters": [ { "id": "period", "label": "Period", "type": "dateRange", "defaultValue": { "start": "2026-01-01", "end": "2026-01-31" }, "options": [] } ], "bindings": [ { "datasetId": "daily_metrics", "filterId": "period", "mode": "parameter", "target": "event_date", "operator": "between" } ] }, "blocks": [ { "id": "daily-line", "type": "widget", "widgetKind": "lakehouse-query", "title": "Daily metrics", "frame": { "x": 0, "y": 0, "w": 12, "h": 6, "minW": 6, "minH": 4 }, "config": { "datasetId": "daily_metrics", "visualization": "line", "xField": "event_date", "yFields": ["value"], "limit": 100, "refreshSeconds": 0 } } ] } ``` For project-scope validation, fully qualify tables with the project catalog. This also applies to metadata queries such as `${TP_DATABRICKS_CATALOG}.information_schema.tables`; unqualified `information_schema.tables` can be rejected by the project catalog guard. If the current local agent environment has working Databricks CLI auth, direct Databricks commands are acceptable for inspection or troubleshooting, but keep Canvas widget validation anchored to `tp lakehouse` so the query is checked through ThinkPlatform's project-scoped API: ```bash databricks current-user me databricks tables list "$TP_DATABRICKS_CATALOG" gold ``` ## Cost-aware execution routes - Local Agent/Codex: use `tp canvas ...` and `tp lakehouse ...`; keep preview cached. - ThinkPlatform Agent: use Canvas MCP tools and the Databricks SQL preview system tool with `fresh=false`. - Set `refreshSeconds: 0`. Use 900 seconds or longer only when the user explicitly requires automatic refresh. - Prefer one dashboard dataset for widgets sharing source SQL or filters. Use a precomputed Gold table when the same expensive aggregation is viewed frequently. - Run `lint`, `schema`, and a bounded query while authoring; run `validate-page` once after the full page is ready. ## Dynamic UI ```bash tp dynamic-ui create --body @ui.json --dry-run tp dynamic-ui create --body @ui.json tp dynamic-ui create-html --html-file ./app.html --title "Operator Panel" --dry-run tp dynamic-ui get tp dynamic-ui update --body @patch.json --dry-run tp dynamic-ui delete --dry-run ``` Embed a persisted Dynamic UI in Canvas with a `dynamic-ui` widget and the created `uiId`. ## Verification checklist - Read back the page/app by ID. - Confirm `layout.surface`, block count, widget kinds, and resource references. - For Mermaid or Dynamic UI, browser-check rendering when available. - For action surfaces, verify the action target exists and is discoverable. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /agent-skills/thinkplatform-edge-ops/references/commands.md # Edge commands Provision devices, inspect modules and twins, and manage deployments. These examples assume an authenticated active saved profile with the intended organization and project. Confirm it with `tp context show` before running commands. Add root `--json` before the command when machine parsing needs JSON output; use root `--profile ` only to override the active profile. ## Check context and available resources ```bash tp auth whoami tp context show tp device list tp device deployments list-device --device-id tp device acr repositories ``` ## Device provisioning and setup ```bash tp device create --device-id --dry-run tp device create --device-id tp device setup download --download-id --output ./setup.zip tp device tags get --device-id tp device tags update --device-id --body @tags.json --dry-run ``` ## Inspect modules and run actions ```bash tp device modules --device-id tp device modules-status --device-id tp device module restart --device-id --module-id --dry-run tp device module restart --device-id --module-id tp device module call --device-id --module-id --method-name --payload @payload.json ``` ## Twin operations Always read before patching: ```bash tp device twin get --device-id --module-id tp device twin update --device-id --module-id --body @twin-patch.json --dry-run tp device twin update --device-id --module-id --body @twin-patch.json ``` ## Deployments ```bash tp device deployments list-device --device-id tp device deployments get --deployment-id tp device deployments create --body @deployment.json --dry-run tp device deployments create --body @deployment.json tp device deployments list-device --device-id tp device deployments default-config ``` ## ACR and model rollout ```bash tp device acr repositories tp device acr tags --repository tp mlops deploy get --device-id tp mlops deploy set --device-id --model-name --model-version --deploy-format --dry-run tp mlops deploy set --device-id --model-name --model-version --deploy-format ``` ## Verification checklist - Confirm target device IDs or tag query result before mutation. - Read current modules and twin before changes. - Read deployment status after changes. - Confirm reported module status converges. - Report rollback target and unresolved warnings. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /agent-skills/thinkplatform-integrations-and-flows/references/commands.md # Integration and flow commands Discover modules, configure flows, and connect event-driven integrations. These examples assume an authenticated active saved profile with the intended organization and project. Confirm it with `tp context show` before running commands. Add root `--json` before the command when machine parsing needs JSON output; use root `--profile ` only to override the active profile. ## Check context and discover resources ```bash tp auth whoami tp context show tp modules list tp flows list tp hooks list tp webhooks list tp api operations ``` ## Modules ```bash tp modules list tp modules get tp modules invoke --tool --input @payload.json ``` Python SDK pattern for multi-step logic: ```python from thinkplatform.sdk import client_from_env tp = client_from_env() result = tp.modules.invoke( "", "", input_data={"query": "status"}, ).result print(result) ``` ## Flows ```bash tp flows create --name "Example flow" --body @flow.json --dry-run tp flows create --name "Example flow" --body @flow.json tp flows save --data @flow-data.json --dry-run tp flows save --data @flow-data.json tp flows run --input @input.json ``` Use Code Flow for arbitrary Python backend logic and graph Flow for inspectable orchestration. ## API fallback Discover before calling raw routes: ```bash tp api operations --tag "" tp api show tp api call --body @payload.json tp rest GET /api/... tp rest POST /api/... --body @payload.json tp raw get /api/... tp raw post /api/... --body @payload.json ``` ## Event integration ```bash tp automation hooks create --body @hook.json --dry-run tp automation hooks invoke --body @sample-event.json tp automation hooks deliveries tp automation webhooks event-types tp automation webhooks create --body @webhook.json --dry-run tp automation webhooks test --body @event.json tp automation webhooks deliveries ``` ## Verification checklist - Read schemas/tool definitions before payload creation. - Check that sample inputs and outputs match the expected structure. - Run one controlled invocation. - Inspect Flow run, hook delivery, webhook delivery, or Module result. - Record exact payload file and resource IDs for repeatability. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /agent-skills/thinkplatform-lakehouse-ai/references/commands.md # Lakehouse AI commands Discover AI functions, run SQL, validate notebooks, and save recurring work as jobs. These examples assume an authenticated active saved profile with the intended organization and project. Confirm it with `tp context show` before running commands. Add root `--json` before the command when machine parsing needs JSON output; use root `--profile ` only to override the active profile. ## Discover functions ```bash tp lakehouse ai-functions list --surface python_notebook tp lakehouse ai-functions describe ai_summarize tp lakehouse ai-functions describe ai_query --no-probe-workspace ``` The list is the managed Registry. `describe` normally overlays target-workspace availability from `DESCRIBE FUNCTION EXTENDED` without running inference. ## Inspect source data ```bash tp lakehouse catalog show tp lakehouse tables get silver.reviews tp lakehouse tables preview silver.reviews --limit 10 tp datalake list --path project/raw/reviews tp datalake preview --path project/raw/reviews/reviews.jsonl tp datalake resolve-uri --path project/raw/reviews ``` `project/raw/...` is a ThinkPlatform logical path, not a Unity Catalog Volume path. Use the URI returned by `datalake resolve-uri` as the notebook or Job `input_path`; do not construct `/Volumes//project/...` or an ABFSS URI yourself. ## Run and monitor a SQL statement ```bash tp lakehouse statements execute \ --statement "SELECT ai_summarize(:text) AS summary" \ --parameter "text=A short representative review" \ --parameter-type "text=STRING" \ --wait-timeout 0s \ --on-wait-timeout CONTINUE tp lakehouse statements get tp lakehouse statements result-chunk 1 tp lakehouse statements cancel ``` For advanced options, provide a JSON request in the format accepted by Databricks: ```bash tp lakehouse statements execute --body @request.json --dry-run ``` ## Import and validate notebooks ```bash tp lakehouse notebooks upsert notebooks/ai/review_enrichment \ --file review_enrichment.sql \ --language SQL tp lakehouse notebooks run notebooks/ai/review_enrichment \ --compute serverless \ --environment-version \ --dependency 'pydantic==2.12.5' \ --param sample_limit=10 \ --wait ``` Omit environment options to inherit the notebook/workspace default. Never combine `--serverless` and `--cluster-id`. ## Save production work as a job ```bash tp lakehouse jobs upsert-notebook \ --name review-ai-enrichment \ --notebook-path notebooks/ai/review_enrichment \ --compute serverless \ --environment-version \ --param sample_limit=0 \ --dry-run tp lakehouse jobs run --wait tp lakehouse runs output --mode compact ``` One-time Serverless runs are for validation. Use a saved Job for repeatable or production processing. `--wait` resolves the latest retry attempt automatically when a run has repeated entries for one task key. For a genuine multi-task Job, inspect the parent with `tp lakehouse runs get `, then request each task run's output explicitly. SQL notebook compact output may contain only run metadata. Use an independent `tp lakehouse statements execute` query against the materialized project-catalog table for row-level acceptance checks. A raw-only `read_files` Statement can be rejected by the project-catalog guard; perform raw inspection in the bounded notebook and keep the independent Statement focused on the resulting project table. Use no more than 10 representative rows for the default validation. Materialize the AI expression once, then perform all acceptance queries against that output. Keep preview caching enabled; add `--fresh` only for the first read after the materialization commit. ## CLI and MCP execution routes | Intent | Local Agent / Codex | ThinkPlatform Agent | |---|---|---| | Discover function | `tp lakehouse ai-functions list/describe` | AI Function registry MCP system tools | | Preview | `tp lakehouse sql preview` | SQL preview system tool, `fresh=false` | | Validation run | `tp lakehouse notebooks run --compute serverless` | Notebook run system tool, `compute_mode=serverless` | | Saved run | `tp lakehouse jobs upsert-* --compute serverless` | Job upsert system tool, `compute_mode=serverless` | | Cost evidence | `tp lakehouse costs overview` | `databricks_get_cost_overview` | If Serverless is unsupported, use `job-cluster`/`job_cluster` with the organization policy. Use existing compute only with explicit approval and an explicit cluster ID. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /agent-skills/thinkplatform-lakehouse-ai/references/patterns.md # SQL and notebook patterns Apply AI functions to project data with SQL queries and notebook examples. Replace catalog, schema, table, endpoint, and version placeholders after discovery. Prefer task-specific functions over `ai_query`. ## SQL ```sql SELECT review_id, ai_summarize(review_text) AS summary, ai_analyze_sentiment(review_text) AS sentiment FROM .silver.reviews LIMIT 10; ``` Pin structured task-specific outputs: ```sql SELECT document_id, ai_extract( text, '{"invoice_id":{"type":"string"},"total":{"type":"number"}}', map('version', '2.1', 'enableConfidenceScores', 'true') ) AS invoice FROM .silver.documents LIMIT 10; ``` In the validated workspace, `ai_extract` expects a top-level field map, not a complete JSON Schema document with `type`, `properties`, or `additionalProperties` around it. Materialize the VARIANT once, then cast it into the business schema separately: ```sql CREATE TABLE IF NOT EXISTS .silver.invoice_extract_stage_ USING DELTA AS SELECT source_path, ai_extract(text, '{"invoice_id":{"type":"string"},"total":{"type":"number"}}', map('version', '2.1', 'instructions', 'Extract explicit values only; use null when absent.')) AS extracted FROM .silver.invoice_text_; SELECT source_path, named_struct( 'invoice_id', try_cast(extracted:response:invoice_id:value AS STRING), 'total', try_cast(extracted:response:total:value AS DECIMAL(18,2)) ) AS record, nullif(try_cast(extracted:error_message AS STRING), '') AS extraction_error FROM .silver.invoice_extract_stage_; ``` Version 2.1 returns a VARIANT envelope whose field values live under `response..value`; nested arrays retain the same value envelope. Inspect the representative output before writing casts. JSON `null` inside VARIANT is not SQL `NULL`; use `is_variant_null(value)` when distinguishing the two. For `ai_classify`, pass short canonical label values. Each label must stay within the workspace limit of 50 characters. Put the policy and label descriptions in `content` or supported instructions, not inside long label strings: ```sql SELECT ai_classify( concat('Apply this routing policy: ', policy, '\nMessage: ', message), array('billing', 'access', 'software', 'equipment', 'document_request') ) AS queue FROM .silver.support_messages; ``` Use row-level error capture and structured output for `ai_query`: ```sql SELECT id, ai_query( 'endpoint-name', concat('Extract the issue and urgency: ', text), responseFormat => 'STRUCT', failOnError => false ) AS inference FROM .silver.tickets LIMIT 10; ``` ## SQL notebook source ```sql -- Databricks notebook source CREATE OR REPLACE TEMP VIEW validation_sample AS SELECT * FROM .silver.reviews LIMIT ${sample_limit}; -- COMMAND ---------- SELECT review_id, ai_summarize(review_text) AS summary FROM validation_sample; ``` ## Python notebook source ```python # Databricks notebook source sample_limit = int(dbutils.widgets.get("sample_limit") or "10") source = spark.table(".silver.reviews").limit(sample_limit) enriched = source.selectExpr( "review_id", "ai_summarize(review_text) AS summary", "ai_analyze_sentiment(review_text) AS sentiment", ) display(enriched) ``` For `ai_query` in PySpark, keep the SQL expression explicit so named arguments remain visible: ```python enriched = source.selectExpr( "id", "ai_query('endpoint-name', text, failOnError => false) AS inference", ) ``` ## Raw files and mixed document formats Resolve the ThinkPlatform logical directory before generating notebook code: ```bash tp datalake resolve-uri \ --path project/raw/ai-functions-validation/2026-08-01/example ``` Pass the returned URI through an `input_path` notebook/Job parameter. Do not derive a `/Volumes/...` path from the project catalog: the Datalake container and Unity Catalog schema layout are independent. Preview a representative file and select the reader from its record semantics. JSONL is row-oriented even when stored in one file: ```sql SELECT id, text, _metadata.file_path AS source_path FROM read_files('', format => 'json', multiLine => false); ``` Using `binaryFile` for JSONL produces one binary row per file, not one row per JSON record. Use directory reads and metadata columns instead of enumerating filenames; reserve `binaryFile` for whole binary documents: ```sql SELECT _metadata.file_path AS source_path, _metadata.file_name AS source_name, content FROM read_files('', format => 'binaryFile'); ``` Route by extension/content type before calling a document function: - `ai_parse_document` v2.0 was live-validated with PDF, DOCX, and PNG. - HTML was rejected with `Unsupported file format: html`; decode it as UTF-8 and retain DOM/heading/table boundaries in a compatible envelope or deterministic chunks. - Do not send plain text or HTML through a binary document parser merely because the directory is mixed. - A non-NULL parse result can still contain `error_status`; count both NULL and internal-error outputs. - `ai_prep_search` is beta. A successful `DESCRIBE` does not guarantee runtime success. If the representative run returns an internal platform error, stop retrying and deterministically chunk parsed title/section/text/table elements while retaining page/bbox/source metadata. ## Fact-preserving text transforms `ai_summarize` is appropriate for ordinary summaries, but a representative run can omit operational facts. For strict handover text, define the required fact classes (identifiers, numbers, units, times, states, actions, safety statements, and follow-up owners), inspect every bounded validation output, and reject summaries that add outcomes or causal claims absent from the source. If a task-specific result cannot satisfy that contract, use a constrained generation function and keep the same independent fact gate in production. Masking functions can also hide approved non-personal identifiers. When a business identifier must survive masking, replace only an explicit allowlisted value with a collision-resistant placeholder before the AI expression, restore it deterministically afterward, and verify both sensitive-value absence and allowlisted-value presence. Translation functions can be technically correct while using terminology that is too general for the operating domain. Keep the raw translation immutable, apply only an explicit reviewed terminology map in a downstream stage, and inspect every bounded validation pair for identifiers, equipment terms, negation, and temporal qualifiers. `ai_analyze_sentiment` can return `mixed` in addition to `positive`, `negative`, and `neutral`. When the consumer requires three labels, define the normalization policy before production (for example, map `mixed` to `neutral`) and retain or audit the native label so the policy is visible. `ai_similarity` returns a score, not a universal duplicate decision. Calibrate the threshold with labeled positive and negative pairs, record it as a Job parameter, require margin between classes, and periodically re-evaluate it. Live validation showed small score variation between representative and production calls, so avoid thresholds that sit close to observed examples. ## Serverless materialization and retry safety AI expressions can be reevaluated by every DataFrame action. Materialize each expensive step exactly once, then run counts, transformations, and quality checks against Delta: ```sql CREATE TABLE IF NOT EXISTS .silver.enrichment_stage_ USING DELTA AS SELECT id, ai_summarize(text) AS summary FROM .silver.source; CREATE TABLE IF NOT EXISTS .silver.enrichment_result_ USING DELTA AS SELECT id, summary, current_timestamp() AS processed_at FROM .silver.enrichment_stage_; ``` Use a new run suffix rather than overwriting an existing table. `CREATE TABLE IF NOT EXISTS` makes a retry reuse an already completed stage after an unrelated notebook failure. Avoid `.write.mode("errorifexists").saveAsTable(...)`; the live Serverless environment rejects that mode. ## Quality gates Validate from an independent SQL Statement after the Job succeeds: - raw inputs, output rows, and distinct source IDs agree; - required values, internal error fields, invalid labels, duplicates, and empty outputs are counted; - structured values cast to the intended DATE/DECIMAL/ARRAY/STRUCT types; - identifiers, dates, numbers, units, and source/page locations are retained; - fields that were not explicit in the source remain NULL; instructions alone can still permit arithmetic or date inference, so use a deterministic source-evidence gate for strict extraction; - representative original/output pairs are inspected for semantic drift. Task-specific text transforms are model operations, not deterministic linters. For strict grammar-only requirements, `ai_fix_grammar` still needs a semantic-preservation gate; a successful run alone is not acceptance. ## Explicit Unity Catalog SQL wrapper Create only when the user wants a stable shared abstraction. Keep it inside the project catalog and use `LANGUAGE SQL`: ```sql CREATE OR REPLACE FUNCTION .ai.summarize_review(text STRING) RETURNS STRING LANGUAGE SQL RETURN ai_summarize(text); ``` ThinkPlatform deliberately rejects Python, JAR, external, permission-changing, and DROP FUNCTION statements through the project SQL policy. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /agent-skills/thinkplatform-agent-cost-analysis/references/commands.md # Agent cost commands Inspect agent usage, task configuration, schedules, and cost attribution. These examples assume an authenticated active saved profile with the intended organization and project. Confirm it with `tp context show` before running commands. Add root `--json` before the command when machine parsing needs JSON output; use root `--profile ` only to override the active profile. Run commands using the active saved profile: ```bash tp --help ``` When `tp` is not on `PATH`, run from `thinkplatform-lib` with `.venv/bin/tp` or pass `--tp-bin /absolute/path/to/.venv/bin/tp` to the collector. The collector auto-detects the repository `.venv/bin/tp`. All commands in this reference are read-only. ## Context and profile ```bash tp profile list tp profile show PROFILE tp context show ``` Confirm that `org_id` and `project_id` match the requested scope. Do not silently switch the active profile. ## Cost and attribution Use explicit dates: ```bash tp costs overview \ --from YYYY-MM-DD --to YYYY-MM-DD tp costs allocation \ --from YYYY-MM-DD --to YYYY-MM-DD --group-by project tp costs allocation \ --from YYYY-MM-DD --to YYYY-MM-DD --group-by project_model tp costs allocation \ --from YYYY-MM-DD --to YYYY-MM-DD --group-by project_agent tp costs allocation \ --from YYYY-MM-DD --to YYYY-MM-DD --group-by project_task tp costs allocation \ --from YYYY-MM-DD --to YYYY-MM-DD --group-by project_user tp costs budgets ``` Useful options: - `--provider openai|azure_openai|azure|all` - `--metric ActualCost|AmortizedCost` - `--force-refresh` when stale cached provider data would materially affect the result - `--exclude-unallocated` only for a focused view; retain unallocated cost in the reconciliation ### Fallback for older CLI installations ```bash tp raw get \ /api/organizations/ORG_ID/costs/allocation \ --query from=YYYY-MM-DD \ --query to=YYYY-MM-DD \ --query groupBy=project_model ``` The server must also support the requested grouping. If it does not, record the missing dimension as a limitation and use tasks, Agents, and provider breakdowns as secondary evidence. ## Agent and task configuration ```bash tp agents list --limit 200 --include-tools tp agents teams list tp agents models tp skills list --limit 200 tp skills get SKILL_ID tp tasks list \ --activity-from FROM_ISO --activity-to TO_ISO --limit 200 --offset 0 tp tasks list \ --thread-id THREAD_ID --activity-from FROM_ISO --activity-to TO_ISO tp tasks get TASK_ID tp tasks messages TASK_ID --summary ``` Only retrieve raw task messages after selecting an anomalous task: ```bash tp tasks messages TASK_ID ``` Do not paste raw message content into the report. Report sizes, repetition, tool names, and short paraphrases. ## Schedules and triggers ```bash tp automation schedules list tp automation schedules agent-log APP_ID \ --from FROM_ISO --to TO_ISO --limit 500 --summary tp hooks list tp webhooks list tp tasks followups TASK_ID --include-inactive ``` Inspect: - interval/trigger and enabled status; - target Agent and schedule prompt; - run count, status mix, attempts, repeated task IDs, and errors; - overlapping schedules, Hooks, Webhooks, and task follow-ups that can trigger the same work. ## Data-context investigation After message summaries indicate file-heavy tool use, inspect only the implicated paths: ```bash tp datalake tree --path REMOTE_PATH tp datalake list --path REMOTE_PATH tp datalake preview --path REMOTE_FILE ``` Look for repeated reads of large or numerous files, raw PDFs/images requiring conversion, and missing curated indexes or summaries. Do not enumerate the entire Data Lake without evidence that it is required. ## Snapshot collector ```bash tp-agent-cost-snapshot --help ``` The default top-task and schedule summaries are bounded. Increase limits deliberately when the initial ranking shows a long tail that matters. Read `collection_warnings`, `derived.dimension_coverage`, and `derived.collection_coverage` before conclusions. Scheduler `status_counts` describe enqueue records, not downstream task outcomes; correlate them with task status. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /agent-skills/thinkplatform-agent-cost-analysis/references/cost-model.md # Agent cost model Calculate agent costs from provider pricing, token usage, and billing data. ## Evidence hierarchy Use evidence in this order: 1. Provider-billed (actual) costs for financial totals. 2. ThinkPlatform allocated provider actuals for project, user, Agent, task, and model attribution. 3. Runtime measured `estimatedCost` for diagnostic detail. 4. Token/request/duration proxies when direct cost is unavailable. Provider actuals and runtime estimates can differ because of reporting delays, currency conversion, discounts, service tiers, rounding, cached-token treatment, tool charges, credits, or incomplete attribution. Reconcile the differences rather than combining the figures. ## General formula For each provider, model, service tier, and context tier: ```text request cost = uncached input tokens × uncached input rate + cached input tokens × cached input rate + cache-write tokens × cache-write rate + output tokens × output rate + audio/image tokens × modality rates + built-in tool, storage, retrieval, container, or other service charges ``` Then: ```text period cost = sum(request cost) + fixed/provisioned capacity charges ``` Do not assume all providers expose every component or that cached tokens are separate from total input tokens. Confirm field semantics before subtracting or adding token categories. ## Metrics to calculate - Cost share: `slice actual cost / project actual cost`. - Activity share: `slice requests / project requests`. - Effective cost per request: `slice actual cost / slice requests`. - Effective cost per million input/output tokens: use only when token coverage is adequate and label it as blended. - Cache ratio: `cached input tokens / input tokens` only when input tokens include cached tokens. - Output amplification: `output tokens / input tokens`. - Reasoning share: `reasoning tokens / output tokens` only when the provider documents reasoning as part of output. - Daily execution rate: `requests or tasks / active days`. - Schedule overhead: failed, retried, duplicated, or overlapping executions × representative task cost. - Concentration: cost share of top model, Agent, task, user, and day. Always handle zero denominators and disclose low token coverage. ## Current pricing verification Pricing is time-sensitive. At analysis time, verify the specific provider, model snapshot, region, service tier, and context length using official sources: - OpenAI API pricing: [https://developers.openai.com/api/docs/pricing](https://developers.openai.com/api/docs/pricing) - OpenAI prompt caching: [https://developers.openai.com/api/docs/guides/prompt-caching](https://developers.openai.com/api/docs/guides/prompt-caching) - OpenAI Batch API: [https://developers.openai.com/api/docs/guides/batch](https://developers.openai.com/api/docs/guides/batch) - OpenAI Usage API: [https://platform.openai.com/docs/api-reference/usage](https://platform.openai.com/docs/api-reference/usage) - Azure OpenAI pricing: [https://azure.microsoft.com/pricing/details/cognitive-services/openai-service/](https://azure.microsoft.com/pricing/details/cognitive-services/openai-service/) - Azure OpenAI prompt caching: [https://learn.microsoft.com/azure/ai-services/openai/how-to/prompt-caching](https://learn.microsoft.com/azure/ai-services/openai/how-to/prompt-caching) - Azure provisioned throughput billing: [https://learn.microsoft.com/azure/foundry/openai/concepts/provisioned-throughput-billing](https://learn.microsoft.com/azure/foundry/openai/concepts/provisioned-throughput-billing) Record the URL and access date in the report. Do not copy a price from this skill. ## Pricing distinctions that change conclusions - Input, cached input, cache writes, and output can have different rates. - Long-context tiers can change rates above provider-specific thresholds. - Standard, Batch, Flex, priority/fast, and provisioned capacity have different economics. - Some built-in tools and storage are billed separately from model tokens. - Azure Standard token billing and provisioned throughput unit/hour billing require different utilization analyses. - A cheaper model that increases retries, output, or tool loops can cost more per successful outcome. ## Prompt caching interpretation Caching helps only when requests are eligible and share an exact stable prefix under the provider's rules. Place stable instructions and common context before variable user/task content when platform behavior permits. Do not treat low cache usage as waste when: - requests are below the provider's cache eligibility threshold; - prompts legitimately differ at the beginning; - traffic is too sparse or separated beyond cache lifetime; - the provider/model/tier does not support the expected cache behavior. ## Currency and billing period Keep provider currencies separate unless ThinkPlatform supplies a documented conversion. State the exchange-rate source and date when converting. Align analysis dates with provider reporting timezone and note that very recent days may be incomplete. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /agent-skills/thinkplatform-agent-cost-analysis/references/diagnostic-playbook.md # Diagnose agent costs Identify changes in usage, model pricing, context size, and tool activity that drive agent costs. Work from totals to mechanisms. For each finding, record evidence, size, confidence, and an alternative explanation. ## 1. Validate attribution Check: - provider status and last-updated timestamp; - actual, allocated, measured, and unallocated totals; - token/request coverage; - currency and billing period; - whether the target project is isolated from shared provider usage; - model/Agent/task dimension coverage and collector truncation warnings; - whether scheduler statuses represent enqueue records or final task outcomes. A large unallocated share or stale or missing provider data prevents a confident project-level conclusion. Report this limitation before discussing optimization. If model coverage is low, report `Unknown model` as a measurement gap. Do not assign historical cost using an Agent's current model configuration. ## 2. Find the change point Compare daily cost, requests, and tokens. Align spikes with: - model changes; - schedule creation or interval changes; - prompt/skill deployment; - new data sources or file formats; - retry/error periods; - new Agents, Hooks, or follow-ups. Use equal windows around the change. Normalize by successful business outcome when possible. ## 3. Separate model price from volume For each model calculate cost share, request share, token share, and effective cost per request. Then compare current official rates. Evidence for a model-price driver: - cost share greatly exceeds request/token share; - the high-cost model's active dates align with the spend spike; - similarly sized tasks on a lower-cost model cost materially less. Alternative explanations include longer contexts, more output/reasoning, tool calls, or task complexity concentrated on that model. ## 4. Quantify schedule-required and avoidable volume Inventory every active schedule and triggering path. Derive intended executions from interval/trigger and compare with observed runs/tasks. Split volume into: - required successful executions; - retries after errors; - duplicate or overlapping triggers; - concurrent runs that repeat unfinished work; - abandoned or no-op runs; - follow-up fan-out. If schedule volume is a requirement, report its unavoidable baseline cost. Optimize cost per execution and avoidable overhead instead of recommending removal. ## 5. Diagnose prompt and context cost Use Agent and schedule prompt lengths as a screen, not proof. Use task message summaries to inspect: - input growth over time; - repeated identical human prompts; - largest messages; - tool-result size; - repeated system/context injection; - low cache ratio despite a reusable stable prefix. Common mechanisms: - overly detailed instructions repeated on every request; - multiple skills restating the same rules; - full conversation replay when a state summary would suffice; - entire file sets loaded before the task is narrowed; - variable values placed early and invalidating prompt caching. ## 6. Diagnose tool and data amplification Rank tool-call names in anomalous tasks. Investigate repeated Data Lake/Blob reads, PDF/image extraction, OCR, conversions, searches, and broad directory scans. Ask: - Is the same immutable input processed in many runs? - Is the derived text/index stored and reused? - Can metadata narrow candidate files before reading content? - Are large tool results returned to the model when only IDs/counts are needed? - Does an error cause the Agent to retry the same expensive operation? Treat preprocessing and indexing as recommendations only; do not mutate data in a cost-analysis task. ## 7. Diagnose output, reasoning, and loops High output or reasoning may be appropriate. Look for: - repeated long reports when a delta would work; - Agent handoffs that duplicate context; - evaluator/reviewer loops without a termination condition; - tool-call/result cycles with no state change; - errors that regenerate an entire answer; - model settings mismatched to task difficulty. Use cost per successful outcome rather than cost per request when quality matters. ## 8. Check budget and operational controls Report existing project budget policy, thresholds, current usage, and enforcement state. Absence of a budget is a risk-control gap, not a root cause of past spend. Do not change budgets or configuration during analysis. ## Finding confidence - High: provider actuals reconcile and the driver is visible in multiple independent dimensions. - Medium: allocation and runtime behavior align, but pricing or task detail is incomplete. - Low: based mainly on configuration, token proxy, or a small sample. ## Recommendation priority Prioritize by: ```text expected savings × confidence ÷ implementation and quality risk ``` Separate: - immediate containment; - low-risk efficiency; - architectural context/data improvements; - measurement gaps. For each recommendation specify the mechanism, affected share, validation experiment, quality guardrail, and rollback condition. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /agent-skills/thinkplatform-agent-cost-analysis/assets/agent-cost-analysis-report.md # Agent cost report template Summarize agent usage, cost drivers, and recommendations in a structured report. ## Scope - Profile: - Organization / project: - Analysis period: - Comparison period: - Providers / currency: - Snapshot: - Report generated: ## Executive summary | Rank | Critical factor | Estimated affected share | Confidence | Why it matters | |---:|---|---:|---|---| | 1 | | | | | ## Cost reconciliation | Measure | Amount | Share | Notes | |---|---:|---:|---| | Provider actual | | 100% | | | Allocated to target project | | | | | Runtime measured | | | | | Unallocated | | | | Provider status, timestamps, currency, and coverage limitations: ### Data quality | Check | Result | Analytical impact | |---|---|---| | Model cost/request coverage | | | | Agent/task coverage | | | | Provider freshness | | | | Inventory/log truncation | | | | Raw API fallback | | | ## Trend and change points | Date/window | Cost | Requests/tasks | Tokens | Relevant configuration/event | |---|---:|---:|---:|---| | | | | | | ## Ranked drivers ### Models | Model | Cost/share | Requests/share | Input/cached/output/reasoning | Interpretation | |---|---:|---:|---|---| | | | | | | ### Agents and tasks | Agent/task | Cost/share | Runs/requests | Evidence | Interpretation | |---|---:|---:|---|---| | | | | | | ### Schedules and triggers | Schedule/trigger | Intended volume | Observed volume | Retry/duplicate overhead | Cost implication | |---|---:|---:|---:|---| | | | | | | ### Prompt, context, skills, and data tools | Evidence | Observed behavior | Cost mechanism | Confidence | |---|---|---|---| | | | | | ## Hypothesis assessment | Hypothesis | Result | Quantified evidence | Alternative explanation | |---|---|---|---| | Expensive model mix | | | | | Required schedule volume | | | | | Prompt or skill bloat | | | | | Repeated context/file conversion | | | | | Retry, fan-out, or Agent loop | | | | | Attribution/measurement issue | | | | ## Recommendations No configuration was changed during this analysis. | Priority | Recommendation | Mechanism | Expected impact | Quality guardrail / validation | |---:|---|---|---|---| | 1 | | | | | ## Limitations - ## Reproduction ```bash # Exact read-only tp commands used ``` ## Pricing sources - Provider/model/tier: - Official URL: - Accessed: ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /agent-skills/thinkplatform-lakehouse-cost-analysis/references/commands.md # Lakehouse cost commands Inspect spending and investigate SQL warehouses, jobs, and dashboard refresh costs. These examples assume an authenticated active saved profile with the intended organization and project. Confirm it with `tp context show` before running commands. Add root `--json` before the command when machine parsing needs JSON output; use root `--profile ` only to override the active profile. Use one route consistently. Both routes call the same ThinkPlatform backend and use the same org/project authorization. ## CLI route Run commands using the active saved profile: ```bash tp profile show PROFILE tp lakehouse costs overview \ --from YYYY-MM-DD --to YYYY-MM-DD --scope project tp lakehouse warehouses list tp lakehouse query-history list \ --from FROM_ISO --to TO_ISO --limit 200 tp lakehouse jobs list tp lakehouse runs list --job-id JOB_ID --from ISO_START --to ISO_END --limit 20 ``` Use `--scope organization` only as an org owner. Use `--force-refresh` only when stale provider data would materially affect the conclusion; it is not a routine refresh option. Do not enable query text during broad collection. Run the bounded collector: ```bash tp-lakehouse-cost-snapshot --help ``` ## MCP route Use these ThinkPlatform system tools in a managed Agent: | Intent | MCP system tool | CLI equivalent | |---|---|---| | Financial and usage overview | `databricks_get_cost_overview` | `tp lakehouse costs overview` | | Warehouse state/config | `databricks_list_warehouses` | `tp lakehouse warehouses list` | | Recent execution causes | `databricks_list_query_history` | `tp lakehouse query-history list` | | Job definitions | `databricks_list_jobs` | `tp lakehouse jobs list` | | Period-bounded Job runs | `databricks_list_job_runs` with `start_time_from`/`start_time_to` | `tp lakehouse runs list --from ... --to ...` | | SQL preview | Databricks SQL preview system tool with `fresh=false` | `tp lakehouse sql preview` | | Notebook run | Databricks notebook run system tool with `compute_mode` | `tp lakehouse notebooks run --compute ...` | | Job upsert | Databricks Job upsert system tool with `compute_mode` | `tp lakehouse jobs upsert-* --compute ...` | Pass explicit cost/query dates and scope, and bound Job runs with `start_time_from`/`start_time_to`. Keep `include_query_text=false`. If a tool is missing, report that capability gap; do not bypass project boundaries with ad-hoc credentials. ## Cost-aware operation examples ```bash tp lakehouse sql preview \ --query "SELECT key, metric FROM ${TP_DATABRICKS_CATALOG}.gold.metrics LIMIT 100" tp lakehouse sql preview --file check.sql --fresh tp lakehouse notebooks run notebooks/daily \ --compute serverless --wait tp lakehouse jobs upsert-notebook \ --name daily --notebook-path notebooks/daily --compute serverless --dry-run ``` Preview uses the shared cache by default. Use `--fresh` only for an explicit new read. Prefer `serverless`; use `job-cluster` for unsupported workloads and `existing-cluster` only with an explicit cluster ID and authorization. ## Targeted follow-up - Filter Query History by `warehouse_id` and status before increasing the limit. - Inspect runs only for ranked project Jobs; do not enumerate unrelated workspace Jobs. - Use SQL hash, duration, cache status, bytes/rows read, and status in reports. Retrieve raw SQL only when an org owner explicitly authorizes it and the diagnosis cannot proceed otherwise. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /agent-skills/thinkplatform-lakehouse-cost-analysis/references/cost-model.md # Lakehouse cost model Reconcile billing and usage data, calculate cost metrics, and avoid double counting. ## Source order 1. Azure workspace plus managed resource group ActualCost for financial totals. 2. Databricks `system.billing` usage for DBU, SKU, billing-origin product, and workload attribution. 3. Billing custom tags and Job/resource tags for project allocation; ThinkPlatform Query Tags, Query History, and run metadata for recent cause attribution. 4. Duration, scan bytes, rows, and run counts as diagnostic proxies when direct allocation is unavailable. Do not sum ActualCost and DBU list-price cost. List price is a diagnostic reference, not an additional charge. ## Reconciliation Keep these buckets separate: - `exact`: billing usage directly tagged or uniquely mapped to a project/workload. Do not present a proportional share of financial ActualCost as exact. - `estimated`: project ActualCost allocated by that project's `system.billing` custom-tagged list cost divided by total list cost for the same period. - `unallocated`: cost that cannot be mapped safely. Report backend allocation coverage as custom-tagged list cost divided by total list cost for the same billing period, with currency and source timestamps. Never force coverage to 100% by spreading unallocated cost. Managed-resource-group resources can include compute, networking, storage, and related services. Attribute them only when resource tags or a documented mapping support the link. ## Useful metrics - Daily cost and seven-day moving average. - DBU and ActualCost by SKU, billing-origin product, workload, Warehouse, and Job. - Warehouse active minutes, idle tail after the last query, starts, and queries per active minute. - Query count, distinct SQL hashes, cache-hit ratio, failure ratio, p95 duration, and scan bytes. - Job attempted/successful runs, retries, success rate, p95 duration, and cost per successful run. - Cost per successful output row only when output counts are reliable. Handle zero denominators and partial periods explicitly. An unavailable project allocation must be represented as `null`/unknown, not zero. Keep confirmed workload counts and observation coverage together; a zero count with incomplete Job task data is only a lower bound. ## Timing and confidence - Recent Azure ActualCost or `system.billing` rows can be delayed or corrected. Mark incomplete days. - A `system.billing` read can start the configured SQL Warehouse even though it is non-mutating. Prefer cached overviews and avoid concurrent forced refreshes. - Query History is better for current behavior but is not the financial ledger. - Query Tags provide a strong recent shared-Warehouse activity signal, but do not become `system.billing.custom_tags` and therefore do not allocate financial cost by themselves. - A Warehouse tag identifies ownership/configuration, not which project caused every shared query. - Job tags and IDs can support exact allocation only when their lifecycle and project mapping are authoritative. Use `high`, `medium`, or `low` confidence for each finding and explain the limiting evidence. ## Double-count prevention Databricks AI Functions can cause both Lakehouse compute/AI service cost and LLM-like usage. Keep this report scoped to costs returned by Lakehouse/Azure billing sources. Do not merge it into ThinkPlatform Agent/LLM provider totals unless the billing source proves the charges are distinct. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /agent-skills/thinkplatform-lakehouse-cost-analysis/references/diagnostic-playbook.md # Diagnose Lakehouse costs Investigate idle compute, repeated queries, expensive scans, retries, and missing billing coverage. ## Idle SQL Warehouse Compare query timestamps, Warehouse active intervals, auto-stop, and starts. A long gap between the last query and stop suggests idle tail. Confirm that frequent polling is not keeping it alive before recommending a shorter auto-stop. ## Repeated SQL or cache misses Group by SQL hash, principal-safe project tag, and minute. Look for stable repeated statements, multiple browser tabs, overlapping Agents, or retries. Distinguish: - ThinkPlatform response-cache hits, which avoid Databricks execution; - Databricks result-cache hits, which still appear in Query History and can wake compute; - explicit fresh/manual requests, which intentionally bypass the response cache. ## Expensive scans Rank query hashes by DBU proxy, duration, and bytes read. Check partition pruning, bounded dates, selected columns, reused Gold tables, and repeated equivalent aggregates. Recommend materialization only when reuse outweighs its refresh/storage cost. ## Jobs, failures, and retries Calculate attempts per successful run and cost per successful run. Check overlapping schedules, `max_concurrent_runs`, timeout, retry count, skew, dependency failures, and repeated full recomputation. Do not treat a necessary retry policy as waste without failure evidence. ## Compute selection Flag production Jobs on All-Purpose/existing clusters. For compatible workloads compare five representative runs on Serverless and a policy-managed Job Cluster using output equality, success rate, duration, and billed cost. Keep the cheaper valid mode; do not optimize from DBU rate alone. ## Lakehouse AI Verify representative sample size, AI expression count, materialization, error rate, and DBU per successful row. Re-evaluating an AI expression in multiple actions can multiply work; materialize it once before validation and downstream reads. ## Dashboard refresh Group Query History by SQL hash and minute while the page is idle. `refreshSeconds=0` should produce only the initial/manual request; allowed automatic refresh must be at least 900 seconds. Consolidate widgets that share filters or source SQL into one dataset. ## Missing tags or billing coverage List untagged resources and unallocated cost separately. Required tags are `tp_org_id`, `tp_project_id`, `tp_system`, and `workload_type`; SQL also needs request-source Query Tags. Fix observability before asserting project chargeback. ## Recommendation order 1. Stop accidental idle/repeated work. 2. Bound previews, scans, samples, retries, and concurrency. 3. Reuse response cache and materialized results. 4. Right-size Warehouse and Job compute after representative comparison. 5. Improve tags and billing coverage. Estimate savings as a range and state the assumptions. Never promise a target from DBU reduction alone. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /agent-skills/thinkplatform-lakehouse-cost-analysis/assets/lakehouse-cost-analysis-report.md # Lakehouse cost report template Document Lakehouse spending, workload findings, and cost-saving recommendations. ## Executive summary - Financial ActualCost: <currency amount>; comparison: <amount/change>. - Allocation coverage: <exact>, <estimated>, <unallocated>. - Primary driver: <driver, quantified evidence, confidence>. - Immediate low-risk action: <action and expected range>. ## Scope and evidence | Field | Value | |---|---| | Profile / org / project | | | Period / comparison period | | | Azure data updated | | | Databricks usage updated | | | Query History window | | | Missing permissions/data | | ## Financial reconciliation | Component | ActualCost | Currency | Source | Confidence | |---|---:|---|---|---| | Workspace | | | | | | Managed resource group | | | | | | Total | | | | | | Exact project allocation | | | | | | Estimated project allocation | | | | | | Unallocated | | | | | ## Ranked drivers | Rank | SKU / workload / resource | Cost or DBU share | Activity evidence | Confidence | |---:|---|---:|---|---| | 1 | | | | | ## Warehouse and SQL findings | Warehouse / SQL hash | Queries | Cache | Duration / scan | Finding | |---|---:|---|---|---| | | | | | | ## Job findings | Job | Compute | Attempts / success | Duration / cost | Finding | |---|---|---:|---|---| | | | | | | ## Recommendations | Priority | Change | Evidence | Expected effect | Risk / validation | |---:|---|---|---|---| | 1 | | | | | ## Limitations and alternative explanations - <billing delay, missing tags, shared-Warehouse estimation, or incomplete window> - <alternative explanation for each major finding> ## Reproduction ```bash ``` ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /agent-skills/thinkplatform-autonomous-plant-ops/references/commands.md # Plant operations commands Inspect plant resources, review operational state, and plan improvements. These examples assume an authenticated active saved profile with the intended organization and project. Confirm it with `tp context show` before running commands. Add root `--json` before the command when machine parsing needs JSON output; use root `--profile ` only to override the active profile. Use these commands to review the current state across ThinkPlatform domains before choosing a workstream. ## Context ```bash tp auth whoami tp context show tp --output table context orgs tp --output table context projects ``` ## Review operational state ```bash tp home data tp tasks list tp agents list tp agents teams list tp automation schedules list tp hooks list tp webhooks list tp flows list tp modules list tp device list tp device deployments list-device --device-id tp datalake tree --path data/ tp db tables list tp mlops jobs list tp mlops models list tp mlops cloud list tp home pages list ``` ## Inspect specific resources ```bash tp tasks status tp tasks messages tp device modules-status --device-id tp mlops jobs get tp mlops jobs metrics tp canvas pages get tp automation schedules log --device-id ``` ## Track improvement opportunities When producing an autonomous improvement proposal, include: - Evidence: resource IDs, status, metrics, delivery failures, missing outputs, or repeated tasks. - Proposed action: specific skill/workstream and expected platform artifact. - Risk: read-only, reversible write, production write, cost, or external notification. - Verification: command or status used to confirm the result. - Follow-up: whether to automate, dashboard, or create an Agent task. ## Choose safe first actions ```bash tp tasks create --title "Review project results" --agent-id --dry-run tp home pages apply --spec @ops-review.json --create-if-missing --dry-run tp automation schedules create --body @report-only-schedule.json --dry-run ``` Do not perform production mutations from this top-level skill. Route to the domain skill and require approval when the action changes devices, deployments, endpoints, data, or external notifications. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /admin/overview.md # Administration Manage access and understand the boundaries of your ThinkPlatform environment. Administration brings together the people, roles, and resources that support work in an organization and its projects. Your available controls depend on your role and the deployment's configuration. ## Choose the scope Select the intended organization and, for project changes, the intended project. Check the selected names before changing settings: organization membership and project membership are separate. [Organizations and projects](/concepts/organizations-and-projects.md) explains how these scopes relate to sign-in. ## Manage access Use the organization or project settings to inspect members and roles. To give someone project access, first check their organization membership, then add them to the intended project and verify their role in the member list. Follow [Members and permissions](/admin/members-and-permissions.md) for the steps and role boundaries. ## Review security and data When a person or workload cannot access a resource, identify the acting identity and the relevant scope before changing permissions. [Security and authentication](/admin/security-and-authentication.md) explains human sign-in and workspace identity. Before moving or deleting data, use [Data management](/admin/data-management.md) to identify the storage location and dependent work. ## Use developer tools For integrations and automation, start with the [developer overview](/developers/overview.md), [CLI](/cli/get-started/overview.md), and [Python SDK](/python-sdk/overview.md). Confirm the selected context and the result of each operation just as you would in the browser. Use [Costs and budgets](/admin/costs-and-budgets.md) to inspect usage and understand monthly LLM protection before changing a limit. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /admin/members-and-permissions.md # Members and permissions Invite organization members and manage access to projects. Organization membership and project membership are separate. An organization Owner can access its projects, while other organization roles do not automatically grant access to projects the person has not joined. See [Organizations and projects](/concepts/organizations-and-projects.md). You need permission to manage members in the relevant scope. The project member controls are available to project Owners and administrators. Role options and management controls can depend on the organization's configuration. The member and role tabs are part of the people and permissions settings. Depending on the settings view, the section may be titled **People & Permissions**; in **Project settings**, use the **Members** and **Roles** tabs directly. ## Invite someone to an organization 1. Select the organization and open its **Organization** settings, then **Members**. 2. Choose **Invite**, enter the person's **Email address**, and select a **Role**. The invitation form offers Member and, when permitted, Owner. 3. Choose **Invite**. Check the member list for the person and their role. An invitation manages ThinkPlatform membership. It is separate from Microsoft Entra sign-in and does not automatically add a Member to every project. ## Add a project member 1. Select the organization and project, and open **Project settings** and **Members**. 2. Choose **Add member**, select an existing organization member, and choose Owner or Member. 3. Submit the dialog and check the project member list and role displayed for that person. If the person is missing from the selection, first check their organization membership. If the control is unavailable, check your own project role and selected project. ## Change roles or remove a member In the appropriate organization or project **Members** list, use **Roles** beside the member to review or edit their roles. Use the member's actions menu to remove them when access is no longer needed. Confirm the change in the list and ask the person to verify the intended access. The interface prevents editing or removing your own membership through these controls. Changes can be rejected to preserve required ownership or enforce authorization; review the message and involve another authorized owner when needed. The **Roles** settings can include Owner, Member, Reader, and custom permission bundles where configured. Review a role's permissions and scope before assigning it. Preset roles are immutable; custom roles allow a more specific set of permissions. An effective permission can also depend on resource-specific access settings. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /admin/security-and-authentication.md # Security and authentication Understand user sign-in and the separate authority of agents and workspaces. ThinkPlatform uses Microsoft Entra authentication for human sign-in. An eligible tenant user may sign in automatically, but organization and project access still depend on ThinkPlatform membership and roles. ## Resolve a person's access 1. Ask the person to confirm the account, organization, and project selected in the browser. 2. If sign-in fails, check the identity provider's message and involve the organization's identity administrator. If sign-in succeeds but the project is missing, check organization membership and the project role using [Members and permissions](/admin/members-and-permissions.md). 3. After any authorized membership change, have the person reopen the project and verify the specific resource and operation they need. A successful sign-in establishes identity; it does not itself grant access to every project or action. ## Review agent and workspace authority Agent visibility, configured tools, and approval requirements are separate from the person's membership. A workspace can use a managed identity for external services; its grants are distinct from the signed-in person's role. When a workload is denied, identify the actor, selected project, allowed paths, tool restrictions, and underlying resource permissions. Grant only the access required and verify the intended operation at its destination. Workspace creation does not configure secret injection or network policy. Arrange and verify those controls with the deployment administrator. The API rejects writes containing the legacy `secrets` or `internet_access` fields. See [Operate agent workspaces](/guides/operations/workspaces.md). ## Check developer access For programmatic sign-in and configuration, see [SDK authentication](/python-sdk/authentication.md) and the [developer overview](/developers/overview.md). If a request is denied, check the identity and project context used by that request as well as the displayed error; a browser session does not automatically resolve a missing runtime grant. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /admin/data-management.md # Data management Understand where project data lives before moving or deleting it. ThinkPlatform projects can contain application assets and use Data Lake storage. Agent workspace local files are a separate runtime location: treat them as ephemeral unless durable backing has been configured. ## Keep an output For an agent result offered as a downloadable file, you can preserve a copy in the project's Data Lake: 1. In the agent chat, open the result file card and download it to your device. Check that the downloaded file contains the expected output. If no download action is offered, ask the workspace administrator for an approved export method before replacing the workspace. 2. With the CLI installed, authenticated, and set to the intended project, upload that local file to an authorized project path. For example, if the downloaded file is `./result.txt` and `project/uploads/` is permitted, first run the dry run and inspect its destination: ```bash tp datalake upload-file --local-path ./result.txt --remote-path project/uploads/result.txt --dry-run tp datalake upload-file --local-path ./result.txt --remote-path project/uploads/result.txt ``` 3. Follow [Upload and inspect Data Lake files](/cli/guides/files.md) to list and download or preview the destination. Read it back and verify the contents before restarting, replacing, or deleting the workspace. An interrupted upload may have written data; inspect the destination before retrying. This path requires both permission to download the result and permission to write the selected Data Lake folder. ## Review data before deletion Select the intended organization and project and identify the affected resource and its dependencies. Review which people, agents, flows, and applications use it, confirm you have the appropriate permissions, and arrange a recoverable copy where needed. Confirm the target in the deletion dialog and check the result afterward. Deletion can interrupt consumers or remove work they depend on; recovery depends on the storage and retention configuration of your deployment. ## Check Data Lake access Use the project's permitted paths and verify saved files in the intended location. Workspace access to Data Lake paths is controlled separately from a person's project membership. If a file is unavailable, check the project, path, workspace access configuration, and underlying storage permissions with the administrator responsible for that storage. See [Explore files and data assets](/guides/data/files-and-data-assets.md). For access management, see [Members and permissions](/admin/members-and-permissions.md). For programmatic workflows, see the [developer overview](/developers/overview.md), [CLI](/cli/get-started/overview.md), and [Python SDK](/python-sdk/overview.md). ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements. --- Source: /admin/costs-and-budgets.md # Review usage and manage budgets Inspect organization spending and configure monthly AgentOps LLM limits. Open **Settings → Billing** in the intended organization. Organization members can view **Usage**; organization Owners have overview and budget management controls. Price administration is a separate platform-administrator function. Available sections depend on your role and the deployment's cost services. ## Inspect spending Open **Usage**, select the period and available grouping, and inspect the currency, provider and allocation information alongside the total. The overview's month-to-date period uses the current UTC month. A provider's reported cost, a runtime token estimate and a project allocation are different measures; do not add overlapping figures together. Refresh before investigating a new change. Missing, stale or unallocated provider data limits what the totals establish; it is not evidence of zero spend. Review source status before reporting a project total. The [agent cost guidance](/agent-skills/thinkplatform-agent-cost-analysis/references/cost-model.md) and [Lakehouse cost guidance](/agent-skills/thinkplatform-lakehouse-cost-analysis/references/cost-model.md) explain these measures. ## Set a project LLM budget An organization Owner can open **Billing → Budgets**: 1. Choose **New budget**, select the **Project**, and enter the **Monthly LLM budget** and **Currency**. 2. Decide whether to enable **Stop new LLM usage when this budget is reached**. Review the effect with the project's users before changing it. 3. Choose **Save budget**, then check the saved amount, currency and status. Use **Edit budget** beside an existing project to change it. For example, if your team has agreed a monthly test limit of `100` in `USD`, enter those values and verify the saved budget. This is an input example, not a recommended spend limit. With the stop option enabled, an in-flight response may finish and a subsequent model call can be blocked. Without it, usage continues after alerts. This budget covers AgentOps LLM usage; it is not a cap on every cloud charge. Projects without a project budget are shown as unlimited, though an organization-level protection policy can still apply. ## Review organization protection The budget view also has an organization **Enabled** setting, **Monthly limit**, **Currency** and **Save** control. Review the affected projects, save deliberately, and check the resulting policy state. An organization limit and each project allocation need not describe the same amount. If a source is stale or a policy cannot be loaded, inspect the error with the administrator responsible for billing. A client update does not configure provider access or reset an exhausted budget. ## Automation notes - Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management. - Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions. - Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome. - Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements.