How to Build an AI Agent With the GitHub Copilot SDK for Java

AI coding tools have changed quite a bit. They are no longer limited to answering questions or suggesting a line of code. An agent can look at a task, decide what it needs to do, call tools, inspect files, and continue working based on the result.

That becomes interesting when you want to put this kind of workflow inside your own Java application.

Instead of asking a developer to open a chat window and copy the answer into an application, you can build a Java service that starts an agent, gives it a task, and handles the response from your own code.

The GitHub Copilot SDK is designed for this type of integration. In this article, we will look at the basic idea and build a small Java example to understand how an agent-based workflow fits into a Java application.

What We Are Building

Let's keep the example practical.

Suppose we have a Java application that receives a developer request such as:

Review the OrderService.java file and list possible problems.

Our application sends that task to an AI agent.

The basic flow is:

Java Application
       |
       v
Copilot SDK
       |
       v
AI Agent
       |
       v
Available Tools
       |
       v
Files / Project Data
       |
       v
Agent Response
       |
       v
Java Application

The Java application remains in control of the workflow. The agent is responsible for working through the task.

Why Use an SDK Instead of Calling an AI API Directly?

A normal LLM integration often looks like this:

Application
    |
    v
Prompt
    |
    v
Model
    |
    v
Text Response

That works well for many applications.

An agent is different because it may need to perform several steps:

Read task
   |
   v
Inspect available information
   |
   v
Choose an action
   |
   v
Use a tool
   |
   v
Read the result
   |
   v
Continue
   |
   v
Return answer

An SDK can handle much of the interaction between your application and the agent runtime, rather than forcing you to build the entire loop yourself.

For Java developers, that means the agent can become another component of the application instead of being something that only exists in a separate developer tool.

Basic Project Setup

A simple Maven project is enough to start.

The project could look like this:

copilot-agent-demo/
├── pom.xml
└── src/
    └── main/
        └── java/
            └── com/
                └── example/
                    └── App.java

The exact SDK artifact and version should be taken from the current GitHub Copilot SDK documentation because SDK packages and APIs can change.

Conceptually, your Maven project needs the Copilot SDK dependency:

<dependency>
    <groupId>...</groupId>
    <artifactId>...</artifactId>
    <version>...</version>
</dependency>

Do not copy an old version number from a blog post into a production project without checking the current package information.

Start With the Agent Session

The first thing the application needs is an agent session.

The exact class and method names depend on the SDK version you are using, but the workflow is roughly:

var client = new CopilotClient();

var session = client.createSession();

var response = session.send(
    "Review OrderService.java and explain any problems you find."
);

System.out.println(response);

The important part is not the exact syntax.

The important idea is that the Java application creates a session and sends work to the agent through that session.

A session also gives you a place to keep related interactions together.

Give the Agent a Clear Task

One mistake I see often in AI integrations is sending a vague instruction and expecting the model to figure out everything.

For example:

Review this project.

That leaves too many questions.

Which files?

What type of problems?

Should it change anything?

Should it only report issues?

A better request might be:

Review OrderService.java.

Look for:
1. Null handling problems
2. Database-related issues
3. Unnecessary repeated calls
4. Exception handling problems

Do not modify any files.
Return a short list of findings with the relevant method names.

The agent now has a much clearer job.

This matters even more when the agent has permission to modify files or call external tools.

Working With Files

An agent becomes much more useful when it can work with project files.

For example, a developer might ask:

Find where OrderService is used and explain whether changing
the constructor would affect other parts of the application.

The agent may need to:

Find OrderService
       |
       v
Search project
       |
       v
Find references
       |
       v
Read related files
       |
       v
Build an answer

This is different from sending the source code manually inside a prompt.

The application can give the agent access to the project context and let the agent use the tools available to it.

Tool Access Needs to Be Controlled

This is one of the areas that should not be overlooked.

If an agent can read files, write files, execute commands, or interact with external services, those capabilities need to be limited.

For example, a code-review agent may only need:

Read files
Search files

It probably does not need:

Delete files
Deploy application
Change infrastructure
Modify production database

Think about the agent like a junior developer working inside your repository.

Give it the tools required for the job, not every tool available on the machine.

A Simple Java Service

Rather than putting all the agent code in main(), you can wrap it in a service.

For example:

public class CodeReviewService {

    private final CopilotClient client;

    public CodeReviewService(CopilotClient client) {
        this.client = client;
    }

    public String review(String request) {

        var session = client.createSession();

        var response = session.send(request);

        return response;
    }
}

Then your application can call:

var reviewService = new CodeReviewService(client);

String result = reviewService.review(
    "Review OrderService.java for exception handling problems."
);

System.out.println(result);

This separation makes it easier to test the rest of the application without having agent-specific code spread across different classes.

Handling Long-Running Agent Work

Agent tasks can take longer than a normal method call.

A task such as:

Inspect the repository, find all database access classes,
review them, and summarize possible performance problems.

may involve several operations.

For that reason, production applications should think about:

• timeouts

• cancellation

• retries

• logging

• partial failures

• user feedback

For example:

try {
    String result = reviewService.review(request);

    System.out.println(result);

} catch (Exception ex) {
    System.err.println(
        "Agent request failed: " + ex.getMessage()
    );
}

