[P1] Implement WorkerAgent.execute_task() with Anthropic API integration

[frankbria]

Overview

The core task execution method in WorkerAgent is currently stubbed with a TODO comment. This prevents agents from actually executing tasks autonomously.

Current State

File: codeframe/agents/worker_agent.py lines 97-99

# TODO: Implement task execution with LLM provider
# TODO: Add token tracking after LLM call (see docstring example)
return {"status": "completed", "output": "Task executed successfully"}

Expected Behavior

• Initialize AsyncAnthropic client with API key from environment
• Construct prompt from task description and context
• Make LLM API call using Claude Sonnet 4.5 (or configurable model)
• Parse response and extract task output
• Handle errors gracefully (rate limits, network issues, etc.)
• Return structured result with status and output

Implementation Requirements

1. Use AsyncAnthropic client for async API calls
2. Follow the pattern shown in docstring example
3. Include proper error handling and retries
4. Use streaming for long responses (optional enhancement)
5. Support model selection via configuration

Acceptance Criteria

• execute_task() makes actual Anthropic API calls
• Token usage is tracked and returned in response
• Error handling covers rate limits, network issues, invalid responses
• Unit tests verify API call construction (mocked)
• Integration tests verify end-to-end task execution (real API)

Priority

P1 - Critical: Without this, workers cannot perform their primary function of autonomous task execution.

References

• User Documentation: CODEFRAME_USER_DOCUMENTATION.md lines 16-21
• Issues Analysis: CODEFRAME_ISSUES_ANALYSIS.md lines 11-20

[traycerai]

Plan

Observations

The WorkerAgent.execute_task() method in file:codeframe/agents/worker_agent.py (lines 67-99) is currently stubbed with TODO comments. The codebase already has established patterns for Anthropic API integration in file:codeframe/agents/frontend_worker_agent.py (lines 91-217) and file:codeframe/agents/hybrid_worker.py (lines 123-205). The file:codeframe/providers/anthropic.py provides a synchronous provider, while specialized agents use AsyncAnthropic directly. Token tracking infrastructure exists via file:codeframe/lib/metrics_tracker.py with the record_token_usage() method. Configuration management in file:codeframe/core/config.py handles API keys from environment variables.

Approach

The implementation will follow the async pattern established by FrontendWorkerAgent, using AsyncAnthropic client directly for maximum flexibility. The method will be converted to async, initialize the client with API key from environment, construct a prompt from task description and context, make the API call, handle errors with proper exception types, record token usage via MetricsTracker, and return a structured result. This approach aligns with the existing codebase patterns and satisfies all acceptance criteria without introducing unnecessary complexity.

Implementation Steps

1. Update Method Signature and Imports

File: file:codeframe/agents/worker_agent.py

• Change execute_task() method signature from sync to async (line 67)
• Add imports at the top of the file:
  • import os
  • from anthropic import AsyncAnthropic, AuthenticationError, RateLimitError, APIConnectionError
  • from codeframe.lib.metrics_tracker import MetricsTracker
  • from codeframe.core.models import CallType
• Update the method signature to: async def execute_task(self, task: Task) -> dict:

2. Initialize AsyncAnthropic Client

File: file:codeframe/agents/worker_agent.py (within execute_task() method)

• Retrieve API key from environment: api_key = os.getenv("ANTHROPIC_API_KEY")
• Add validation to raise ValueError if API key is missing with helpful message directing to .env.example
• Determine model name from configuration or use default "claude-sonnet-4-20250514"
• Initialize client: client = AsyncAnthropic(api_key=api_key)
• Set self.current_task = task to establish project context (already present at line 96)

3. Construct Prompt from Task

File: file:codeframe/agents/worker_agent.py (within execute_task() method)

• Build a structured prompt combining:
  • Task title from task.title
  • Task description from task.description
  • Task number from task.task_number
  • System prompt from self.system_prompt if available
• Format as clear instructions for the LLM
• Example structure:

  Task #{task.task_number}: {task.title}
  
  Description:
  {task.description}
  
  Please complete this task and provide a summary of the work done.
  

4. Make Anthropic API Call with Error Handling

File: file:codeframe/agents/worker_agent.py (within execute_task() method)

