Initial commit
This commit is contained in:
Zhongwei Li
325
agents/meta.agent/README.md
Normal file
325
agents/meta.agent/README.md
Normal file
@@ -0,0 +1,325 @@
|
||||
# meta.agent - Agent Creator
|
||||
|
||||
The meta-agent that creates other agents through skill composition.
|
||||
|
||||
## Overview
|
||||
|
||||
**meta.agent** transforms natural language descriptions into complete, functional agents with proper skill composition, artifact metadata, and documentation.
|
||||
|
||||
**What it produces:**
|
||||
- Complete `agent.yaml` with recommended skills
|
||||
- Auto-generated `README.md` documentation
|
||||
- Proper artifact metadata (produces/consumes)
|
||||
- Inferred permissions from skills
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Create an Agent Description
|
||||
|
||||
Create a Markdown file describing your agent:
|
||||
|
||||
```markdown
|
||||
# Name: api.architect
|
||||
|
||||
# Purpose:
|
||||
An agent that designs comprehensive REST APIs and validates them
|
||||
against best practices.
|
||||
|
||||
# Inputs:
|
||||
- API requirements
|
||||
|
||||
# Outputs:
|
||||
- openapi-spec
|
||||
- validation-report
|
||||
- api-models
|
||||
|
||||
# Examples:
|
||||
- Design a RESTful API for an e-commerce platform
|
||||
- Create an API for a task management system
|
||||
```
|
||||
|
||||
### 2. Run meta.agent
|
||||
|
||||
```bash
|
||||
python3 agents/meta.agent/meta_agent.py examples/api_architect_description.md
|
||||
```
|
||||
|
||||
### 3. Output
|
||||
|
||||
```
|
||||
✨ Agent 'api.architect' created successfully!
|
||||
|
||||
📄 Agent definition: agents/api.architect/agent.yaml
|
||||
📖 Documentation: agents/api.architect/README.md
|
||||
|
||||
🔧 Skills: api.define, api.validate, workflow.validate
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### Basic Creation
|
||||
|
||||
```bash
|
||||
# Create agent from Markdown description
|
||||
python3 agents/meta.agent/meta_agent.py path/to/agent_description.md
|
||||
|
||||
# Create agent from JSON description
|
||||
python3 agents/meta.agent/meta_agent.py path/to/agent_description.json
|
||||
|
||||
# Specify output directory
|
||||
python3 agents/meta.agent/meta_agent.py description.md -o agents/my-agent
|
||||
|
||||
# Skip validation
|
||||
python3 agents/meta.agent/meta_agent.py description.md --no-validate
|
||||
```
|
||||
|
||||
### Description Format
|
||||
|
||||
**Markdown Format:**
|
||||
|
||||
```markdown
|
||||
# Name: agent-name
|
||||
|
||||
# Purpose:
|
||||
Detailed description of what the agent does...
|
||||
|
||||
# Inputs:
|
||||
- artifact-type-1
|
||||
- artifact-type-2
|
||||
|
||||
# Outputs:
|
||||
- artifact-type-3
|
||||
- artifact-type-4
|
||||
|
||||
# Constraints:
|
||||
(Optional) Any constraints or requirements...
|
||||
|
||||
# Examples:
|
||||
- Example use case 1
|
||||
- Example use case 2
|
||||
```
|
||||
|
||||
**JSON Format:**
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "agent-name",
|
||||
"purpose": "Detailed description...",
|
||||
"inputs": ["artifact-type-1", "artifact-type-2"],
|
||||
"outputs": ["artifact-type-3", "artifact-type-4"],
|
||||
"examples": ["Example 1", "Example 2"]
|
||||
}
|
||||
```
|
||||
|
||||
## What meta.agent Creates
|
||||
|
||||
### 1. agent.yaml
|
||||
|
||||
Complete agent definition with:
|
||||
- **Recommended skills** - Uses `agent.compose` to find compatible skills
|
||||
- **Artifact metadata** - Proper produces/consumes declarations
|
||||
- **Permissions** - Inferred from selected skills
|
||||
- **Description** - Professional formatting
|
||||
|
||||
Example output:
|
||||
```yaml
|
||||
name: api.architect
|
||||
description: Designs and validates REST APIs against best practices
|
||||
skills_available:
|
||||
- api.define
|
||||
- api.validate
|
||||
permissions:
|
||||
- filesystem:read
|
||||
- filesystem:write
|
||||
artifact_metadata:
|
||||
consumes:
|
||||
- type: api-requirements
|
||||
produces:
|
||||
- type: openapi-spec
|
||||
schema: schemas/openapi-spec.json
|
||||
- type: validation-report
|
||||
schema: schemas/validation-report.json
|
||||
```
|
||||
|
||||
### 2. README.md
|
||||
|
||||
Auto-generated documentation with:
|
||||
- Agent purpose and capabilities
|
||||
- Skills used with rationale
|
||||
- Artifact flow (inputs/outputs)
|
||||
- Example use cases
|
||||
- Usage instructions
|
||||
- "Created by meta.agent" attribution
|
||||
|
||||
## How It Works
|
||||
|
||||
1. **Parse Description** - Reads Markdown or JSON
|
||||
2. **Find Skills** - Uses `agent.compose` to recommend compatible skills
|
||||
3. **Generate Metadata** - Uses `artifact.define` for artifact contracts
|
||||
4. **Infer Permissions** - Analyzes required skills
|
||||
5. **Create Files** - Generates agent.yaml and README.md
|
||||
6. **Validate** - Ensures proper structure and compatibility
|
||||
|
||||
## Integration with Other Meta-Agents
|
||||
|
||||
### With meta.compatibility
|
||||
|
||||
After creating an agent, use `meta.compatibility` to analyze it:
|
||||
|
||||
```bash
|
||||
# Create agent
|
||||
python3 agents/meta.agent/meta_agent.py description.md
|
||||
|
||||
# Analyze compatibility
|
||||
python3 agents/meta.compatibility/meta_compatibility.py analyze api.architect
|
||||
```
|
||||
|
||||
### With meta.suggest
|
||||
|
||||
Get suggestions after creating an agent:
|
||||
|
||||
```bash
|
||||
python3 agents/meta.suggest/meta_suggest.py \
|
||||
--context meta.agent \
|
||||
--artifacts agents/api.architect/agent.yaml
|
||||
```
|
||||
|
||||
## Common Workflows
|
||||
|
||||
### Workflow 1: Create and Analyze
|
||||
|
||||
```bash
|
||||
# Step 1: Create agent
|
||||
python3 agents/meta.agent/meta_agent.py examples/my_agent.md
|
||||
|
||||
# Step 2: Analyze compatibility
|
||||
python3 agents/meta.compatibility/meta_compatibility.py find-compatible my-agent
|
||||
|
||||
# Step 3: Test the agent
|
||||
# (Manual testing or agent.run)
|
||||
```
|
||||
|
||||
### Workflow 2: Create Multiple Agents
|
||||
|
||||
```bash
|
||||
# Create several agents
|
||||
for desc in examples/*_agent_description.md; do
|
||||
python3 agents/meta.agent/meta_agent.py "$desc"
|
||||
done
|
||||
|
||||
# Analyze the ecosystem
|
||||
python3 agents/meta.compatibility/meta_compatibility.py list-all
|
||||
```
|
||||
|
||||
## Artifact Types
|
||||
|
||||
### Consumes
|
||||
|
||||
- **agent-description** - Natural language agent requirements
|
||||
- Format: Markdown or JSON
|
||||
- Pattern: `**/agent_description.md`
|
||||
|
||||
### Produces
|
||||
|
||||
- **agent-definition** - Complete agent.yaml
|
||||
- Format: YAML
|
||||
- Pattern: `agents/*/agent.yaml`
|
||||
- Schema: `schemas/agent-definition.json`
|
||||
|
||||
- **agent-documentation** - Auto-generated README
|
||||
- Format: Markdown
|
||||
- Pattern: `agents/*/README.md`
|
||||
|
||||
## Tips & Best Practices
|
||||
|
||||
### Writing Good Descriptions
|
||||
|
||||
✅ **Good:**
|
||||
- Clear, specific purpose
|
||||
- Well-defined inputs and outputs
|
||||
- Concrete examples
|
||||
- Specific artifact types
|
||||
|
||||
❌ **Avoid:**
|
||||
- Vague purpose ("does stuff")
|
||||
- Generic inputs ("data")
|
||||
- No examples
|
||||
- Unclear artifact types
|
||||
|
||||
### Choosing Artifact Types
|
||||
|
||||
Use existing artifact types when possible:
|
||||
- `openapi-spec` for API specifications
|
||||
- `validation-report` for validation results
|
||||
- `workflow-definition` for workflows
|
||||
|
||||
If you need a new type, create it with `meta.artifact` first.
|
||||
|
||||
### Skill Selection
|
||||
|
||||
meta.agent uses keyword matching to find skills:
|
||||
- "api" → finds api.define, api.validate
|
||||
- "validate" → finds validation skills
|
||||
- "agent" → finds agent.compose, meta.agent
|
||||
|
||||
Be descriptive in your purpose statement to get better skill recommendations.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Agent name conflicts
|
||||
|
||||
```
|
||||
Error: Agent 'api.architect' already exists
|
||||
```
|
||||
|
||||
**Solution:** Choose a different name or remove the existing agent directory.
|
||||
|
||||
### No skills recommended
|
||||
|
||||
```
|
||||
Warning: No skills found for agent purpose
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
- Make purpose more specific
|
||||
- Mention artifact types explicitly
|
||||
- Check if relevant skills exist in registry
|
||||
|
||||
### Missing artifact types
|
||||
|
||||
```
|
||||
Warning: Artifact type 'my-artifact' not in known registry
|
||||
```
|
||||
|
||||
**Solution:** Create the artifact type with `meta.artifact` first:
|
||||
```bash
|
||||
python3 agents/meta.artifact/meta_artifact.py create artifact_description.md
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
See `examples/` directory for sample agent descriptions:
|
||||
- `api_architect_description.md` - API design and validation agent
|
||||
- (Add more as you create them)
|
||||
|
||||
## Architecture
|
||||
|
||||
meta.agent is part of the meta-agent ecosystem:
|
||||
|
||||
```
|
||||
meta.agent
|
||||
├─ Uses: agent.compose (find skills)
|
||||
├─ Uses: artifact.define (generate metadata)
|
||||
├─ Produces: agent.yaml + README.md
|
||||
└─ Works with: meta.compatibility, meta.suggest
|
||||
```
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [META_AGENTS.md](../../docs/META_AGENTS.md) - Complete meta-agent architecture
|
||||
- [ARTIFACT_STANDARDS.md](../../docs/ARTIFACT_STANDARDS.md) - Artifact system
|
||||
- [agent-description schema](../../schemas/agent-description.json) - JSON schema
|
||||
|
||||
## Created By
|
||||
|
||||
Part of the Betty Framework meta-agent ecosystem.
|
||||
Reference in New Issue
Block a user