Agent Management

Agent Management in PostQode allows you to enable and configure specialized agents that can handle specific tasks autonomously. These agents extend PostQode's capabilities by delegating complex tasks to purpose-built AI assistants.

Accessing Agent Management Settings

Open VS Code with PostQode extension installed
Click on the PostQode icon in the sidebar to open the PostQode panel
Click on the Settings icon (gear icon) in the PostQode panel
Navigate to the Agent Management section

Enable Agents

Default: Disabled

Allow the AI to delegate tasks to specialized agents for more efficient and focused task execution.

What are Specialized Agents?

Specialized agents are AI assistants configured for specific types of tasks. Instead of using a general-purpose AI for everything, PostQode can delegate tasks to agents that are optimized for particular domains.

Examples of Specialized Agents:

Code Review Agent - Focused on reviewing code quality and best practices
Testing Agent - Specialized in writing and executing tests
Documentation Agent - Expert at creating and updating documentation
Debugging Agent - Optimized for finding and fixing bugs
API Agent - Specialized in API testing and automation
Web Agent - Focused on web automation and browser testing

How Agent Delegation Works

When you enable agents, PostQode can:

Analyze Your Task - Understand what you're trying to accomplish
Select Appropriate Agent - Choose the best specialized agent for the task
Delegate Execution - Hand off the task to the specialized agent
Return Results - Bring back the completed work

Example Flow:

You: "Review this code for security issues"
  ↓
PostQode: Analyzes request → Delegates to Code Review Agent
  ↓
Code Review Agent: Performs security analysis
  ↓
PostQode: Returns security review results to you

Benefits of Using Agents

1. Specialized Expertise

Each agent is optimized for specific tasks with:

Domain-specific knowledge
Specialized prompts and instructions
Focused tool access
Optimized workflows

2. Improved Efficiency

Faster task completion with specialized agents
Better results from domain expertise
Reduced token usage with focused agents
Parallel task execution capabilities

3. Better Organization

Clear separation of concerns
Consistent behavior for specific task types
Easier to maintain and update
Reusable across projects

4. Customization

Create your own specialized agents
Tailor agents to your team's needs
Share agents across projects
Version control agent configurations

Types of Agents

PostQode supports different types of agents, each serving specific purposes and stored in different locations.

Built-in Agents

Location: Bundled with PostQode extension

Purpose: Pre-configured agents provided by PostQode for common tasks.

PostQode comes with several built-in agents that are ready to use out of the box:

Code Review Agent - Reviews code for quality, security, and best practices
Testing Agent - Generates and executes test suites
Documentation Agent - Creates and updates technical documentation
Debugging Agent - Helps identify and fix bugs
Refactoring Agent - Assists with code refactoring and optimization

Benefits:

✅ No configuration needed - works immediately
✅ Professionally designed and tested
✅ Regularly updated with PostQode releases
✅ Optimized for common development tasks
✅ Best practices built-in

How to Use: Built-in agents are automatically available when you enable the "Enable Agents" feature. PostQode will automatically delegate tasks to the appropriate built-in agent based on your request.

Note: Built-in agents cannot be modified directly, but you can create custom agents that override or extend their functionality.

Organization Agents

Location: Configured by your organization administrator

Purpose: Company-wide agents shared across all organization members.

Organization agents are centrally managed agents that enforce company standards and workflows across all team members.

Characteristics:

Centrally Managed: Configured and maintained by organization admins
Automatic Distribution: Automatically available to all organization members
Enforced Standards: Ensures consistent practices across teams
Cannot be Modified: Individual users cannot change organization agents
Priority: Take precedence over personal and project agents

Common Use Cases:

Security Review Agent: Enforces company security standards
Compliance Agent: Ensures regulatory compliance
Code Style Agent: Enforces company coding standards
Documentation Agent: Maintains consistent documentation format
Deployment Agent: Follows company deployment procedures

Benefits:

✅ Consistent standards across entire organization
✅ Centralized updates and improvements
✅ Enforced best practices
✅ Reduced configuration overhead for team members
✅ Compliance and security enforcement

