153 lines
3.4 KiB
Markdown
153 lines
3.4 KiB
Markdown
# Agent Guide
|
|
|
|
This guide explains how to configure and create custom agents in TAKT.
|
|
|
|
## Built-in Agents
|
|
|
|
TAKT includes three built-in agents:
|
|
|
|
| Agent | Tools | Purpose |
|
|
|-------|-------|---------|
|
|
| `coder` | Read, Glob, Grep, Edit, Write, Bash, WebSearch, WebFetch | Implements features and fixes bugs |
|
|
| `architect` | Read, Glob, Grep, WebSearch, WebFetch | Reviews code and provides feedback |
|
|
| `supervisor` | Read, Glob, Grep, Bash, WebSearch, WebFetch | Final verification and approval |
|
|
|
|
## Specifying Agents
|
|
|
|
In workflow YAML, agents can be specified by:
|
|
|
|
```yaml
|
|
# Built-in agent name
|
|
agent: coder
|
|
|
|
# Path to prompt file
|
|
agent: ~/.takt/agents/my-agent.md
|
|
|
|
# Project-local agent
|
|
agent: ./.takt/agents/reviewer.md
|
|
|
|
# Absolute path
|
|
agent: /path/to/custom/agent.md
|
|
```
|
|
|
|
## Creating Custom Agents
|
|
|
|
### Agent Prompt File
|
|
|
|
Create a Markdown file with your agent's instructions:
|
|
|
|
```markdown
|
|
# Security Reviewer
|
|
|
|
You are a security-focused code reviewer.
|
|
|
|
## Your Role
|
|
- Check for security vulnerabilities
|
|
- Verify input validation
|
|
- Review authentication logic
|
|
|
|
## Guidelines
|
|
- Focus on OWASP Top 10 issues
|
|
- Check for SQL injection, XSS, CSRF
|
|
- Verify proper error handling
|
|
|
|
## Output Format
|
|
Output one of these status markers:
|
|
- [REVIEWER:APPROVE] if code is secure
|
|
- [REVIEWER:REJECT] if issues found
|
|
```
|
|
|
|
### Status Markers
|
|
|
|
Agents must output status markers for workflow transitions:
|
|
|
|
| Status | Example Pattern |
|
|
|--------|----------------|
|
|
| done | `[AGENT:DONE]` |
|
|
| blocked | `[AGENT:BLOCKED]` |
|
|
| approved | `[AGENT:APPROVED]`, `[AGENT:APPROVE]` |
|
|
| rejected | `[AGENT:REJECTED]`, `[AGENT:REJECT]` |
|
|
|
|
## Advanced Configuration
|
|
|
|
### Using agents.yaml
|
|
|
|
For more control, define agents in `.takt/agents.yaml`:
|
|
|
|
```yaml
|
|
agents:
|
|
- name: security-reviewer
|
|
prompt_file: .takt/prompts/security-reviewer.md
|
|
allowed_tools:
|
|
- Read
|
|
- Glob
|
|
- Grep
|
|
status_patterns:
|
|
approved: "\\[SECURITY:APPROVE\\]"
|
|
rejected: "\\[SECURITY:REJECT\\]"
|
|
```
|
|
|
|
### Tool Permissions
|
|
|
|
Available tools:
|
|
- `Read` - Read files
|
|
- `Glob` - Find files by pattern
|
|
- `Grep` - Search file contents
|
|
- `Edit` - Modify files
|
|
- `Write` - Create/overwrite files
|
|
- `Bash` - Execute commands
|
|
- `WebSearch` - Search the web
|
|
- `WebFetch` - Fetch web content
|
|
|
|
## Best Practices
|
|
|
|
1. **Clear role definition** - State what the agent does and doesn't do
|
|
2. **Explicit output format** - Define exact status markers
|
|
3. **Minimal tools** - Grant only necessary permissions
|
|
4. **Focused scope** - One agent, one responsibility
|
|
5. **Examples** - Include examples of expected behavior
|
|
|
|
## Example: Multi-Reviewer Setup
|
|
|
|
```yaml
|
|
# .takt/agents.yaml
|
|
agents:
|
|
- name: security-reviewer
|
|
prompt_file: .takt/prompts/security.md
|
|
allowed_tools: [Read, Glob, Grep]
|
|
status_patterns:
|
|
approved: "\\[SEC:OK\\]"
|
|
rejected: "\\[SEC:FAIL\\]"
|
|
|
|
- name: performance-reviewer
|
|
prompt_file: .takt/prompts/performance.md
|
|
allowed_tools: [Read, Glob, Grep, Bash]
|
|
status_patterns:
|
|
approved: "\\[PERF:OK\\]"
|
|
rejected: "\\[PERF:FAIL\\]"
|
|
```
|
|
|
|
```yaml
|
|
# workflow.yaml
|
|
steps:
|
|
- name: implement
|
|
agent: coder
|
|
# ...
|
|
|
|
- name: security-review
|
|
agent: security-reviewer
|
|
transitions:
|
|
- condition: approved
|
|
next_step: performance-review
|
|
- condition: rejected
|
|
next_step: implement
|
|
|
|
- name: performance-review
|
|
agent: performance-reviewer
|
|
transitions:
|
|
- condition: approved
|
|
next_step: COMPLETE
|
|
- condition: rejected
|
|
next_step: implement
|
|
```
|