Agent System

The Kuse Cowork agent is an autonomous AI system that can plan and execute complex tasks using a combination of language models and tools.

How It Works

Agent Loop

The agent operates in a loop, processing the task step by step:

1. Receive Request: User provides task description and optional project context
2. Create Plan: Agent analyzes the request and creates a step-by-step plan
3. Execute Steps: Each step is executed, potentially using tools
4. Track Progress: Status events are emitted in real-time
5. Complete: Final response is generated and saved

Maximum Turns

The agent has a configurable maximum number of turns (default: 20). Each API call counts as one turn. This prevents infinite loops and runaway costs.

Planning

When given a task, the agent first creates a structured plan:

<plan>
1. Read the existing code file
2. Analyze the current implementation
3. Identify areas for improvement
4. Make the necessary edits
5. Verify the changes work
</plan>

Plan Visualization

The UI shows:

• Step Number: Current step being executed
• Description: What the step aims to accomplish
• Status: Pending, In Progress, Completed, or Failed
• Progress Markers: [STEP 1 START] and [STEP 1 DONE]

Tool Execution

The agent can use various tools to accomplish tasks:

Tool Selection

The agent automatically selects appropriate tools based on the task:

• Reading code? → read_file, glob, grep
• Making changes? → edit_file, write_file
• Running commands? → bash, docker_run
• Exploring project? → list_dir, glob

Real-time Events

The agent emits events during execution:

Event Types

Event Flow Example

[text] I'll help you refactor this code...
[plan] Created 5-step plan
[step_start] Step 1
[tool_start] read_file: src/component.tsx
[tool_end] success
[step_done] Step 1
[step_start] Step 2
[tool_start] edit_file: src/component.tsx
[tool_end] success
[step_done] Step 2
...
[done] Completed in 8 turns

‍

Context Management

Project Context

When a project folder is selected:

• Files are accessible via tools
• Folder is mounted at /workspace in Docker
• Agent understands project structure

Conversation History

The agent maintains context across turns:

• Previous messages are included in prompts
• Tool results are part of the conversation
• Context helps with follow-up tasks

Token Management

Long conversations are managed through:

• Context truncation for large files
• Summarization of verbose outputs
• Smart selection of relevant history

Task Types

Simple Tasks

Quick, single-step operations:

"What's in the package.json file?"

Agent: Reads file, provides summary

Multi-step Tasks

Complex operations requiring planning:

"Add a dark mode toggle to the settings page"

Agent:

1. Read existing settings component
2. Analyze current styling approach
3. Create theme context/store
4. Add toggle component
5. Update styles
6. Test the implementation

Iterative Tasks

Tasks requiring back-and-forth:

"Let's debug why the tests are failing"

Agent:

1. Run tests to see failures
2. Read failing test files
3. Read related source code
4. Identify issues
5. Propose fixes
6. Apply fixes
7. Re-run tests
8. Repeat if needed

Error Handling

Graceful Degradation

When tools fail, the agent:

1. Reports the error
2. Attempts alternative approaches
3. Asks for user guidance if stuck

Common Errors

Recovery Strategies

• Retry with different approach: Try alternative tools or methods
• Ask for clarification: Request more specific instructions
• Report partial progress: Show what was accomplished before error

Best Practices

Writing Effective Prompts

Be Specific

❌ "Fix the bug"
✅ "Fix the TypeError in handleSubmit function in src/components/Form.tsx"


Provide Context

❌ "Add authentication"
✅ "Add JWT authentication to the /api/users endpoint using the existing auth middleware"


Break Down Complex Tasks

❌ "Build a complete e-commerce site"
✅ "Create the product listing component with filtering"


Optimizing Performance

• Select project folder: Enables faster file access
• Use tool mode: Enable tools for actionable tasks
• Provide file paths: Direct paths are faster than searching

Working with Large Projects

• Focus on specific directories or files
• Use glob patterns to narrow scope
• Break large refactors into smaller tasks

System Prompt

The agent uses a system prompt that defines its behavior:

You are Kuse Cowork, an AI agent that helps users with
software development tasks.

## IMPORTANT: Always Create a Plan First

Before starting ANY task, you MUST output a plan in this
exact format:

<plan>
1. [First step description]
2. [Second step description]
...
</plan>

## Guidelines
- Always read files before modifying them
- Use edit_file for small changes, write_file for new files
- Be careful with bash commands
- Search with glob and grep before making assumptions

Customization

Future versions may support custom system prompts for:

• Different coding styles
• Specific project conventions
• Domain-specific knowledge

Advanced Features

MCP Tool Integration

When MCP servers are connected, additional tools become available:

[tool_start] mcp_server_tool_name
[tool_end] success

Skills Integration

Skills extend agent capabilities:

"Extract text from document.pdf"

[tool_start] read_file: ~/.kuse-cowork/skills/pdf/SKILL.md
[tool_end] Loaded skill instructions
[tool_start] docker_run: python /skills/pdf/extract.py /workspace/document.pdf
[tool_end] Extracted text content

Limitations

Current limitations of the agent system:

• Max turns: 50 turns per task (configurable)
• Context window: Limited by model's context length
• File size: Large files are truncated
• Network: Cannot make arbitrary HTTP requests
• Interactive: Cannot handle interactive prompts

Next Steps

• Tools Reference - Detailed tool documentation
• Skills System - Extend agent capabilities
• MCP Protocol - Connect external tools

‍