minions-ai-agents/docs/AI_AGENT_PROTOCOL.md

🤖 AI Agent Protocol

READ THIS BEFORE WORKING ON THE CODEBASE

This document defines the mandatory protocols for AI agents working on the Antigravity Brain project.

---

🎯 Prime Directives

1. READ KNOWLEDGE FIRST - Before writing ANY code, read relevant src/knowledge/standards/*.md
2. NEVER HARDCODE SECRETS - Use Config class and environment variables
3. TOOLS MUST NOT RAISE - Always return error strings, never raise exceptions
4. TEST BEFORE COMMIT - Verify changes with docker-compose restart app

---

📖 Required Reading by Task Type

Task	Must Read First
Python tools	python_tool_standards.md
Docker changes	docker_standards.md
New agents	DEVELOPER_GUIDE.md#adding-new-agents
Database	database_standards.md
Security	security_standards.md
Git operations	git_standards.md
UI changes	ui_ux_standards.md

---

✅ Code Change Checklist

Before making any change:

• Read relevant standards file
• Check if pattern already exists in codebase
• Plan change with minimal impact
• Add error handling
• Test locally

After making change:

• Restart container: docker-compose restart app
• Check logs for errors: docker logs antigravity_brain --tail 50
• Verify functionality works
• Commit with proper message format

---

📝 Commit Message Format

<type>: <short description>

<optional body>

Types:

• feat: New feature
• fix: Bug fix
• docs: Documentation
• refactor: Code cleanup
• test: Tests
• chore: Maintenance

Example:

feat: Add new DevOps agent persona

- Created persona-devops-dan.md
- Added to Infrastructure crew
- Assigned Docker tools

---

🔧 Tool Development Protocol

class MyTool(BaseTool):
    name: str = "Descriptive Name"  # Agent reads this
    description: str = (
        "DETAILED description of when to use this tool. "
        "Include example inputs and expected outputs."
    )
    args_schema: type = MyToolInput  # Pydantic model with Field descriptions

    def _run(self, **kwargs) -> str:
        try:
            # Your logic
            return "Success: ..."
        except SpecificError as e:
            return f"Error: Specific handling for {e}"
        except Exception as e:
            return f"Error: Unexpected - {str(e)[:100]}"

NEVER:

• Use input() for user interaction
• Raise exceptions
• Return raw JSON (use narrative text)
• Use Any type hints

---

🤖 Agent Development Protocol

Persona Files

1. Use YAML frontmatter for metadata
2. Include **Role:** and **Goal:** fields
3. Write backstory in character voice
4. Define clear protocols/procedures

Tool Assignment

• Only assign tools the agent actually needs
• Consider model_tier: tools requiring reasoning → smart
• Memory tools are auto-assigned to all agents

---

📁 File Placement Rules

Content Type	Location
Agent personas	src/agents/personas/persona-*.md
Tools	src/tools/*.py
Knowledge standards	src/knowledge/standards/*.md
Dynamic knowledge	src/knowledge/dynamic/*/*.md
Crew definitions	src/crews/definitions.py
Configuration	src/config.py

---

⚠️ Common Mistakes to Avoid

1. Variable Names in Standards

❌ BAD:

return f"Error: File '{path}' not found"  # {path} interpreted as template

✅ GOOD:

return f"Error: File 'PATH_VAR' not found"  # Escaped

2. Missing Rate Limiting

❌ BAD:

while True:
    api.call()  # Burns quota instantly

✅ GOOD:

for attempt in range(MAX_RETRIES):
    result = api.call()
    if success: break
    time.sleep(DELAY * (2 ** attempt))

3. Hardcoded Configuration

❌ BAD:

model = "gpt-4"
api_key = "sk-xxx"

✅ GOOD:

config = Config.get_llm_config(mode="smart")

---

🧪 Testing Protocol

1. Local test:

   docker-compose restart app
   docker logs antigravity_brain --tail 50
   

2. Verify no errors:

   docker logs antigravity_brain 2>&1 | findstr "Error ERROR Exception"
   

3. Interactive test:

   • Open http://localhost:8000
   • Send test message
   • Verify correct crew routing
   • Check agent response

---

🚀 Deployment Protocol

1. Commit changes:

   git add .
   git commit -m "feat: Description"
   git push
   

2. On production server:

   git pull
   docker-compose build --no-cache app
   docker-compose up -d
   

---

Remember: Quality over speed. Read the standards. Test your changes.