• Wrap API call in try-except block
• Make async call: response = await client.messages.create(model=model_name, max_tokens=4096, messages=[{"role": "user", "content": prompt}])
• Extract response content: content = response.content[0].text if response.content else ""
• Extract token usage: input_tokens = response.usage.input_tokens, output_tokens = response.usage.output_tokens
• Handle specific exceptions:
  • AuthenticationError: Log error, return failed status with message about invalid API key
  • RateLimitError: Log warning, return failed status with message about rate limits
  • APIConnectionError: Log error, return failed status with network error message
  • TimeoutError: Log error, return failed status with timeout message
  • Generic Exception: Log error, return failed status with generic error message
• All error returns should follow format: {"status": "failed", "output": error_message, "error": str(e)}

5. Record Token Usage

File: file:codeframe/agents/worker_agent.py (within execute_task() method)

• After successful API call, initialize MetricsTracker: tracker = MetricsTracker(db=self.db)
• Call await tracker.record_token_usage() with parameters:
  • task_id=task.id
  • agent_id=self.agent_id
  • project_id=task.project_id
  • model_name=model_name
  • input_tokens=input_tokens
  • output_tokens=output_tokens
  • call_type=CallType.TASK_EXECUTION
• Wrap in try-except to prevent token tracking failures from blocking task execution
• Log warning if token tracking fails but continue execution

6. Return Structured Result

File: file:codeframe/agents/worker_agent.py (within execute_task() method)

• On success, return dictionary with:
  • "status": "completed"
  • "output": content (the LLM response text)
  • "usage": {"input_tokens": input_tokens, "output_tokens": output_tokens}
  • "model": model_name
• Ensure return format matches existing patterns in FrontendWorkerAgent and HybridWorkerAgent

7. Update Dependent Code

Files: Any files that call WorkerAgent.execute_task()

