|
| 1 | +The Security Lab Taskflow Agent is an MCP enabled multi-Agent framework. |
| 2 | + |
| 3 | +While the [Security Lab Copilot Extensions Framework](https://github.com/github/seclab-copilot-extensions) was created for team-internal prototyping and exploring various Agentic workflow ideas and approaches, the Taskflow Agent is intended as a "production" implementation. |
| 4 | + |
| 5 | +The Taskflow Agent is built on top of the [OpenAI Agents SDK](https://openai.github.io/openai-agents-python/) in contrast to the largely custom backend implementations of our original Copilot extensions framework. |
| 6 | + |
| 7 | +As such the Taskflow Agent provides a more future-proof CLI focused Agent tool as we leverage the SDK for keeping pace with e.g. evolving MCP protocol specifications. |
| 8 | + |
| 9 | +While the Taskflow Agent does not integrate into the dotcom Copilot UX, it does operate using the Copilot API (CAPI) as its backend. |
| 10 | + |
| 11 | +# Core Concepts |
| 12 | + |
| 13 | +The Taskflow Agent leverages a GitHub Workflow-esque YAML based grammar to perform a series of tasks using a set of Agents. |
| 14 | + |
| 15 | +Agents are defined through [personalities](personalities/), that receive a [task](taskflows/) to complete given a set of [tools](toolboxes/). |
| 16 | + |
| 17 | +Agents can cooperate to complete sequences of tasks through so-called [Taskflows](taskflows/GRAMMAR.md). |
| 18 | + |
| 19 | +# Installation |
| 20 | + |
| 21 | +```sh |
| 22 | +python -m venv .venv |
| 23 | +source .venv/bin/activate |
| 24 | +python -m pip install -r requirements.txt |
| 25 | +``` |
| 26 | + |
| 27 | +## System Requirements |
| 28 | + |
| 29 | +Python >= 3.9 |
| 30 | + |
| 31 | +# Usage |
| 32 | + |
| 33 | +Provide a Copilot entitled GitHub PAT via the `COPILOT_TOKEN` environment variable. |
| 34 | + |
| 35 | +Run `python main.py` for help. |
| 36 | + |
| 37 | +Example: deploying a prompt to an Agent Personality: |
| 38 | + |
| 39 | +``` |
| 40 | +python main.py -p assistant 'explain modems to me please' |
| 41 | +``` |
| 42 | + |
| 43 | +Example: deploying a Taskflow: |
| 44 | + |
| 45 | +``` |
| 46 | +python main.py -t example |
| 47 | +``` |
| 48 | + |
| 49 | +## Configuration |
| 50 | + |
| 51 | +Set environment variables via an `.env` file in the project root as required. |
| 52 | + |
| 53 | +# Personalities |
| 54 | + |
| 55 | +Core characteristics for a single Agent. Configured through YAML files in `personalities/`. |
| 56 | + |
| 57 | +These are system prompt level instructions. |
| 58 | + |
| 59 | +Example: |
| 60 | + |
| 61 | +```yaml |
| 62 | +# personalities define the system prompt level directives for this Agent |
| 63 | +personality: | |
| 64 | + You are a simple echo bot. You use echo tools to echo things. |
| 65 | +
|
| 66 | +task: | |
| 67 | + Echo user inputs using the echo tools. |
| 68 | + |
| 69 | +# personality toolboxes map to mcp servers made available to this Agent |
| 70 | +toolboxes: |
| 71 | + - echo |
| 72 | +``` |
| 73 | +
|
| 74 | +# Toolboxes |
| 75 | +
|
| 76 | +MCP servers that provide tools. Configured through YAML files in `toolboxes/`. |
| 77 | + |
| 78 | +Example stdio config: |
| 79 | + |
| 80 | +```yaml |
| 81 | +# stdio mcp server configuration |
| 82 | +server_params: |
| 83 | + kind: stdio |
| 84 | + command: python |
| 85 | + args: |
| 86 | + - toolboxes/echo/echo.py |
| 87 | + env: |
| 88 | + SOME: value |
| 89 | +``` |
| 90 | + |
| 91 | +Example sse config: |
| 92 | + |
| 93 | +```yaml |
| 94 | +server_params: |
| 95 | + kind: sse |
| 96 | + # make sure you .env config the echo server, see echo_sse.py for example |
| 97 | + url: http://127.0.0.1:9000/echo |
| 98 | + headers: |
| 99 | + SomeHeader: "{{ env USER }}" |
| 100 | +``` |
| 101 | + |
| 102 | +# Taskflows |
| 103 | + |
| 104 | +A sequence of interdependent tasks performed by a set of Agents. Configured through a YAML based [grammar](taskflows/GRAMMAR.md) in [taskflows/](taskflows/). |
| 105 | + |
| 106 | +Example: |
| 107 | + |
| 108 | +```yaml |
| 109 | +taskflow: |
| 110 | + - task: |
| 111 | + # taskflows can optionally choose any of the support CAPI models for a task |
| 112 | + model: gpt-4.1 |
| 113 | + # taskflows can optionally limit the max allowed number of Agent task loop |
| 114 | + # iterations to complete a task, this defaults to 50 when not provided |
| 115 | + max_steps: 20 |
| 116 | + must_complete: true |
| 117 | + # taskflows can set a primary (first entry) and handoff (additional entries) agent |
| 118 | + agents: |
| 119 | + - c_auditer |
| 120 | + - fruit_expert |
| 121 | + user_prompt: | |
| 122 | + Store an example vulnerable C program that uses `strcpy` in the |
| 123 | + `vulnerable_c_example` memory key and explain why `strcpy` |
| 124 | + is insecure in the C programming language. Do this before handing off |
| 125 | + to any other agent. |
| 126 | + |
| 127 | + Then provide a summary of a high impact CVE ID that involved a `strcpy` |
| 128 | + based buffer overflow based on your GHSA knowledge as an additional |
| 129 | + example. |
| 130 | + |
| 131 | + Finally, why are apples and oranges healthy to eat? |
| 132 | + |
| 133 | + # taskflows can set temporary environment variables, these support the general |
| 134 | + # "{{ env FROM_EXISTING_ENVIRONMENT }" pattern we use elsewhere as well |
| 135 | + # these environment variables can then be made available to any stdio mcp server |
| 136 | + # through its respective yaml configuration, see memcache.yaml for an example |
| 137 | + # you can use these to override top-level environment variables on a per-task basis |
| 138 | + env: |
| 139 | + MEMCACHE_STATE_DIR: "example_taskflow/" |
| 140 | + MEMCACHE_BACKEND: "dictionary_file" |
| 141 | + # taskflows can optionally override personality toolboxes, in this example |
| 142 | + # kevin normally only has the memcache toolbox, but we extend it here with |
| 143 | + # the GHSA toolbox |
| 144 | + toolboxes: |
| 145 | + - ghsa |
| 146 | + - memcache |
| 147 | + - task: |
| 148 | + must_complete: true |
| 149 | + model: gpt-4.1 |
| 150 | + agents: |
| 151 | + - c_auditer |
| 152 | + user_prompt: | |
| 153 | + Retrieve C code for security review from the `vulnerable_c_example` |
| 154 | + memory key and perform a review. |
| 155 | +
|
| 156 | + Clear the memory cache when you're done. |
| 157 | + env: |
| 158 | + MEMCACHE_STATE_DIR: "example_taskflow/" |
| 159 | + MEMCACHE_BACKEND: "dictionary_file" |
| 160 | + toolboxes: |
| 161 | + - memcache |
| 162 | +``` |
| 163 | +
|
| 164 | +Taskflows support [Agent handoffs](https://openai.github.io/openai-agents-python/handoffs/). Handoffs are useful for implementing triage patterns where the primary Agent can decide to handoff a task to any subsequent Agents in the `Agents` list. |
| 165 | + |
| 166 | +See the [taskflow examples](taskflows/examples) for other useful Taskflow patterns such as repeatable and asynchronous templated prompts. |
| 167 | + |
| 168 | +# Docker based deployments |
| 169 | + |
| 170 | +You can find a Docker image for the Seclab Taskflow Agent [here](https://github.com/GitHubSecurityLab/seclab-taskflow-agent/pkgs/container/seclab-taskflow-agent) |
| 171 | + |
| 172 | +Note that this image is based on the public release of the Taskflow Agent, and you will have to mount any custom taskflows, personalities, or prompts into the image for them to be available to the Agent. See [docker/run.sh](docker/run.sh) for examples of use. |
0 commit comments