How Organization Agents Work:

Admin Configuration: Organization admins configure agents in the organization settings
Automatic Sync: Agents are automatically synced to all organization members
Transparent Usage: Users don't need to do anything - agents work automatically
Cannot Override: Individual users cannot disable or modify organization agents
Regular Updates: Admins can update agents, changes propagate automatically

Example Scenario:

Your Organization: Acme Corp
Organization Agents:
  - acme-security-reviewer (enforces Acme security standards)
  - acme-code-style-checker (enforces Acme coding style)
  - acme-deployment-validator (validates deployment procedures)

When you write code:
  ↓
PostQode automatically uses acme-security-reviewer
  ↓
Code is checked against Acme's security standards
  ↓
You receive feedback aligned with company policies

For Organization Administrators:

To configure organization agents:

Access organization settings in PostQode admin panel
Navigate to "Organization Agents" section
Create or upload agent configuration files
Set agent priority and scope
Publish agents to organization members

For Team Members:

Organization agents work automatically:

No configuration needed
Cannot be disabled (enforced by organization)
Visible in agent list with "Organization" badge
Take priority over personal and project agents
Updates happen automatically

Agent Storage Locations

Agents are defined as .md files (Markdown) in specific directories. PostQode looks for agents in the following locations:

1. Project Agents (Team-Shared)

Location: .postqode/agents/

Purpose: Agents shared with your entire team through version control.

Use Cases:

Team-specific workflows
Project-specific conventions
Shared testing strategies
Company coding standards

Example:

your-project/
└── .postqode/
    └── agents/
        ├── code-reviewer.md
        ├── api-tester.md
        └── documentation-writer.md

Benefits:

✅ Version controlled with your project
✅ Shared automatically with team members
✅ Consistent across all team members
✅ Project-specific customization

2. Personal Agents (All Projects)

Location: ~/.postqode/agents/

Purpose: Your personal agents available across all your projects.

Use Cases:

Personal productivity tools
Individual coding preferences
Cross-project utilities
Personal automation scripts

Example:

~/.postqode/
└── agents/
    ├── my-code-style-checker.md
    ├── my-commit-message-generator.md
    └── my-refactoring-assistant.md

Benefits:

✅ Available in all your projects
✅ Personal customization
✅ Not shared with team (private)
✅ Portable across workspaces

3. Claude Code Compatible Agents

Location: .claude/agents/

Purpose: Agents compatible with Claude Code format for cross-tool compatibility.

Use Cases:

Sharing agents with Claude Code users
Migration from Claude Code
Cross-tool workflows
Standard agent formats

Example:

your-project/
└── .claude/
    └── agents/
        ├── test-generator.md
        └── bug-fixer.md

Benefits:

✅ Compatible with Claude Code
✅ Standard format
✅ Easy migration
✅ Broader ecosystem support

Creating Custom Agents

You can create your own specialized agents by creating .md files in any of the agent directories.

Agent File Structure

Agents are defined using Markdown files with YAML frontmatter:

---
name: code-reviewer
description: Reviews code for quality, security, and best practices
model: claude-3-5-sonnet
tools: [read_file, search_files, write_to_file]
---

# Code Review Agent

You are a specialized code review agent focused on:
- Code quality and maintainability
- Security vulnerabilities
- Performance issues
- Best practices adherence

## Review Process

1. Read the code files
2. Analyze for issues
3. Provide detailed feedback
4. Suggest improvements

## Focus Areas

- Security: Check for common vulnerabilities
- Performance: Identify bottlenecks
- Maintainability: Assess code clarity
- Best Practices: Verify standards compliance

Agent Configuration Options

Frontmatter Fields

Required:

name: Unique identifier for the agent
description: What the agent does (used for task matching)

Optional:

model: Specific AI model to use (e.g., claude-3-5-sonnet, gpt-4)
tools: Array of tools the agent can use
temperature: Creativity level (0.0 - 1.0)
max_tokens: Maximum response length
system_prompt: Additional system instructions