• Search for calls to execute_task() using grep: execute_task\(
• Update all call sites to use await since method is now async
• Common locations:
  • file:codeframe/agents/backend_worker_agent.py
  • file:codeframe/agents/frontend_worker_agent.py
  • file:codeframe/agents/test_worker_agent.py
  • file:codeframe/agents/review_worker_agent.py
  • Test files in tests/agents/
• Verify each calling method is also async or wrapped in asyncio.run()

8. Add Unit Tests

File: file:tests/agents/test_worker_agent.py (create if doesn't exist)

• Test successful execution:
  • Mock AsyncAnthropic client with @patch("anthropic.AsyncAnthropic")
  • Mock response with sample content and token usage
  • Verify returned status is "completed"
  • Verify output contains expected content
  • Verify usage dict has input_tokens and output_tokens
• Test API key validation:
  • Mock missing ANTHROPIC_API_KEY environment variable
  • Verify ValueError is raised with helpful message
• Test error handling:
  • Mock AuthenticationError and verify failed status returned
  • Mock RateLimitError and verify failed status returned
  • Mock APIConnectionError and verify failed status returned
  • Mock TimeoutError and verify failed status returned
  • Mock generic Exception and verify failed status returned
• Test token tracking:
  • Mock MetricsTracker.record_token_usage with AsyncMock
  • Verify it's called with correct parameters
  • Verify task execution succeeds even if token tracking fails
• Use @pytest.mark.asyncio decorator for all async tests
• Follow patterns from file:tests/agents/test_backend_worker_agent.py (lines 609-787)

9. Add Integration Tests

File: file:tests/integration/test_worker_agent_integration.py (create if doesn't exist)

• Test end-to-end execution with real Anthropic API:
  • Skip if ANTHROPIC_API_KEY not set: @pytest.mark.skipif(not os.getenv("ANTHROPIC_API_KEY"), reason="API key required")
  • Create real task with simple description
  • Call execute_task() without mocks
  • Verify response status is "completed"
  • Verify token usage is recorded in database
  • Verify output is non-empty string
• Test with different model configurations:
  • Test with claude-sonnet-4-20250514 (default)
  • Test with claude-haiku-4 (if supported)
• Follow patterns from file:tests/integration/test_backend_worker_agent_integration.py

10. Update Documentation

File: file:codeframe/agents/worker_agent.py (docstring for execute_task())

• Update method docstring to reflect async nature
• Document return value structure with all keys
• Add example showing token tracking integration
• Document error handling behavior
• Add note about API key requirement
• Update the existing docstring example (lines 78-93) to show actual implementation instead of TODO

File: file:CODEFRAME_USER_DOCUMENTATION.md

• Update section on WorkerAgent to reflect implemented functionality
• Add example of using execute_task() with async/await
• Document error scenarios and how to handle them

Architecture Diagram

sequenceDiagram
    participant Caller
    participant WorkerAgent
    participant AsyncAnthropic
    participant MetricsTracker
    participant Database

    Caller->>WorkerAgent: await execute_task(task)
    WorkerAgent->>WorkerAgent: Get API key from env
    WorkerAgent->>WorkerAgent: Build prompt from task
    WorkerAgent->>AsyncAnthropic: await messages.create()
    
    alt API Success
        AsyncAnthropic-->>WorkerAgent: Response with content & usage
        WorkerAgent->>MetricsTracker: await record_token_usage()
        MetricsTracker->>Database: Save token usage
        Database-->>MetricsTracker: usage_id
        MetricsTracker-->>WorkerAgent: success
        WorkerAgent-->>Caller: {status: "completed", output, usage}
    else API Error
        AsyncAnthropic-->>WorkerAgent: AuthenticationError/RateLimitError/etc
        WorkerAgent-->>Caller: {status: "failed", error}
    end

Loading

Key Implementation Details

Component	Implementation	Location
API Client	AsyncAnthropic	anthropic package
API Key Source	os.getenv("ANTHROPIC_API_KEY")	Environment variable
Default Model	claude-sonnet-4-20250514	Configurable via parameter
Token Tracking	MetricsTracker.record_token_usage()	file:codeframe/lib/metrics_tracker.py
Error Types	AuthenticationError, RateLimitError, APIConnectionError, TimeoutError	anthropic package
Return Format	{"status": str, "output": str, "usage": dict}	Consistent with other agents
Test Pattern	@patch("anthropic.AsyncAnthropic") with AsyncMock	unittest.mock

Configuration Requirements

Ensure the following environment variable is set in .env:

ANTHROPIC_API_KEY=sk-ant-api03-...

Reference file:.env.example (lines 9-11) for the expected format.

Import In IDE

🤖 Prompt for AI Agents

## Observations

The `WorkerAgent.execute_task()` method in `file:codeframe/agents/worker_agent.py` (lines 67-99) is currently stubbed with TODO comments. The codebase already has established patterns for Anthropic API integration in `file:codeframe/agents/frontend_worker_agent.py` (lines 91-217) and `file:codeframe/agents/hybrid_worker.py` (lines 123-205). The `file:codeframe/providers/anthropic.py` provides a synchronous provider, while specialized agents use `AsyncAnthropic` directly. Token tracking infrastructure exists via `file:codeframe/lib/metrics_tracker.py` with the `record_token_usage()` method. Configuration management in `file:codeframe/core/config.py` handles API keys from environment variables.

## Approach

The implementation will follow the async pattern established by `FrontendWorkerAgent`, using `AsyncAnthropic` client directly for maximum flexibility. The method will be converted to async, initialize the client with API key from environment, construct a prompt from task description and context, make the API call, handle errors with proper exception types, record token usage via `MetricsTracker`, and return a structured result. This approach aligns with the existing codebase patterns and satisfies all acceptance criteria without introducing unnecessary complexity.

## Implementation Steps

### 1. Update Method Signature and Imports

**File**: `file:codeframe/agents/worker_agent.py`

- Change `execute_task()` method signature from sync to async (line 67)
- Add imports at the top of the file:
  - `import os`
  - `from anthropic import AsyncAnthropic, AuthenticationError, RateLimitError, APIConnectionError`
  - `from codeframe.lib.metrics_tracker import MetricsTracker`
  - `from codeframe.core.models import CallType`
- Update the method signature to: `async def execute_task(self, task: Task) -> dict:`

### 2. Initialize AsyncAnthropic Client

**File**: `file:codeframe/agents/worker_agent.py` (within `execute_task()` method)

- Retrieve API key from environment: `api_key = os.getenv("ANTHROPIC_API_KEY")`
- Add validation to raise `ValueError` if API key is missing with helpful message directing to `.env.example`
- Determine model name from configuration or use default `"claude-sonnet-4-20250514"`
- Initialize client: `client = AsyncAnthropic(api_key=api_key)`
- Set `self.current_task = task` to establish project context (already present at line 96)

### 3. Construct Prompt from Task

**File**: `file:codeframe/agents/worker_agent.py` (within `execute_task()` method)

- Build a structured prompt combining:
  - Task title from `task.title`
  - Task description from `task.description`
  - Task number from `task.task_number`
  - System prompt from `self.system_prompt` if available
- Format as clear instructions for the LLM
- Example structure:
  ```
  Task #{task.task_number}: {task.title}
  
  Description:
  {task.description}
  
  Please complete this task and provide a summary of the work done.
  ```

### 4. Make Anthropic API Call with Error Handling

**File**: `file:codeframe/agents/worker_agent.py` (within `execute_task()` method)

- Wrap API call in try-except block
- Make async call: `response = await client.messages.create(model=model_name, max_tokens=4096, messages=[{"role": "user", "content": prompt}])`
- Extract response content: `content = response.content[0].text if response.content else ""`
- Extract token usage: `input_tokens = response.usage.input_tokens`, `output_tokens = response.usage.output_tokens`
- Handle specific exceptions:
  - `AuthenticationError`: Log error, return failed status with message about invalid API key
  - `RateLimitError`: Log warning, return failed status with message about rate limits
  - `APIConnectionError`: Log error, return failed status with network error message
  - `TimeoutError`: Log error, return failed status with timeout message
  - Generic `Exception`: Log error, return failed status with generic error message
- All error returns should follow format: `{"status": "failed", "output": error_message, "error": str(e)}`

### 5. Record Token Usage

**File**: `file:codeframe/agents/worker_agent.py` (within `execute_task()` method)

- After successful API call, initialize MetricsTracker: `tracker = MetricsTracker(db=self.db)`
- Call `await tracker.record_token_usage()` with parameters:
  - `task_id=task.id`
  - `agent_id=self.agent_id`
  - `project_id=task.project_id`
  - `model_name=model_name`
  - `input_tokens=input_tokens`
  - `output_tokens=output_tokens`
  - `call_type=CallType.TASK_EXECUTION`
- Wrap in try-except to prevent token tracking failures from blocking task execution
- Log warning if token tracking fails but continue execution

### 6. Return Structured Result

**File**: `file:codeframe/agents/worker_agent.py` (within `execute_task()` method)

- On success, return dictionary with:
  - `"status": "completed"`
  - `"output": content` (the LLM response text)
  - `"usage": {"input_tokens": input_tokens, "output_tokens": output_tokens}`
  - `"model": model_name`
- Ensure return format matches existing patterns in `FrontendWorkerAgent` and `HybridWorkerAgent`

### 7. Update Dependent Code

**Files**: Any files that call `WorkerAgent.execute_task()`

- Search for calls to `execute_task()` using grep: `execute_task\(`
- Update all call sites to use `await` since method is now async
- Common locations:
  - `file:codeframe/agents/backend_worker_agent.py`
  - `file:codeframe/agents/frontend_worker_agent.py`
  - `file:codeframe/agents/test_worker_agent.py`
  - `file:codeframe/agents/review_worker_agent.py`
  - Test files in `tests/agents/`
- Verify each calling method is also async or wrapped in `asyncio.run()`

### 8. Add Unit Tests

**File**: `file:tests/agents/test_worker_agent.py` (create if doesn't exist)

- Test successful execution:
  - Mock `AsyncAnthropic` client with `@patch("anthropic.AsyncAnthropic")`
  - Mock response with sample content and token usage
  - Verify returned status is "completed"
  - Verify output contains expected content
  - Verify usage dict has input_tokens and output_tokens
- Test API key validation:
  - Mock missing `ANTHROPIC_API_KEY` environment variable
  - Verify `ValueError` is raised with helpful message
- Test error handling:
  - Mock `AuthenticationError` and verify failed status returned
  - Mock `RateLimitError` and verify failed status returned
  - Mock `APIConnectionError` and verify failed status returned
  - Mock `TimeoutError` and verify failed status returned
  - Mock generic `Exception` and verify failed status returned
- Test token tracking:
  - Mock `MetricsTracker.record_token_usage` with `AsyncMock`
  - Verify it's called with correct parameters
  - Verify task execution succeeds even if token tracking fails
- Use `@pytest.mark.asyncio` decorator for all async tests
- Follow patterns from `file:tests/agents/test_backend_worker_agent.py` (lines 609-787)

### 9. Add Integration Tests

**File**: `file:tests/integration/test_worker_agent_integration.py` (create if doesn't exist)

- Test end-to-end execution with real Anthropic API:
  - Skip if `ANTHROPIC_API_KEY` not set: `@pytest.mark.skipif(not os.getenv("ANTHROPIC_API_KEY"), reason="API key required")`
  - Create real task with simple description
  - Call `execute_task()` without mocks
  - Verify response status is "completed"
  - Verify token usage is recorded in database
  - Verify output is non-empty string
- Test with different model configurations:
  - Test with `claude-sonnet-4-20250514` (default)
  - Test with `claude-haiku-4` (if supported)
- Follow patterns from `file:tests/integration/test_backend_worker_agent_integration.py`

### 10. Update Documentation

**File**: `file:codeframe/agents/worker_agent.py` (docstring for `execute_task()`)

- Update method docstring to reflect async nature
- Document return value structure with all keys
- Add example showing token tracking integration
- Document error handling behavior
- Add note about API key requirement
- Update the existing docstring example (lines 78-93) to show actual implementation instead of TODO

**File**: `file:CODEFRAME_USER_DOCUMENTATION.md`

- Update section on WorkerAgent to reflect implemented functionality
- Add example of using `execute_task()` with async/await
- Document error scenarios and how to handle them

## Architecture Diagram

```mermaid
sequenceDiagram
    participant Caller
    participant WorkerAgent
    participant AsyncAnthropic
    participant MetricsTracker
    participant Database

    Caller->>WorkerAgent: await execute_task(task)
    WorkerAgent->>WorkerAgent: Get API key from env
    WorkerAgent->>WorkerAgent: Build prompt from task
    WorkerAgent->>AsyncAnthropic: await messages.create()
    
    alt API Success
        AsyncAnthropic-->>WorkerAgent: Response with content & usage
        WorkerAgent->>MetricsTracker: await record_token_usage()
        MetricsTracker->>Database: Save token usage
        Database-->>MetricsTracker: usage_id
        MetricsTracker-->>WorkerAgent: success
        WorkerAgent-->>Caller: {status: "completed", output, usage}
    else API Error
        AsyncAnthropic-->>WorkerAgent: AuthenticationError/RateLimitError/etc
        WorkerAgent-->>Caller: {status: "failed", error}
    end
```

## Key Implementation Details

| Component | Implementation | Location |
|-----------|---------------|----------|
| API Client | `AsyncAnthropic` | `anthropic` package |
| API Key Source | `os.getenv("ANTHROPIC_API_KEY")` | Environment variable |
| Default Model | `claude-sonnet-4-20250514` | Configurable via parameter |
| Token Tracking | `MetricsTracker.record_token_usage()` | `file:codeframe/lib/metrics_tracker.py` |
| Error Types | `AuthenticationError`, `RateLimitError`, `APIConnectionError`, `TimeoutError` | `anthropic` package |
| Return Format | `{"status": str, "output": str, "usage": dict}` | Consistent with other agents |
| Test Pattern | `@patch("anthropic.AsyncAnthropic")` with `AsyncMock` | `unittest.mock` |

## Configuration Requirements

Ensure the following environment variable is set in `.env`:

```bash
ANTHROPIC_API_KEY=sk-ant-api03-...
```

Reference `file:.env.example` (lines 9-11) for the expected format.

---

Execution Information

Branch: main
Commit: 1a87e4e

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

_{You can configure auto-planning by selecting labels in the issue_enrichment configuration.}

🔗 Similar Issues

Related Issues

• [Future] Evaluate Subagent Context Isolation per Task #68
• [Future] Implement Goal Recitation for Long-Running Tasks #70
• [Future] Audit and Enforce Tool Definition Stability #69
• [Future] Evaluate Task-Scoped Context vs. Agent-Level Context Tiers #72
• [Phase 4] Replace Fixed Self-Correction Cap with Adaptive Failure Handling #71

🔗 Related PRs

#11 - feat: Convert worker agents to async/await pattern (cf-48) [merged]
#28 - feat: Complete session lifecycle implementation and fix integration tests [merged]

👤 Suggested Assignees

• frankbria

---

🧪 Issue enrichment is currently in open beta.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord or schedule a call!