Files

Zhongwei Li 8f22ddf339 Initial commit

2025-11-29 18:26:08 +08:00

5.8 KiB

Raw Blame History

Betty Framework Agents

⚙️ Integration Note: Claude Code Plugin System

Betty agents are Claude Code plugins. You do not invoke agents via standalone CLI commands (betty or direct Python scripts). Instead:

Claude Code serves as the execution environment for all agent invocation
Each agent is registered through its agent.yaml manifest
Agents become automatically discoverable and executable through Claude Code's natural language interface
All routing, validation, and execution is handled by Claude Code via MCP (Model Context Protocol)

No separate installation step is needed beyond plugin registration in your Claude Code environment.

This directory contains agent manifests for the Betty Framework.

What are Agents?

Agents are intelligent orchestrators that compose skills with reasoning, context awareness, and error recovery. Unlike workflows (which follow fixed sequential steps) or skills (which execute atomic operations), agents can:

Reason about requirements and choose appropriate strategies
Iterate based on feedback and validation results
Recover from errors with intelligent retry logic
Adapt their approach based on context

Directory Structure

Each agent has its own directory containing:

agents/
├── <agent-name>/
│   ├── agent.yaml              # Agent manifest (required)
│   ├── README.md               # Documentation (auto-generated)
│   └── tests/                  # Agent behavior tests (optional)
│       └── test_agent.py

Creating an Agent

Using meta.agent (Recommended)

Via Claude Code:

"Use meta.agent to create a my.agent that does [description],
with capabilities [list], using skills [skill.one, skill.two],
and iterative reasoning mode"

Direct execution (development/testing):

cat > /tmp/my_agent.md <<'EOF'
# Name: my.agent
# Purpose: What your agent does
# Capabilities: First capability, Second capability
# Skills: skill.one, skill.two
# Reasoning: iterative
EOF
python agents/meta.agent/meta_agent.py /tmp/my_agent.md

Manual Creation

Create agent directory:
```
mkdir -p agents/my.agent
```

Create agent manifest (agents/my.agent/agent.yaml):

name: my.agent
version: 0.1.0
description: "What your agent does"

capabilities:
  - First capability
  - Second capability

skills_available:
  - skill.one
  - skill.two

reasoning_mode: iterative  # or oneshot

status: draft

Validate and register:

Via Claude Code:

"Use agent.define to validate agents/my.agent/agent.yaml"

Direct execution (development/testing):

python skills/agent.define/agent_define.py agents/my.agent/agent.yaml

Agent Manifest Schema

Required Fields

Field	Type	Description
`name`	string	Unique identifier (e.g., `api.designer`)
`version`	string	Semantic version (e.g., `0.1.0`)
`description`	string	Human-readable purpose statement
`capabilities`	array[string]	List of what the agent can do
`skills_available`	array[string]	Skills the agent can orchestrate
`reasoning_mode`	enum	`iterative` or `oneshot`

Optional Fields

Field	Type	Description
`status`	enum	`draft`, `active`, `deprecated`, `archived`
`context_requirements`	object	Structured context the agent needs
`workflow_pattern`	string	Narrative description of reasoning process
`example_task`	string	Concrete usage example
`error_handling`	object	Retry strategies and failure handling
`output`	object	Expected success/failure outputs
`tags`	array[string]	Categorization tags
`dependencies`	array[string]	Other agents or schemas

Reasoning Modes

Iterative

Agent can retry with feedback, refine based on errors, and improve incrementally.

Use for:

Validation loops (API design with validation feedback)
Refinement tasks (code optimization)
Error correction (fixing compilation errors)

Example:

reasoning_mode: iterative

error_handling:
  max_retries: 3
  on_validation_failure: "Analyze errors, refine spec, retry"

Oneshot

Agent executes once without retry.