---
paths:
  - agents/**/*
---

# AI Agent Development Rules

When working with AI agents in the `agents/` directory:

## Development Tool

Use `kubani` CLI for all agent development:

```bash
kubani run <agent> --hot-reload   # Run locally
kubani test <agent>               # Run tests
kubani eval <agent>               # Run evaluation
kubani ship <agent>               # Ship: test -> build -> deploy (preferred)
```

## Code Standards

- Use Python 3.11+ with full type annotations
- Use Pydantic models for all data structures
- Follow the patterns in `agents/core/` for shared functionality
- All agents depend on `core-agents` for base utilities
- Use `AgentFactory` for creating agents
- Use `GraphFactory` for hybrid workflows

## File Structure

Each agent must have:
```
agents/<agent-name>/
├── src/<agent_name>/
│   ├── __init__.py
│   ├── worker.py           # Temporal worker entry point
│   ├── workflows.py        # Temporal workflow definitions
│   ├── activities.py       # Temporal activity definitions
│   ├── models.py           # Pydantic data models
│   ├── agent_info.py       # A2A capability definitions
│   └── federated/          # Optional: federated agents
│       ├── sentinel.py     # Event classification
│       ├── healer.py       # Remediation
│       └── explorer.py     # Discovery
├── tests/
├── pyproject.toml          # Must include version
└── Earthfile               # Docker build definition
```

## Core Library Usage

Use the enhanced core library modules:

```python
# Agent creation
from kubani.framework import AgentConfig, get_agent_factory
factory = get_agent_factory()
agent = factory.create_agent(AgentConfig(...))

# Workflow graphs
from kubani.framework import GraphConfig
graph = factory.create_graph(GraphConfig(...))

# Context engineering
from kubani.framework.context import ContextManager
ctx = ContextManager(session_id="...")

# Continuous learning
from kubani.framework.learning import get_learning_manager
manager = get_learning_manager()

# Hierarchical memory
from kubani.framework.memory import HierarchicalMemorySystem
memory = HierarchicalMemorySystem(agent_id="...")

# Dynamic plugins
from kubani.framework.plugins import get_plugin_manager
plugins = get_plugin_manager()
```

## Versioning & Shipping

- Version is in `pyproject.toml`: `version = "0.1.0"`
- Image tags use `{version}-{git-sha}` format
- `kubani ship` auto-bumps patch version before each build
- Ship a component: `kubani ship <component-name>`
- Core framework changes require shipping ALL dependent agents

## Temporal Patterns

- Use descriptive workflow IDs: `<agent>-<action>-<timestamp>`
- Activities should be idempotent where possible
- Handle timeouts and retries appropriately
- Log important state transitions
- Use `AgentWorker` for standardized worker setup

## Testing

- Run tests: `kubani test <agent>`
- Run evaluation: `kubani eval <agent>`
- Include unit tests for activities
- Test workflow logic with mocks
- Use evaluation layers (automated, llm, simulation)

## Evaluation Framework

Run multi-layer evaluation:

```bash
kubani eval <agent>                # Full evaluation
kubani eval <agent> --layer llm    # LLM-as-judge only
```

Evaluation layers:
- **automated**: Fast, deterministic checks
- **llm**: LLM-as-judge evaluation
- **simulation**: Scenario-based testing
- **human**: Human review interface

## Observability

Use kubani for observability:

```bash
kubani dashboard        # Start dashboard
kubani trace <agent>    # View traces
kubani metrics <agent>  # View metrics
```