Workspace
Shows which Proto account you’re signed in as and what’s connected to it, such as Modal and Hugging Face. Start here if a tool won’t run or a connection looks wrong.
Takes no parameters.
Discover
Lists the tools you can use. By default you only see tools that are ready to run in your workspace.
Pass deployed_only=false to see the whole catalog, including tools you could deploy. Each entry has
a tool_key, a category, a short summary, and what it needs to run.
false for the whole catalog.Finds tools by keyword, matching against tool keys and descriptions. The best matches come first,
with the same details list_tools gives.
false to include tools you could deploy.Inspect
Shows what a tool takes and returns: its input, config, and output schemas. It also tells you whether you can run the tool and whether it has an example. Check this before building an input, because unknown or misnamed fields are rejected.
Returns an example input that’s known to work, or null if the tool doesn’t have one. It makes a
good starting point for your own input. To run the example as is, pass use_example=true to
run_tool.
Tells you where a tool comes from: its description, category, citation and DOI, documentation, source code, and links to the original method. Use it when you write up results or need to cite the tool.
Run
Runs a tool and returns the result. Look at the schema first, and the example if there is one. A run can take a few minutes when a container has to start or a model has to load.
If a run is still going after about 45 seconds, you get back pending and a job_id. The run keeps
going in the background, and get_run_status collects the result when it’s done. If no response
comes back at all, for example because your client timed out, use list_runs to find the job_id
instead of starting the run over. Large outputs come back as stored files or download links, so
they don’t fill up the conversation.
use_example is true.Deploy and collect
Deploys a tool to your Modal workspace so you can run it. Deploying takes a few minutes and costs a build on your Modal account, so your assistant should check with you first. You only need to deploy a tool once. Deploying it again updates it to the latest version.
This call can return before the build finishes. Use get_deploy_status to check on it instead of
starting a second deployment.
Shows how a deployment started through Proto is going. You can call it as often as you like. If it
says tracked: false, there’s no recent deployment to report on. Use list_tools to see whether the
tool is ready.
Lists your recent runs, newest first, whether you started them here, on the website, or from the
SDK. Each entry has a job_id, tool_key, status, created_at, and completed_at. If a result
never arrived, find the run’s job_id here and pass it to get_run_status. That way you don’t run
it again and pay for it twice.
For runs on your own Modal workspace, the status shown is the last one we recorded. It updates when the run is collected. Runs started with a Modal token in the request headers aren’t recorded, so they won’t appear here.
pending, running, completed, failed, or cancelled.Collects the result of a run that came back pending. You can call it as often as you like while
the run is going. Each time you fetch a finished result, you get fresh download links.
job_id from run_tool or list_runs.Fetches a stored output directly, for when a download link won’t open. Text comes back as text, and other files come back as base64. Large files aren’t pasted into the conversation. Use their download links instead.