agent.run

What this skill does

# agent.run

**Version:** 0.1.0
**Status:** Active
**Tags:** agents, execution, claude-api, orchestration, layer2

## Overview

The `agent.run` skill executes registered Betty agents by orchestrating the complete agent lifecycle: loading manifests, generating Claude-friendly prompts, invoking the Claude API (or simulating), executing planned skills, and logging all results.

This skill is the primary execution engine for Betty agents, enabling them to operate in both **iterative** and **oneshot** reasoning modes. It handles the translation between agent manifests and Claude API calls, manages skill invocation, and provides comprehensive logging for auditability.

## Features

- ✅ Load agent manifests from path or agent name
- ✅ Generate Claude-optimized system prompts with capabilities and workflow patterns
- ✅ Optional Claude API integration (with mock fallback for development)
- ✅ Support for both iterative and oneshot reasoning modes
- ✅ Skill selection and execution orchestration
- ✅ Comprehensive execution logging to `agent_logs/<agent>_<timestamp>.json`
- ✅ Structured JSON output for programmatic integration
- ✅ Error handling with detailed diagnostics
- ✅ Validation of agent manifests and available skills

## Usage

### Command Line

```bash
# Execute agent by name
python skills/agent.run/agent_run.py api.designer

# Execute with task context
python skills/agent.run/agent_run.py api.designer "Design a REST API for user management"

# Execute from manifest path
python skills/agent.run/agent_run.py agents/api.designer/agent.yaml "Create authentication API"

# Execute without saving logs
python skills/agent.run/agent_run.py api.designer "Design API" --no-save-log
```

### As a Skill (Programmatic)

```python
import sys
import os
sys.path.insert(0, os.path.abspath("./"))

from skills.agent.run.agent_run import run_agent

# Execute agent
result = run_agent(
    agent_path="api.designer",
    task_context="Design a REST API for user management with authentication",
    save_log=True
)

if result["ok"]:
    print(f"Agent executed successfully!")
    print(f"Skills invoked: {result['details']['summary']['skills_executed']}")
    print(f"Log saved to: {result['details']['log_path']}")
else:
    print(f"Execution failed: {result['errors']}")
```

### Via Claude Code Plugin

```bash
# Using the Betty plugin command
/agent/run api.designer "Design authentication API"

# With full path
/agent/run agents/api.designer/agent.yaml "Create user management endpoints"
```

## Input Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `agent_path` | string | Yes | - | Path to agent.yaml or agent name (e.g., `api.designer`) |
| `task_context` | string | No | None | Task or query to provide to the agent |
| `save_log` | boolean | No | true | Whether to save execution log to disk |

## Output Schema

```json
{
  "ok": true,
  "status": "success",
  "timestamp": "2025-10-23T14:30:00Z",
  "errors": [],
  "details": {
    "timestamp": "2025-10-23T14:30:00Z",
    "agent": {
      "name": "api.designer",
      "version": "0.1.0",
      "description": "Design RESTful APIs...",
      "reasoning_mode": "iterative",
      "status": "active"
    },
    "task_context": "Design a REST API for user management",
    "prompt": "You are api.designer, a specialized Betty Framework agent...",
    "skills_available": [
      {
        "name": "api.define",
        "description": "Create OpenAPI specifications",
        "status": "active"
      }
    ],
    "missing_skills": [],
    "claude_response": {
      "analysis": "I will design a comprehensive user management API...",
      "skills_to_invoke": [
        {
          "skill": "api.define",
          "purpose": "Create initial OpenAPI spec",
          "inputs": {"guidelines": "zalando"},
          "order": 1
        }
      ],
      "reasoning": "Following API design workflow pattern"
    },
    "execution_results": [
      {
        "skill": "api.define",
        "purpose": "Create initial OpenAPI spec",
        "status": "simulated",
        "timestamp": "2025-10-23T14:30:05Z",
        "output": {
          "success": true,
          "note": "Simulated execution of api.define"
        }
      }
    ],
    "summary": {
      "skills_planned": 3,
      "skills_executed": 3,
      "success": true
    },
    "log_path": "/home/user/betty/agent_logs/api.designer_20251023_143000.json"
  }
}
```

## Reasoning Modes

### Oneshot Mode

In **oneshot** mode, the agent analyzes the complete task and plans all skill invocations upfront in a single pass. The execution follows the predetermined plan without dynamic adjustment.

**Best for:**
- Well-defined tasks with predictable workflows
- Tasks where all steps can be determined in advance
- Performance-critical scenarios requiring minimal API calls

**Example Agent:**
```yaml
name: api.generator
reasoning_mode: oneshot
workflow_pattern: |
  1. Define API structure
  2. Validate specification
  3. Generate models
```

### Iterative Mode

In **iterative** mode, the agent analyzes results after each skill invocation and dynamically determines the next steps. It can retry failed operations, adjust its approach based on feedback, or invoke additional skills as needed.

**Best for:**
- Complex tasks requiring adaptive decision-making
- Tasks with validation/refinement loops
- Scenarios where results influence subsequent steps

**Example Agent:**
```yaml
name: api.designer
reasoning_mode: iterative
workflow_pattern: |
  1. Analyze requirements
  2. Draft OpenAPI spec
  3. Validate (if fails, refine and retry)
  4. Generate models
```

## Examples

### Example 1: Execute API Designer

```bash
python skills/agent.run/agent_run.py api.designer \
  "Create a REST API for managing blog posts with CRUD operations"
```

**Output:**
```
================================================================================
AGENT EXECUTION: api.designer
================================================================================

Agent: api.designer v0.1.0
Mode: iterative
Status: active

Task: Create a REST API for managing blog posts with CRUD operations

--------------------------------------------------------------------------------
CLAUDE RESPONSE:
--------------------------------------------------------------------------------
{
  "analysis": "I will design a RESTful API following best practices...",
  "skills_to_invoke": [
    {
      "skill": "api.define",
      "purpose": "Create initial OpenAPI specification",
      "inputs": {"guidelines": "zalando", "format": "openapi-3.1"},
      "order": 1
    },
    {
      "skill": "api.validate",
      "purpose": "Validate the specification for compliance",
      "inputs": {"strict_mode": true},
      "order": 2
    }
  ]
}

--------------------------------------------------------------------------------
EXECUTION RESULTS:
--------------------------------------------------------------------------------

  ✓ api.define
    Purpose: Create initial OpenAPI specification
    Status: simulated

  ✓ api.validate
    Purpose: Validate the specification for compliance
    Status: simulated

📝 Log saved to: /home/user/betty/agent_logs/api.designer_20251023_143000.json

================================================================================
EXECUTION COMPLETE
================================================================================
```

### Example 2: Execute with Direct Path

```bash
python skills/agent.run/agent_run.py \
  agents/api.analyzer/agent.yaml \
  "Analyze this OpenAPI spec for compatibility issues"
```

### Example 3: Execute Without Logging

```bash
python skills/agent.run/agent_run.py api.designer \
  "Design authentication API" \
  --no-save-log
```

### Example 4: Programmatic Integration

```python
from skills.agent.run.agent_run import run_agent, load_agent_manifest

# Load and inspect agent before running
manifest = load_agent_manifest("api.designer")
print(f"Ag