326 lines
7.3 KiB
Markdown
326 lines
7.3 KiB
Markdown
# 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.
|