Declarative Annotations

static <T> T createAgenticSystem(Class<T> agentServiceClass);
static <T> T createAgenticSystem(Class<T> agentServiceClass, ChatModel chatModel);
static <T> T createAgenticSystem(Class<T> agentServiceClass, Consumer<DeclarativeAgentCreationContext> configurator);
static <T> T createAgenticSystem(Class<T> agentServiceClass, ChatModel chatModel, Consumer<DeclarativeAgentCreationContext> configurator);

interface Assistant {
    @Agent(name = "assistant", description = "General purpose assistant")
    String assist(String query);
}

Assistant assistant = AgenticServices.createAgenticSystem(Assistant.class, chatModel);
String response = assistant.assist("Hello!");

interface MyAgents {
    @Agent(
        name = "researcher",
        description = "Researches topics using web search",
        outputKey = "research_results",
        async = false
    )
    String research(String topic);

    @Agent(
        name = "writer",
        description = "Writes articles based on research",
        summarizedContext = {"researcher"}
    )
    String write(String topic);
}

interface Pipeline {
    @SequenceAgent(
        name = "data-pipeline",
        description = "Processes data through multiple stages",
        subAgents = {Fetcher.class, Processor.class, Validator.class}
    )
    String processPipeline(String input);
}

interface ParallelProcessing {
    @ParallelAgent(
        name = "multi-source",
        description = "Fetches data from multiple sources simultaneously",
        subAgents = {ApiSource.class, DatabaseSource.class, FileSource.class}
    )
    String fetchAllSources(String query);
}

interface IterativeRefinement {
    @LoopAgent(
        name = "refiner",
        description = "Iteratively refines output until quality threshold met",
        maxIterations = 5,
        subAgents = {Generator.class, Evaluator.class}
    )
    String refine(String input);

    @ExitCondition
    boolean isQualityMet(AgenticScope scope) {
        return scope.hasState("quality_score") &&
               (Integer) scope.readState("quality_score") >= 8;
    }
}

interface ConditionalProcessing {
    @ConditionalAgent(
        name = "router",
        description = "Routes to different processors based on input type",
        subAgents = {TextProcessor.class, ImageProcessor.class}
    )
    String process(String input);
}

interface TextProcessor {
    @Agent(name = "text-processor")
    String process(String input);

    @ActivationCondition
    boolean shouldActivate(AgenticScope scope) {
        return scope.readState("input_type").equals("text");
    }
}

interface SupervisedSystem {
    @SupervisorAgent(
        name = "orchestrator",
        description = "Coordinates specialized agents",
        subAgents = {Researcher.class, Analyst.class, Writer.class},
        maxAgentsInvocations = 15,
        contextStrategy = SupervisorContextStrategy.FULL,
        responseStrategy = SupervisorResponseStrategy.SUMMARY
    )
    String complete(String task);
}

interface PlannedExecution {
    @PlannerAgent(
        name = "dynamic-planner",
        subAgents = {Agent1.class, Agent2.class}
    )
    String execute(String goal);

    @PlannerSupplier
    Planner getPlanner();
}

interface DistributedAgents {
    @A2AClientAgent(
        name = "remote-analyzer",
        description = "Connects to remote analysis service",
        serverUrl = "http://analysis-service:8080"
    )
    String analyze(String data);
}

interface ApprovalWorkflow {
    @Agent(name = "drafter")
    String draft(String topic);

    @HumanInTheLoop(
        name = "approval",
        description = "Human reviews and approves draft",
        inputKey = "draft",
        outputKey = "approved_draft"
    )
    String getApproval();

    @Agent(name = "publisher")
    String publish();
}

interface ConfiguredAgents {
    @ChatModelSupplier
    ChatModel getChatModel();

    @ToolsSupplier
    List<Object> getTools();

    @Agent(name = "assistant")
    String assist(String query);
}

interface RobustAgent {
    @Agent(name = "processor")
    String process(String input);

    @ErrorHandler
    ErrorRecoveryResult handleError(Throwable error, AgenticScope scope);
}

interface CustomOutput {
    @Agent(name = "processor")
    String process(String input);

    @Output
    String customizeOutput(AgenticScope scope);
}

interface ConditionalPipeline {
    @SequenceAgent(
        subAgents = {Agent1.class, OptionalAgent.class, Agent3.class}
    )
    String process(String input);

    default boolean shouldRunOptional(AgenticScope scope) {
        return (Boolean) scope.readState("feature_enabled", false);
    }
}

interface OptionalAgent {
    @Agent(name = "optional")
    @ActivationCondition(conditionMethod = "shouldRunOptional")
    String process(AgenticScope scope);
}

interface LoopWorkflow {
    @LoopAgent(maxIterations = 10, subAgents = {Worker.class})
    String work(String input);

    @ExitCondition
    boolean shouldExit(AgenticScope scope) {
        return scope.hasState("done");
    }
}

interface SupervisorSystem {
    @SupervisorAgent(subAgents = {Agent1.class, Agent2.class})
    String coordinate(String task);

    @SupervisorRequest
    String generateRequest(AgenticScope scope) {
        String task = (String) scope.readState("user_input");
        return "Coordinate agents to solve: " + task;
    }
}

interface HITLWorkflow {
    @SequenceAgent(
        subAgents = {Generator.class, HumanReview.class, Publisher.class}
    )
    String workflow(String input);

    @HumanInTheLoopResponseSupplier
    String getHumanFeedback() {
        Scanner scanner = new Scanner(System.in);
        return scanner.nextLine();
    }
}

interface ParallelSystem {
    @ParallelAgent(
        subAgents = {Worker1.class, Worker2.class, Worker3.class}
    )
    List<String> processInParallel(String input);

    @ParallelExecutor
    static Executor executor() {
        return Executors.newFixedThreadPool(3);
    }
}

interface UserName extends TypedKey<String> {
    @Override
    default String name() {
        return "UserName";
    }
}

interface PersonalizedAgent {
    @Agent(name = "greeter")
    String greet(@K(UserName.class) String name, @K(UserAge.class) int age);
}

interface LoopingAgent {
    @LoopAgent(maxIterations = 10, subAgents = {Processor.class})
    String processUntilDone(String input);
}

interface Processor {
    @Agent(name = "processor")
    String process(String input, @LoopCounter int iteration);
}

interface ComprehensiveSystem {
    // Chat model configuration
    @ChatModelSupplier
    ChatModel getChatModel() {
        return OpenAiChatModel.builder()
            .apiKey(System.getenv("OPENAI_API_KEY"))
            .modelName("gpt-4")
            .build();
    }

    // Tools configuration
    @ToolsSupplier
    List<Object> getTools() {
        return List.of(new WebSearchTool(), new CalculatorTool());
    }

    // Agent listener for observability
    @AgentListenerSupplier
    AgentListener getListener() {
        return new LoggingListener();
    }

    // Sequential workflow
    @SequenceAgent(
        name = "main-workflow",
        subAgents = {DataCollector.class, Analyzer.class, Reporter.class}
    )
    String processRequest(String input);

    // Error handler
    @ErrorHandler
    ErrorRecoveryResult handleError(Throwable error, AgenticScope scope) {
        if (error instanceof RetryableException) {
            return ErrorRecoveryResult.retry();
        }
        return ErrorRecoveryResult.throwException();
    }

    // Custom output
    @Output
    String formatOutput(AgenticScope scope) {
        return Map.of(
            "result", scope.readState("final_result"),
            "metadata", scope.readState("metadata")
        ).toString();
    }
}