Akka Agent Generator: Natural Language to Deployed Akka Agent

The Akka Agent Generator is a Java 21 system that takes a natural language description of a desired agent and produces a deployed, functional Akka Typed agent. The pipeline is linear: parse the natural language query, generate Java source code following Akka agent structural patterns, compile in-process via javax.tools (no subprocess), optionally enhance the output with Claude AI, then deploy to local, Docker, or Kubernetes environments.

The system is built on Spring Boot and Akka Typed 2.8.5. A weather reporting agent ships as the reference implementation, demonstrating the full round-trip from natural language input to a running, queryable agent.

Why is it useful?

Akka Typed agent code has a precise structural contract: extend Agent, annotate with @ComponentId, implement command handlers returning Effect<T>, register function tools. This structure is regular enough that a code generation system can produce correct agents from intent descriptions without requiring the author to internalize the full Akka Typed API surface.

By compiling in-process rather than forking a Maven subprocess, we avoid the startup cost of a full build process per generation. In-process compilation via javax.tools runs in milliseconds, which means the feedback loop from description to running agent is short enough to support iterative refinement. The multi-environment deployment layer means a generated agent moves from prototype to staging to production without manual configuration changes between environments.

How and where does it apply?

The generator is internal tooling for accelerating Worksona agent development. When a new agent capability is needed, the generator produces a structurally correct starting point in seconds rather than hours of boilerplate. We use it to establish the skeleton — correct annotations, correct method signatures, correct effect chain — and then refine the domain logic.

The optional AI enhancement gate applies Claude to the generated source before compilation. In this pass, Claude adds error handling, improves method naming, and adapts the function tool implementations to the specific domain described in the natural language input. The gate is optional because not every generation task benefits from the additional latency; straightforward agents with well-understood function tools can skip directly to deployment.

The system is also a reference implementation for teams learning Akka Typed patterns. Reading generated agents alongside their natural language descriptions is a practical way to understand the mapping between intent and structure.

graph LR
    A[Natural Language Query] --> B[CodeGeneratorService<br/>parse + template]
    B --> C[Java Source Code]
    C --> D[javax.tools Compiler<br/>in-process]
    D -->|pass| E{AI Enhancement?}
    E -->|yes| F[Claude Refinement]
    E -->|no| G[DeploymentService]
    F --> G
    G --> H[Local / Docker / K8s]

The generated agent skeleton below is the structural contract the generator must satisfy. Every field is load-bearing: @ComponentId registers the agent with the Akka runtime, handleUserMessage is the entry point for all inbound messages, and @FunctionTool exposes callable capabilities to the orchestration layer.

@ComponentId("weather-agent")
public class WeatherAgent extends Agent {

  @Override
  public Agent.Effect<String> handleUserMessage(String message) {
    return effects()
      .callFunctionTool("getCurrentWeather", message)
      .thenReply(result -> "Current conditions: " + result);
  }

  @FunctionTool(description = "Get current weather for a location")
  public String getCurrentWeather(String location) {
    // Generated implementation
    return weatherService.fetch(location);
  }
}

The generator produces this skeleton correctly on every run. The Claude enhancement pass then fills in the implementation body, adapts the tool description to the actual domain, and adds the exception handling that the template deliberately omits.