Skip to main content
A workflow is the right choice when you want TeamCopilot to run a repeatable task as code. In TeamCopilot, workflows are created through the AI Assistant, then refined in the workflow editor.

​
Before you create one

Create a workflow when:
  • the task should run the same way every time
  • you need Python code to execute the task
  • the task needs structured inputs
  • the task interacts with APIs, files, or external systems
If the task mainly needs instructions for the AI, create a skill instead.

​
How to create a workflow

  1. Open TeamCopilot.
  2. Go to the AI Assistant.
  3. Ask the assistant to create a workflow for a specific task.
  4. Be clear about the workflow’s purpose, inputs, and expected output.
  5. After the assistant creates it, open it from the Workflows tab.
  6. Review and edit the generated files.
  7. Declare any required secret keys and configuration.
  8. Have an engineer approve the workflow before running it in production.
From the product UI today, workflows are created by talking to the AI Assistant. Once created, they appear in the Workflows section where you can inspect, edit, approve, and run them.

​
What gets created

Each workflow lives in: 
workflows/<slug>/
A workflow is a small package of files. The core files are: 
workflows/<slug>/
├── workflow.json
├── README.md
├── run.py
├── requirements.txt
├── .venv/
└── requirements.lock.txt
Depending on how the workflow was generated, you may also see extra support files such as .env or .env.example. For secrets, prefer TeamCopilot secret management rather than storing raw values in those files.

​
What each file does

  • workflow.json: defines the workflow contract, including its intent, inputs, and runtime timeout
  • README.md: documents what the workflow does and how it should be used
  • run.py: contains the executable Python logic
  • requirements.txt: lists Python dependencies
  • .venv/: contains the workflow’s isolated Python environment
  • requirements.lock.txt: records the exact installed dependency versions

​
The most important file: workflow.json

workflow.json defines how TeamCopilot understands the workflow. It includes:
  • intent_summary: a human-readable description of the workflow
  • inputs: the parameters the workflow accepts
  • required_secrets: the secret keys TeamCopilot must resolve before the workflow can run
  • triggers.manual: whether it can be run manually
  • runtime.timeout_seconds: how long it can run before timing out
This file powers both the workflow contract and the manual run UI.

​
Writing run.py

run.py should implement one clear task end to end. In practice, that means:
  • parse inputs
  • perform the workflow logic
  • print useful output
  • fail clearly if something goes wrong
Keep the workflow focused. If the script starts doing several unrelated jobs, it is usually time to split it into separate workflows.

​
Adding dependencies and secrets

When a workflow needs external packages:
  • add them to requirements.txt
  • install them into the workflow’s local virtual environment
  • refresh requirements.lock.txt
When a workflow needs credentials:
  • declare the key names in workflow.json under required_secrets
  • have the user add those keys in Profile Secrets, or ask an engineer to provide a Global Secret
  • read the values in run.py from environment variables such as os.environ["STRIPE_SECRET_KEY"]
Example: 
{
  "intent_summary": "Create a Stripe customer",
  "required_secrets": ["STRIPE_SECRET_KEY"]
}

import os

stripe_key = os.environ["STRIPE_SECRET_KEY"]
TeamCopilot blocks runs when a required secret is missing and tells the user which key to add in Profile Secrets. Do not put raw secrets in workflow.json, README.md, chat instructions, or source comments.

​
Reviewing and testing a workflow

Before asking your team to use a workflow:
  • check that the slug and intent still match what it does
  • confirm the inputs are clear and correctly typed
  • verify the timeout is reasonable
  • document required setup in README.md
  • test it with realistic inputs
  • get engineer approval
After approval, users can run the workflow from TeamCopilot, including through the manual run UI for workflows with defined inputs.

​
When to choose a workflow instead of a skill

Choose a workflow when the main value is reliable execution. Examples:
  • syncing data between systems
  • generating a report
  • provisioning a standard resource
  • running an operational remediation step
If the main value is guidance, process, or reasoning, create a skill instead.