The real application should use more specific exception handling, but even this simple example shows an important point: an agent call is an external dependency and should not be treated like a guaranteed local method call.

Streaming Can Improve the User Experience

For an interactive application, waiting for the complete response can feel slow.

If the SDK supports streaming events, you can process output as it arrives.

Conceptually:

session.onMessage(message -> {
    System.out.print(message);
});

This can be useful for:

• IDE extensions

• developer dashboards

• internal support tools

• command-line applications

• web applications

Instead of:

Wait...
Wait...
Wait...
Complete response

the user can see the agent making progress.

The exact event APIs depend on the SDK version, so check the current SDK documentation before implementing this part.

Give the Agent Context, Not Everything

More context does not automatically produce a better result.

Suppose the task is to review one Java class.

Sending an entire large repository may add noise and increase processing cost.

Start with the information needed for the task.

For example:

Task:
Review OrderService.java.

Focus:
- exception handling
- database calls
- transaction boundaries

Do not modify files.

If the agent needs additional files, it can inspect them when necessary.

This is usually easier to reason about than creating one huge prompt containing the entire project.

Keep Instructions Separate From User Data

If your application receives a request from a user, do not blindly combine that input with privileged instructions.

For example:

String prompt = """
You are a code review assistant.
Do not modify files.

User request:
%s
""".formatted(userRequest);

Even here, the application should still validate what operations are allowed.

If the user asks:

Delete all files in the repository.

the Java application should not suddenly grant the agent file-deletion access.

The prompt is not a security mechanism.

Tool permissions and application authorization should enforce the actual boundaries.

Logging Agent Activity

When an agent performs several operations, debugging can become difficult without logs.

A useful log might contain:

RequestId: 91a72
Agent: code-review
Task: Review OrderService.java
Tool: file-search
Result: 8 matches
Tool: file-read
File: OrderService.java
Result: success
Final response: generated

Avoid logging sensitive source code, credentials, tokens, or other confidential information unnecessarily.

The goal is to understand what the agent did without creating another security problem.

Testing an Agent Is Different From Testing a Normal Method

A normal Java method might produce the same result for the same input.

An AI agent can behave differently depending on the model, context, available tools, and intermediate results.

That means tests should focus on things such as:

Can the agent complete the task?
Does it stay within its tool permissions?
Does it handle missing files?
Does it avoid modifying files when instructed not to?
Does it return a useful result?

For example, a test scenario could be:

Task:
Review CustomerService.java.

Expected:
- No file changes
- No shell commands
- Identify null handling issue
- Return a structured summary

You can then verify both the answer and the actions taken by the agent.

Common Mistakes

Giving the Agent Too Much Access

If the application only needs file analysis, do not expose deployment or administrative tools.

Treating the Agent Response as Always Correct

An agent can misunderstand a task or make an incorrect technical conclusion.

Important changes should still go through normal review and testing.

Putting Secrets in the Prompt

API keys, passwords, and tokens should never be passed to the model just because the agent needs to call a service.

Use application-side authentication instead.

Skipping Timeouts

A request that depends on an external model or tool can take longer than expected.

Set reasonable time limits.

Building Everything Around One Prompt

As the application grows, move important rules into code, authorization policies, tool definitions, and tests instead of continuously making the prompt larger.

Where a Java-Based Agent Can Be Useful

There are many practical uses for this pattern.

Code Review

A Java service can submit files or repository tasks to an agent and return a review.

Documentation

An agent can inspect Java classes and help generate documentation or explain unfamiliar code.

Developer Support

Internal tools can let developers ask questions about a company's codebase.

Issue Triage

An agent can inspect an issue, search relevant code, and suggest likely areas that need investigation.

Test Assistance

An agent can inspect a class and suggest missing test cases.

The key is to keep the agent's responsibilities narrow enough that the results can be checked.

A Practical Architecture

A production application could eventually look like this:

                    Java Application
                           |
                           v
                    Agent Service
                           |
                           v
                   Copilot SDK
                           |
                           v
                      AI Agent
                    /    |     \
                   /     |      \
                  v      v       v
              File     Search    Other
              Tools    Tools     Tools
                |        |         |
                +--------+---------+
                         |
                         v
                  Application Data

Add authorization before sensitive tools:

Agent
  |
  v
Tool Request
  |
  v
Authorization
  |
  +---- No ----> Reject
  |
 Yes
  |
  v
Validation
  |
  v
Tool Execution

That extra layer becomes important as soon as the agent can do more than read information.

Conclusion

The GitHub Copilot SDK makes it possible to bring an agent-style development workflow into your own application instead of keeping it limited to a separate coding interface.

For Java developers, the basic idea is straightforward:

1. Create the SDK client.

2. Start an agent session.

3. Give the agent a clear task.

4. Provide only the tools it needs.

5. Handle the response in your application.

6. Add timeouts, logging, and error handling.

7. Test both the agent's output and its actions.

The most important part is not writing the first agent call. It is deciding what that agent is allowed to see and do.

Start with a small task, keep the tool set narrow, and expand its permissions only when the application actually needs them.