Version 3
What Projects can do

What Projects can do

See every capability a Project's agent, its Workflows, and its custom views can use, and how each one reaches it.

Audience: builders

You do not need to write code to use these capabilities. You ask the agent in the Project's conversation, and the agent writes the code that calls them. The names in the tables below help you ask for something precisely, and help you read what the agent did.

Three ways to reach the platform

WhoHow it calls the platformWhere it runs
The agentPython code that calls the sdk modules listed on this pageIn the Project's sandbox, during a conversation or a Workflow agent step
A custom viewIts own runtime calls, such as listDecisions()In the browser of the person viewing it, with that person's permissions
Verified logicThe same sdk modules as the agent, inside reviewed and approved codeFrom a Workflow step, a conversation, a custom view, or the Project API

A custom view has its own calls for work items, decisions, files, data reads, and Verified logic. For everything else, including changes to data, a view goes through Verified logic. You ask the agent to write the logic, a reviewer approves it, and a button in the view starts it. This way, every action a view takes beyond its own calls runs reviewed code.

In the tables below, Agent means the agent's code and the code inside Verified logic. View means a custom view's own runtime calls. Where a section has no View calls, a view reaches those capabilities through Verified logic.

Ask a person to decide

A run can stop and wait for a person to choose. The person answers in the conversation, in the work item, or in a custom view.

CallWhat it doesAgentView
sdk.human.ask()Asks a person a question with options, then ends the script so the run waits for the answer.YesNo
sdk.human.ask_many()Asks up to four questions at once in a conversation. A Workflow step asks one at a time.YesNo
sdk.meta.work_items.propose_decision()Proposes an answer to a work item's pending decision for a person to confirm.YesNo
listDecisions()Lists the Project's decisions, pending by default, newest or oldest first.NoYes
getDecision()Reads one decision's question, options, pre-filled values, and answer.NoYes
answerDecision()Answers a decision as the person viewing.NoYes
openDecision()Opens the work item's decision card over the view, to edit values or add a note.NoYes

sdk.human.ask() ends the script: nothing after the call runs. The agent writes anything the next run needs to the Project's files before it asks. A Workflow that must stop for a person every time uses a human.request step instead. See Outcomes.

An answer given in a view is recorded as the person's own. The platform checks it the same way as an answer in the work item, and a decision someone else answered first is not answered again.

Query and change data

These calls work on the data sources attached to the Project, within the access the Project was granted.

CallWhat it doesAgentView
sdk.sql.sources()Lists the data sources, the Project's access, and the tables and columns it may use.YesNo
sdk.sql.describe_source()Reads one source's access grant and catalog.YesNo
sdk.sql.list_databases()Lists the databases an attached connection can reach.YesNo
sdk.sql.read()Reads data with ANSI SQL over the declared columns.YesNo
sdk.sql.execute()Runs SQL within the Project's grants.YesNo
sdk.sql.transaction()Commits 1 to 100 related writes on one source together, or rolls them all back.YesNo
sdk.sql.validate()Checks SQL against the current grants without sending it to the source.YesNo
sdk.semantic_modelsCreates, versions, and binds semantic models, and links Verified logic to them.YesNo
listDataSources()Lists the data sources attached to the Project.NoYes
openDataSource()Opens an attached data source in the app.NoYes
readSql()Reads an attached data source or semantic model with one read-only SQL statement, with the viewer's access. Returns at most 1,000 rows.NoYes

To show query results in a view, call readSql(). To change data from a view, start Verified logic.

Run Workflows and work items

