Semantic Annotation Framework

@RoleSpec                 → BDI + Gaia metadata
├── @Responsibility       → Role responsibilities (nested)
└── @LLMConfig            → LLM configuration (nested)

@Action                   → Action definition
├── @WebService          → HTTP call config (nested)
├── @LLMTool             → Tool calling config (nested)
└── @MCPTool             → MCP server config (nested)

@Communication           → Communication style
├── @Style               → Tone, formality (nested)
└── @Messaging           → Channels, topics (nested)

@Coordination            → Multi-agent coordination
└── @Consensus           → Voting mechanism (nested)

@Memory                  → Memory management
├── @Conversation        → Conversation memory (nested)
├── @Vector              → Vector memory (nested)
└── @Persistence         → Persistence (nested)

@Resilience              → Resilience
├── @Retry               → Retry policy (nested)
├── @CircuitBreaker      → Circuit breaker (nested)
└── @RateLimit           → Rate limiting (nested)

@Security                → Security
@Contract                → Design by Contract
@Lifecycle               → Lifecycle callbacks

@RoleSpec(
    name = "ResearchAgent",
    description = "Agent that performs academic research",
    version = "1.0.0",

    // BDI Model
    beliefs = {"research_context", "available_sources"},
    desires = {"find_relevant_papers", "synthesize_findings"},
    intentions = {"search_databases", "analyze_papers"},

    // Gaia Responsibilities
    responsibilities = {
        @Responsibility(
            name = "Paper Search",
            description = "Search in academic databases",
            actions = {"searchPapers", "filterResults"}
        )
    },

    // LLM Configuration
    llm = @LLMConfig(
        provider = "ollama",
        model = "llama3",
        temperature = 0.7f,
        maxTokens = 4096
    )
)
public class ResearchRole extends Role {
    // ...
}

@Action(
    type = ActionType.LOCAL,
    description = "Calculates the sum of numbers"
)
public double calculateSum(List<Double> numbers) {
    return numbers.stream().mapToDouble(d -> d).sum();
}

@Action(
    type = ActionType.WEB_SERVICE,
    description = "Fetches weather data",
    webService = @WebService(
        endpoint = "https://api.weather.com/v1/current",
        method = HttpMethod.GET,
        timeout = 5000,
        auth = AuthType.BEARER,
        authTokenEnv = "WEATHER_API_KEY"
    )
)
public WeatherData getWeather(String city) {
    return null; // HTTP call is made automatically
}

@Action(
    type = ActionType.LLM_TOOL,
    description = "Performs research from academic sources",
    llmTool = @LLMTool(
        tools = {BuiltInTool.ARXIV, BuiltInTool.GOOGLE_SCHOLAR},
        maxToolCalls = 5,
        parallelToolCalls = true,
        temperature = 0.3f
    )
)
public String researchTopic(String topic) {
    return "Please research: " + topic;
}

@Action(
    type = ActionType.MCP_TOOL,
    description = "Fetches cryptocurrency data",
    mcpTool = @MCPTool(
        serverUrl = "https://mcp.coingecko.com/mcp",
        toolName = "get_coin_price",
        apiKeyEnv = "COINGECKO_API_KEY"
    )
)
public CoinPrice getCoinPrice(String coinId) {
    return null; // Called via MCP
}

@Resilience(
    retry = @Retry(
        maxAttempts = 3,
        backoffMs = 1000,
        multiplier = 2.0
    ),
    circuitBreaker = @CircuitBreaker(
        enabled = true,
        failureThreshold = 5,
        resetTimeoutMs = 30000
    ),
    timeout = 10000,
    fallback = "fallbackMethod"
)
public Result fetchData(String query) {
    // ...
}

@Communication(
    style = @Style(
        tone = Tone.PROFESSIONAL,
        formality = Formality.FORMAL,
        verbosity = Verbosity.CONCISE
    ),
    messaging = @Messaging(
        channels = {"research-updates"},
        topics = {"papers", "findings"}
    ),
    language = "tr",
    responseFormat = ResponseFormat.MARKDOWN
)
public class ResearchRole extends Role { }

// Orchestrator Agent
@Coordination(
    role = CoordinationRole.ORCHESTRATOR,
    workers = {"analyst-1", "analyst-2", "writer-1"},
    consensus = @Consensus(
        strategy = Strategy.MAJORITY,
        threshold = 0.6
    ),
    taskDistribution = TaskDistribution.CAPABILITY_BASED
)
public class TeamLeaderRole extends Role { }

// Worker Agent
@Coordination(
    role = CoordinationRole.WORKER,
    orchestrator = "team-leader",
    capabilities = {"analysis", "summarization"}
)
public class AnalystRole extends Role { }

@Memory(
    conversation = @Conversation(
        enabled = true,
        maxMessages = 100,
        strategy = Strategy.SLIDING_WINDOW
    ),
    vector = @Vector(
        enabled = true,
        dimensions = 1536,
        provider = "pinecone",
        topK = 5
    ),
    persistent = true,
    namespace = "research-agent"
)
public class ResearchRole extends Role { }

@Security(
    approvalRequired = true,
    approvalReason = "Critical data deletion operation",
    audit = AuditLevel.DETAILED,
    sensitive = true,
    requiredPermissions = {"admin", "data-manager"}
)
@Action(type = ActionType.LOCAL)
public void deleteUserData(String userId) {
    // ...
}

@Contract(
    preconditions = {
        "userId != null",
        "userId.length() > 0"
    },
    postconditions = {
        "result != null",
        "result.isValid()"
    },
    invariants = {
        "this.connectionPool.isHealthy()"
    }
)
@Action(type = ActionType.LOCAL)
public UserData fetchUser(String userId) {
    // ...
}

public class ResearchAgent extends Agent {

    @Lifecycle(phase = Phase.INIT)
    public void loadResources() {
        // Load resources
    }

    @Lifecycle(phase = Phase.START, order = 1)
    public void connectToDatabase() {
        // Connect to database
    }

    @Lifecycle(phase = Phase.STOP)
    public void cleanup() {
        // Release resources
    }

    @Lifecycle(phase = Phase.ERROR)
    public void handleError(Throwable error) {
        // Error handling
    }
}

RoleExporter exporter = new JsonRoleExporter();
String json = exporter.export(myRole);
exporter.exportToFile(myRole, Path.of("role.json"));

RoleExporter exporter = new YamlRoleExporter();
String yaml = exporter.export(myRole);

RoleExporter exporter = new JasonExporter();
String asl = exporter.export(myRole);
// Generates AgentSpeak code

RoleExporter exporter = new JadeExporter();
String xml = exporter.export(myRole);
// Generates JADE agent descriptor

// CORRECT: Using nested annotations
@Action(
    type = ActionType.WEB_SERVICE,
    webService = @WebService(endpoint = "https://api.example.com")
)

// INCORRECT: Using flat properties (old style, no longer supported)
@Action(
    type = ActionType.WEB_SERVICE,
    endpoint = "https://api.example.com"  // ERROR!
)