gh-epieczko-betty/agents/api.designer

api.designer Agent

Purpose

api.designer is an intelligent agent that orchestrates the API design process from natural language requirements to validated, production-ready OpenAPI specifications with generated models.

This agent uses iterative refinement to create APIs that comply with enterprise guidelines (Zalando by default), automatically fixing validation errors and ensuring best practices.

Behavior

• Reasoning Mode: iterative – The agent retries on validation failures, refining the spec until it passes all checks
• Capabilities:
  • Design RESTful APIs from natural language requirements
  • Apply Zalando guidelines automatically (or other guideline sets)
  • Generate OpenAPI 3.1 specs with best practices
  • Iteratively refine based on validation feedback
  • Handle AsyncAPI for event-driven architectures

Skills Used

The agent has access to the following skills and uses them in sequence:

Skill	Purpose
api.define	Scaffolds initial OpenAPI spec from service name and requirements
api.validate	Validates spec against enterprise guidelines (Zalando, Google, Microsoft)
api.generate-models	Generates type-safe models in target languages (TypeScript, Python, etc.)
api.compatibility	Checks for breaking changes when updating existing APIs

Workflow Pattern

The agent follows this iterative pattern:

1. Analyze requirements and domain context
2. Draft OpenAPI spec following guidelines
3. Run validation (api.validate)
4. If validation fails:
   - Analyze errors
   - Refine spec
   - Re-validate
   - Repeat until passing (max 3 retries)
5. Generate models for target languages
6. Verify generated models compile

Manifest Fields (Quick Reference)

name: api.designer
version: 0.1.0
reasoning_mode: iterative
skills_available:
  - api.define
  - api.validate
  - api.generate-models
  - api.compatibility
status: draft

Usage

This agent is invoked through a command or workflow:

Via Slash Command

# Assuming /api-design command is registered to use this agent
/api-design user-service

The command passes the service name to the agent, which then:

1. Uses api.define to create initial spec
2. Validates with api.validate
3. Fixes any validation errors iteratively
4. Generates models with api.generate-models

Via Workflow

Include the agent in a workflow YAML:

# workflows/design_api.yaml
steps:
  - agent: api.designer
    input:
      service_name: "user-service"
      guidelines: "zalando"
      languages: ["typescript", "python"]

Context Requirements

The agent expects the following context:

Field	Type	Description	Example
guidelines	string	Which API guidelines to follow	"zalando", "google", "microsoft"
domain	string	Business domain for API design	"user-management", "e-commerce"
existing_apis	list	Related APIs to maintain consistency with	["auth-service", "notification-service"]
strict_mode	boolean	Whether to treat warnings as errors	true or false

Example Task

Input:

"Create API for user management with CRUD operations,
 authentication via JWT, and email verification workflow"

Agent execution:

1. Draft OpenAPI spec with proper resource paths:

   • POST /users - Create user
   • GET /users/{id} - Get user
   • PUT /users/{id} - Update user
   • DELETE /users/{id} - Delete user
   • POST /users/{id}/verify-email - Email verification

2. Apply Zalando guidelines:

   • Use snake_case for property names
   • Include problem JSON error responses
   • Add required headers (X-Request-ID, etc.)
   • Define proper HTTP status codes

3. Validate spec using api.validate:

   python skills/api.validate/api_validate.py specs/user-service.yaml zalando
   

4. Fix validation issues (if any):

   • Missing required headers → Add to spec
   • Incorrect naming → Convert to snake_case
   • Missing error schemas → Add problem JSON schemas

5. Generate models using Modelina:

   python skills/api.generate-models/modelina_generate.py \
     specs/user-service.yaml typescript src/models/typescript
   python skills/api.generate-models/modelina_generate.py \
     specs/user-service.yaml python src/models/python
   

6. Verify models compile:

   • TypeScript: tsc --noEmit
   • Python: mypy --strict

Error Handling

Scenario	Max Retries	Behavior
Validation failure	3	Analyze errors, refine spec, retry
Model generation failure	3	Try alternative Modelina configurations
Compilation failure	3	Adjust spec to fix type issues
Timeout	N/A	Fails after 300 seconds (5 minutes)

On Success

{
  "status": "success",
  "outputs": {
    "spec_path": "specs/user-service.openapi.yaml",
    "validation_report": {
      "valid": true,
      "errors": [],
      "warnings": []
    },
    "generated_models": {
      "typescript": ["src/models/typescript/User.ts", "src/models/typescript/UserResponse.ts"],
      "python": ["src/models/python/user.py", "src/models/python/user_response.py"]
    },
    "dependency_graph": "..."
  }
}

On Failure

{
  "status": "failed",
  "error_analysis": {
    "step": "validation",
    "attempts": 3,
    "last_error": "Missing required header: X-Request-ID in all endpoints"
  },
  "partial_spec": "specs/user-service.openapi.yaml",
  "suggested_fixes": [
    "Add X-Request-ID header to all operations",
    "See Zalando guidelines: https://..."
  ]
}

Status

Draft – This agent is under development and not yet marked active in the registry. Current goals for next version:

• Improve prompt engineering for better initial API designs
• Add more robust error handling for iterative loops
• Support for more guideline sets (Google, Microsoft)
• Better context injection from existing APIs
• Automatic testing of generated models

Related Documentation

• Agents Overview – Understanding agents in Betty's architecture
• Agent Schema Reference – Agent manifest fields and structure
• API-Driven Development – Full API design workflow using Betty
• api.define SKILL.md – Skill for creating API specs
• api.validate SKILL.md – Skill for validating specs
• api.generate-models SKILL.md – Skill for generating models

Version History

• 0.1.0 (Oct 2025) – Initial draft implementation with iterative refinement pattern