CallWhat it doesAgentView
sdk.meta.workflows.submit_work_item()Submits one work item to a Workflow.YesNo
sdk.meta.workflows.submit_work_items()Submits up to 1,000 work items in one call.YesNo
sdk.meta.workflows.poll_work_items()Reads the progress of up to 1,000 submitted work items.YesNo
sdk.meta.workflows.list_triggers()Lists a Workflow's triggers.YesNo
sdk.meta.workflows.pause_trigger()Pauses a trigger so it stops creating work items. resume_trigger() starts it again.YesNo
sdk.meta.work_items.list()Lists work items across the Project or in one Workflow. get() reads one.YesNo
sdk.meta.work_items.rename()Renames a work item.YesNo
sdk.meta.work_items.archive_many()Archives up to 500 work items. unarchive_many() restores them.YesNo
sdk.meta.work_items.rerun()Starts a new run of a work item on its Workflow's latest version.YesNo
sdk.meta.work_items.set_disposition()Sets how a work item ended, for Workflows that declare outcomes.YesNo
listWorkflows()Lists the Project's Workflows.NoYes
listTriggers()Lists one Workflow's triggers.NoYes
queryWorkItems()Finds work items across every Workflow by status, metadata, outcome, or date.NoYes
listWorkItems()Lists one Workflow's work items.NoYes
getWorkItem()Reads one work item.NoYes
getWorkItemAttachments()Lists a work item's attachments.NoYes
readWorkItemInputs()Reads the inputs that work items were submitted with.NoYes
readWorkItemOutputs()Reads the outputs of several work items in one call.NoYes
requestCreateWorkItem()Opens the form that creates a work item.NoYes
rerunWorkItem()Starts a new run of a work item on its Workflow's latest version.NoYes
archiveWorkItems()Archives 1 to 20 work items, or restores them.NoYes
openWorkItem()Opens a work item in the app.NoYes
startWorkItemConversation()Opens a conversation about a work item.NoYes
getModelUsage()Reads the Project's model usage and estimated cost over a time range.NoYes

Work with files

The agent reads and writes the Project's files directly in its workspace, so it needs no sdk call for ordinary files. See Files.

CallWhat it doesAgentView
sdk.google.docsOpens, creates, reads, and edits Google Docs that are in the Project.YesNo
sdk.google.sheetsOpens, creates, reads, and writes Google Sheets that are in the Project.YesNo
sdk.google.slidesReads a summary of Google Slides that are in the Project, and replaces or updates their text.YesNo
readJson()Reads and parses a JSON file.NoYes
listFiles()Lists files under a folder.NoYes
getFileUrl()Returns a link to a file, for an image or a download.NoYes
downloadFile()Downloads a file to the person's computer.NoYes
renderPdfPage()Shows one page of a PDF as an image.NoYes
openFile()Opens a file in the app's file preview.NoYes

Send email

The agent sends email from a shared mailbox or a hosted address configured for the workspace. See Email templates and Email-bound Workflows.

CallWhat it doesAgentView
sdk.mail.send()Sends a new email.YesNo
sdk.mail.reply()Replies on the email thread that started the run.YesNo
sdk.mail.update_inbound()Marks the email that started the run as read, and adds or removes its categories or labels.YesNo
sdk.mail.read_msg()Reads an Outlook .msg file.YesNo

Send notifications

Notifications go to people in the app, or to Slack or Microsoft Teams when the workspace connects them. See Notifications.

CallWhat it doesAgentView
sdk.notify.send()Sends a notification, with optional rich Slack or Teams content.YesNo
sdk.notify.digest()Sends a compact digest notification.YesNo
sdk.users.me()Addresses the person the run works for. by_email() and by_id() address someone else in the workspace.YesNo
Helperssdk.notify.channel(), action(), and image() add a channel, a link button, or an annotated image.YesNo

Use MCP servers and integrations

CallWhat it doesAgentView
sdk.mcp.list_servers()Lists the MCP servers mounted in the Project.YesNo
sdk.mcp.server()Returns a server, to list and call its tools and read its resources and prompts.YesNo
sdk.meta.mcp.install_catalog_server()Installs a server from the catalog and mounts it.YesNo
sdk.meta.mcp.mount()Mounts an existing workspace server in the Project.YesNo
sdk.meta.mcp.reauthorize()Asks the person to sign in to a server again.YesNo
sdk.meta.integrations.connect()Connects an integration. enable() creates one, sync() refreshes it.YesNo
sdk.meta.projects.attach_integration()Attaches a workspace integration to a Project.YesNo
sdk.meta.integrations.add_slack_conversations()Adds Slack channels to the Slack integration.YesNo

When an MCP server needs the person to sign in, the run asks them and continues after they do.

Use models and web search