Example Configurations

Testing Agent:

---
name: testing-agent
description: Generates and executes comprehensive test suites
model: claude-3-5-sonnet
tools: [read_file, write_to_file, execute_command, search_files]
temperature: 0.3
---

Documentation Agent:

---
name: docs-agent
description: Creates and updates technical documentation
model: gpt-4
tools: [read_file, write_to_file, search_files]
temperature: 0.7
---

API Testing Agent:

---
name: api-testing-agent
description: Automates API testing and validation
model: claude-3-5-sonnet
tools: [read_file, write_to_file, execute_command]
temperature: 0.2
---

Using Agents

Automatic Agent Selection

When agents are enabled, PostQode automatically selects the appropriate agent based on your task:

You: "Review this authentication code for security issues"
  ↓
PostQode: Matches task → Delegates to Code Review Agent
  ↓
Code Review Agent: Performs security review
  ↓
Result: Detailed security analysis returned

Manual Agent Selection

You can also explicitly request a specific agent:

You: "Use the testing-agent to create unit tests for this module"
  ↓
PostQode: Delegates to Testing Agent
  ↓
Testing Agent: Generates comprehensive unit tests

Agent Capabilities

Different agents have access to different tools:

Code Review Agent:

✅ Read files
✅ Search codebase
❌ Write files (read-only review)
❌ Execute commands

Testing Agent:

✅ Read files
✅ Write test files
✅ Execute tests
✅ Search for test patterns

Documentation Agent:

✅ Read code files
✅ Write documentation
✅ Search for examples
❌ Execute commands

Best Practices

1. Start with Project Agents

For team projects:

✅ Create agents in .postqode/agents/
✅ Commit agents to version control
✅ Document agent purposes in README
✅ Keep agents focused on project needs

2. Use Personal Agents for Individual Preferences

For personal workflows:

✅ Create agents in ~/.postqode/agents/
✅ Customize to your coding style
✅ Keep private preferences separate
✅ Don't mix with team agents

3. Keep Agents Focused

Each agent should have a clear, specific purpose:

✅ Good: "API Testing Agent" - Tests API endpoints
❌ Bad: "General Helper Agent" - Does everything

4. Limit Tool Access

Give agents only the tools they need:

# Testing agent doesn't need browser tools
tools: [read_file, write_to_file, execute_command]

# Documentation agent doesn't need execute
tools: [read_file, write_to_file, search_files]

5. Document Your Agents

Include clear instructions in the agent file:

## Purpose
This agent reviews code for security vulnerabilities.

## When to Use
- Before merging pull requests
- After implementing authentication
- When handling user input
- Before production deployment

## What It Checks
- SQL injection vulnerabilities
- XSS attack vectors
- Authentication bypass issues
- Data exposure risks

Troubleshooting

Agent Not Being Selected

Symptoms:

PostQode doesn't delegate to your custom agent
General AI handles tasks instead of specialized agent

Solutions:

Check agent description matches your task type
Verify agent file is in correct directory
Ensure agent file has .md extension
Restart VS Code to reload agents
Check agent file has valid YAML frontmatter

Agent Fails to Execute

Symptoms:

Agent starts but fails during execution
Error messages about missing tools

Solutions:

Verify agent has access to required tools
Check model configuration is correct
Ensure API keys are properly configured
Review agent system prompt for errors
Check agent has necessary permissions

Agent File Not Found

Symptoms:

"Agent file not found" error
Agent doesn't appear in available agents

Solutions:

Verify file is in correct directory:
- .postqode/agents/ for project agents
- ~/.postqode/agents/ for personal agents
- .claude/agents/ for Claude Code compatible
Check file has .md extension
Ensure directory exists (create if needed)
Restart VS Code to reload agents

Multiple Agents Conflict

Symptoms:

Wrong agent selected for task
Agents interfering with each other

Solutions:

Make agent descriptions more specific
Use unique, clear agent names
Limit agent scope to specific tasks
Review agent selection logic
Disable conflicting agents temporarily