Cowork Overview¶

Cowork is Backend.AI GO's autonomous assistant mode: the agent takes your request, builds an execution plan, calls tools, and coordinates sub-agents to accomplish complex tasks.

Cowork is a mode of the unified conversation surface, and Home has no separate Cowork tab. A conversation runs as Cowork when you attach a working folder to it with Attach folder in the composer's + menu, from Home or in an ongoing chat. The change from chat to Cowork is one-way. The old /cowork route redirects to the conversation surface at /chat. See Chat and Cowork modes for how the two modes sit together.

What is Cowork?¶

Unlike a plain conversation where the model just predicts the next text, Cowork follows a ReAct (Reasoning + Acting) pattern:

1. Observe: Analyzes your request and the current environment.

2. Think: Builds an execution plan and emits a tool request when a step needs one.

3. Act: Executes a tool (e.g., searches the web, reads a file).

4. Observe: Looks at the result of the tool and decides whether to continue or provide a final answer.

Key Benefits¶

• Up-to-Date Information: Cowork can search the web to find information beyond the model's training data.

• Practical Actions: Cowork can interact with your local files or run code to verify calculations.

• Autonomous Reasoning: You give a high-level goal, and Cowork breaks it into sub-steps and runs them in order.

• Parallel Execution: Sub-agents can work on multiple tasks simultaneously for faster results.

When to Use Cowork¶

• Researching: "Find the latest pricing for NVIDIA RTX 50 series GPUs."

• Data Analysis: "Read the CSV file in my Documents folder and summarize the sales trends."

• Code Debugging: "Run this Python script and tell me why it's throwing a SyntaxError."

Getting Started with Cowork¶

1. Choose Attach folder from the composer's + menu on Home and pick a working folder, or attach one to an ongoing chat to continue it as Cowork. The working folder is the only Cowork entry: a run that needs no folder, such as web research, is a chat conversation and runs in it.

2. Select an Agent Profile (e.g., "General Assistant", "Web Researcher") from the profile selector.

3. Choose a model that supports Tool Calling (look for the "Tool Calling" tag in your library).

4. Enter your task in the composer.

5. Watch the agent's reasoning and tool execution in the workspace progress rail.

Folder Permissions¶

Cowork requires explicit permission to access folders on your system. This ensures the agent only operates within directories you approve.

Permission Levels¶

Managing Folder Access¶

1. In a Cowork conversation, open the workspace rail and go to the Context section (permitted folders and instructions). Attaching a folder to a conversation also grants access and escalates it to cowork.

2. Review the permitted directories listed there.

3. Click Add folder to open the folder picker and grant access to a new directory.

4. Set the permission level for each folder.

5. To revoke access, click the remove button next to a folder entry.

Standing Instructions¶

Standing instructions are persistent directives that guide the agent's behavior across all tasks. They are injected into the system prompt for every interaction.

Global Instructions¶

Global standing instructions apply to all Cowork conversations regardless of which folder or profile is active.

1. Open the Settings drawer and go to the Global Instructions tab.

2. Enter your global instructions (e.g., "Always respond in formal English", "Prefer Python over JavaScript for code tasks").

Folder-Specific Instructions¶

You can also set standing instructions that apply only when a specific folder is active:

1. Open the Settings drawer and go to the Permitted Folders tab.

2. Enter folder-specific instructions in the field below each folder (e.g., "This is a React project using TypeScript and Zustand", "Follow the coding conventions in CONTRIBUTING.md").

Folder-specific instructions are combined with global instructions and injected together into the system prompt.

Mid-Task Steering¶

While a Cowork task is running, you can provide real-time guidance to steer the agent's behavior without stopping and restarting the task.

How to Steer¶

1. While a task is in progress, type your guidance in the composer, the same input you use to start a turn.

2. Press Enter to send the steering message. Mid-run input is routed as steering rather than starting a new turn.

3. The agent will incorporate your guidance into its next reasoning step.

Steering messages can be up to 10,000 characters and are useful for:

• Correcting the agent's approach ("Focus on the backend files, not the frontend")
• Providing additional context ("The database uses PostgreSQL, not MySQL")
• Adjusting priorities ("Skip the unit tests for now and focus on the main implementation")

Sub-Agent Coordination¶

For complex tasks, Cowork can spawn sub-agents that work in parallel on different parts of a task.

How Sub-Agents Work¶

• The main agent analyzes your task and breaks it into sub-tasks when beneficial.
• Each sub-agent runs independently with its own tool access and reasoning chain.
• Results from sub-agents are collected and synthesized by the main agent.

Sub-Agent Execution Mode¶

Sub-agents run in-process by default. Choose Container in Cowork Settings to execute sub-agent tasks in containers while the main agent stays in-process. The bundled container image produces one text response without file tools or follow-up steering. See Cowork Container Mode for setup, folder permissions, and cancellation.

Configuring Sub-Agents¶

• Max Concurrent: Set the maximum number of sub-agents that can run simultaneously in Cowork Settings. Higher values allow more parallelism but consume more resources.

Sub-Agent Tracker¶

The Cowork UI includes a tracker that shows:

• Active sub-agents and their current status
• What each sub-agent is working on
• Progress of individual sub-tasks
• Results as they complete

Run History¶

Cowork records past runs. In a Cowork conversation, the workspace rail's Progress section shows the session's most recent run: while a run is in progress you watch it live, and when the session is idle the section shows a summary card of the last run. Clicking that card opens the Run Details view.

Run Details¶

The detailed view shows:

• Task: The original task description you provided.

• Metadata Summary: At-a-glance stats including status badge, duration, step count, and total tokens used. Below the summary, the model name, start time, and end time are displayed.

• Execution Steps: A collapsible list of every step the agent took. Each step shows a type-specific icon and can be expanded to reveal:

  • Thinking steps: The agent's reasoning rendered as Markdown.
  • Tool Call steps: The tool name and arguments in a structured view.
  • Tool Result steps: Success/failure badge with the result rendered as Markdown.
  • Final Answer: The complete answer rendered as Markdown, with a Save to Library button.

Save to Library¶

Final answers from Cowork can be saved to the Library for later reference:

1. Expand a completed run's Final Answer step.

2. Click the Save to Library button (bookmark icon) at the bottom of the answer.

3. The answer is saved to the Library. Open Library in the sidebar and find it under the Chat bookmarks tab.

This feature works the same way as bookmarking a chat response.

Real-Time Streaming¶

When the agent is thinking, you can see its reasoning in real time:

• Thinking steps stream token-by-token as the model generates its response, giving immediate visual feedback.

• Once the thinking is complete, the step is finalized with the full content and the agent proceeds to execute tools or provide a final answer.

• Tool call parsing and the agent's decision logic remain unaffected by streaming — it only changes how quickly you see the thinking content.

Understanding the Status Indicator¶

The Cowork interface displays a prominent status badge that shows the current state:

Progress Tracking¶

Below the status badge, a visual progress bar shows:

• Completed steps: Filled portion of the bar
• Current step description: What the agent is currently doing
• Step count: "Step X of Y" format