CallWhat it doesAgentView
sdk.llm.prompt()Sends one prompt to a model and returns the answer.YesNo
sdk.llm.generate_images()Generates images and saves them to the Project.YesNo
sdk.llm.generate_image_batch()Generates images for up to five prompts at once.YesNo
sdk.exa.search()Searches the web.YesNo
sdk.exa.answer()Answers a question from web results.YesNo
sdk.exa.get_contents()Reads the contents of web pages.YesNo
sdk.exa.create_webset()Builds a webset: a collection of web results that is kept up to date.YesNo

The web search calls need the Exa integration.

Read documents

CallWhat it doesAgentView
sdk.docintel.parse()Parses a document into structured content.YesNo
sdk.docintel.extract()Extracts fields from a document against a schema.YesNo
sdk.docintel.infer_schema()Drafts an extraction schema from a document and a description.YesNo
sdk.docintel.wait_for_result()Waits for a parse or an extraction to finish and returns its result.YesNo

See Document intelligence.

Show results in a conversation

CallWhat it doesAgentView
sdk.context.publish_vega_chart()Shows an interactive chart in the conversation.YesNo
sdk.context.add_image()Adds an image for the agent to look at in its next step. add_vega_chart(), add_matplotlib_figure(), and add_pdf_pages() do the same for charts, figures, and PDF pages.YesNo
sdk.views.preview()Takes a screenshot of a custom view so the agent can check its own work.YesNo
sdk.meta.threads.rename()Renames the current conversation.YesNo
sdk.tasks.list()Lists the Project's background tasks. get() reads one.YesNo
publishSelection()Tells the conversation what the person selected in the view, so the agent can use it as context.NoYes

Run Verified logic

CallWhat it doesAgentView
sdk.verified.list_approved()Lists the approved Verified logic and the inputs each one takes.YesNo
sdk.verified.run()Runs approved Verified logic and returns its result.YesNo
sdk.meta.verified_logic.run()Runs the tests of a Verified logic package.YesNo
listVerifiedLogic()Lists the approved Verified logic.NoYes
startVerifiedLogic()Starts approved Verified logic with its inputs.NoYes
getVerifiedLogicExecution()Reads a run's state, result, and changed files.NoYes

A view checks a run about once a second until it finishes. The view receives the result once; the platform does not save it. Files the logic writes are saved to the Project when the run succeeds.

Build and manage the Project

CallWhat it doesAgentView
sdk.meta.projects.create()Creates a Project. open() opens one.YesNo
sdk.meta.workflows.validate()Checks a Workflow file before it is applied.YesNo
sdk.meta.workflows.model_options()Lists the models a Workflow's agent steps can use.YesNo
sdk.meta.skills.validate()Checks a skill package before it is published.YesNo
sdk.meta.email_templates.validate()Checks an email template.YesNo
sdk.meta.evalsLists evaluation case sets, runs them, and records the results.YesNo
sdk.meta.tenant.list_projects()Lists the Projects the person can see. list_integrations() and list_mcp_servers() do the same for integrations and MCP servers.YesNo
sdk.meta.tenant.resolve_users()Looks up people's names and pictures from their user IDs.YesNo

What only a view does

CallWhat it doesAgentView
getContext()Reads the Project, the person viewing, and what that person may do.NoYes
getViewState()Reads the person's saved state for this view. saveViewState() and clearViewState() change it.NoYes
subscribeEvents()Reacts to events, such as a file changing or a decision card closing.NoYes

See What a view can read and do.

Permissions and limits

  • The viewer's permissions apply. A view can do only what the person viewing it can do.
  • Some view calls need operate access. Answering decisions, starting Verified logic, rerunning work items, and archiving work items need permission to operate the Project.
  • Previews cannot act. A view in a preview cannot answer decisions or start Verified logic.
  • Verified logic must be approved. A view can start only logic that a reviewer has approved.
  • Effects are not undone. When a Verified logic run fails after it sent email or called a tool, those effects stay. Read the run's state before you start it again.

Ask the agent for the details. Each sdk module documents its own arguments. Ask the agent in the Project's conversation how to use a call, and it reads the current documentation from the module.