Building your first agent application

Now that you've seen how to get the SDK, we need to build our first agent. The easiest way to get going is to clone the starter kit from GitHub, located here: https://github.com/peoplelogic/agent-sdk-starter. This will setup the typical agent structure and contains the Application starter class and all of the necessary dependencies.

Defining the Agent Application

The entry point for any new agent application is the agent runner. This bootstraps your agents, gives you the ability to run either a web or CLI application and even allows you to override the startup banner. For those of you familiar with Spring Boot - the code will seem familiar.

SampleAgentRunner.java

@PeoplelogicAgentApplication
public class SampleAgentRunner extends PeoplelogicAgentRunner {
    public static void main(String[] args) {
        run(SampleAgentRunner.class, args);
    }
}

Creating the first agent

With the boilerplate setup for your agent application, you can get to the real work of creating your agent. The SDK makes a point of handling much of the repetitive code for you so that you can focus on the configuration, prompts and tooling for your agents. Let's take a look at what your first agent might look like.

KnowItAllAgent.java

@PeoplelogicAgent(value="coordinatorAgent",
        name = "Know It All Agent",
        persona = "Funny but a bit snarky")
public interface AllInOneAgent extends WorkerAgent, CoordinatorAgent {
    @SystemMessage(BASE_COORDINATOR_PROMPT)
    BaseAssignmentHolder assign(@MemoryId String userId, @UserMessage String userMessage, @V("InConversation") String inConversation, @V("Agent") String agent);

    @SystemMessage(BASE_WORKER_PROMPT)
    Result<PeoplelogicResult> acceptWork(@MemoryId String userId, @UserMessage String query, @V("previousResponse") String agentResponse);
}

Don't worry if this seems a little overwhelming, we'll get to explanations of all the annotations and methods shortly! In reality you will only need to override the methods that you want to customize, but let's walk through what all this means:

@PeoplelogicAgent

This annotation is the meat and potatoes of your Agent definition. It contains all the configuration you need to setup your agents and can even use SPEL expressions to grab externalized properties (we'll show this more later!). The value must be unique and there must always be one with the value coordinatorAgent. The coordinator agent is the one that parses out all the agent work - even if its to itself. The rest of your agents can have whatever value you desire.

BaseAssignmentHolder assign()

Please pay attention the annotations on the parameters in the method implementation - these are required.

This method is called on the CoordinatorAgent when you send a new question or task into the SDK. The CoordinatorAgent knows about all the other agents in your application and the BASE_COORDINATOR_PROMPT is generally sufficient for most tasks provided you've included sufficient instructions to your worker agents and can handle assigning to one agent or many.

During assignment, no tools will be called, unlike the acceptWork call - this call is entirely about delegating work somewhere else.

Additionally, for the SystemMessage annotation you could also have referenced a prompt file from your resources folder to externalize the handling of the prompts.

Result<PeoplelogicResult> acceptWork()

The acceptWork method is the main entry point to a WorkerAgent and in most of your actual agents will be in a separate class with its own unique agent. The system prompt on this method is all about executing the work for the task that has been assigned to it. You will often use it to help the LLM choose tools more effectively or return a response in a more specific format.

You will almost always want to provide your own SystemMessage prompt here as this is work all the magic happens!

Similarly to the assign method, you can reference an external prompt file and the annotations on the method parameters are important!

Running your new agent

For the purposes of this documentation we'll be using OpenAI to run our agents. We'll explore using other LLMs later in the documentation.

Now that you've built your first agent - you're ready to put it to work. First, we have just a smidge of configuration to do. You'll need to open up resources/application.properties and enter your OpenAI key.

You'll also notice that the sample has the application profile set to cli,cli-interactive . We'll explore these in more detail later, but these profiles control how you'll interact with your agents.

With that set, now you just need to run with the command ./gradlew bootRun . You should see output similar to the output below:

______                _      _             _      
| ___ \              | |    | |           (_)     
| |_/ /__  ___  _ __ | | ___| | ___   __ _ _  ___ 
|  __/ _ \/ _ \| '_ \| |/ _ \ |/ _ \ / _` | |/ __|
| | |  __/ (_) | |_) | |  __/ | (_) | (_| | | (__ 
\_|  \___|\___/| .__/|_|\___|_|\___/ \__, |_|\___|
               | |                    __/ |       
               |_|                   |___/        

 :: Spring Boot ::                (v3.5.3)
 :: Peoplelogic Agent SDK ::   (v1.0.7.22)

2025-07-16T18:53:57.625-04:00  WARN 99149 --- [           main] o.s.c.annotation.AnnotationTypeMapping   : Support for convention-based annotation attribute overrides is deprecated and will be removed in Spring Framework 7.0. Please annotate the following attributes in @ai.peoplelogic.agents.common.spring.PeoplelogicAgent with appropriate @AliasFor declarations: [wiringMode]
2025-07-16T18:53:58.787-04:00  INFO 99149 --- [           main] org.flywaydb.core.FlywayExecutor         : Database: jdbc:h2:file:./data/peoplelogic-agent-sdk (H2 2.3)
2025-07-16T18:53:58.815-04:00  INFO 99149 --- [           main] o.f.core.internal.command.DbValidate     : Successfully validated 10 migrations (execution time 00:00.018s)
2025-07-16T18:53:58.820-04:00  INFO 99149 --- [           main] o.f.core.internal.command.DbMigrate      : Current version of schema "public": 1.0.8
2025-07-16T18:53:58.822-04:00  INFO 99149 --- [           main] o.f.core.internal.command.DbMigrate      : Schema "public" is up to date. No migration necessary.
2025-07-16T18:54:00.316-04:00  WARN 99149 --- [           main] org.jline                                : Unable to create a system terminal, creating a dumb terminal (enable debug logging for more information)
peoplelogic:>

This is the interactive CLI for the agent SDK. Now just ask the agent something simple with q what is your name? . This sends your question or task to the SDK which assigns to your one agent and then proccesses it. In a moment you should get back an answer:

peoplelogic:>q what is your name?
agent:> My name is Know It All Agent. Yes, that's actually my name—it's tough being this humble and informative all at once. What can I help you with today?

And now you have a running agent - a simple one, but we've shown a great deal of flexibility in a very simple package. Now let's start to see how we can get more advanced - onward!