Interface Agent

All Known Implementing Classes:
ComponentPropsAgent, ComposedAgent, FileResourceEditorAgent, InstanceWizardAgent, NamedQueryAgent, QueryBrowserAgent, ScriptingAgent, UdtEditorAgent

public interface Agent
Configures an AI agent: its system prompt, the tools it can call, and any supplemental context that shape its behavior. The configuration is consumed by whatever runtime drives the conversation with the model and dispatches tool calls back through the agent's CallableTools.

Each Agent type is paired with an Agent.AgentFactory that builds fresh instances on demand. Modules wire their factories directly into the call sites that need them — typically through AiContext.newAgenticHarness(String, String, Agent.AgentFactory) for one-shot harnesses, or through module-specific managers for resource-backed agents.

Example:

public class WeatherAgent implements Agent {
  public static final String TYPE_ID = "com.example.weather";

  @Override
  public String getTypeId() {
    return TYPE_ID;
  }

  @Override
  public String getName() {
    return "Weather Agent";
  }

  @Override
  public String getDescription() {
    return "Im a weather agent which can tell you the weather forecast for a given city.";
  }

  @Override
  public String getSystemPrompt() {
    return "You answer weather questions for a given city.";
  }

  @Override
  public List<CallableTool> getTools() {
    return Tools.fromAnnotated(new WeatherTools());
  }

  @Override
  public Optional<String> getAdditionalContext() {
    return Optional.empty();
  }
}

// Pass the factory directly to whichever consumer needs fresh instances of this agent:
aiContext.newAgenticHarness("openai", "gpt-4o", WeatherAgent::new).build();
  • Method Details

    • getTypeId

      String getTypeId()
      Stable type identifier for this agent type. Useful for diagnostics and routing.
    • getName

      String getName()
      Human-readable name used in logs and routing.
    • getDescription

      String getDescription()
      Human and Agent readable description used in logs and routing.
    • getSystemPrompt

      String getSystemPrompt()
      System prompt that primes the model for this agent's role.
    • getTools

      List<CallableTool> getTools()
      Callable tools exposed to the model. Typically built from Tool-annotated methods via Tools.fromAnnotated(Object...), but may include hand-rolled CallableTool implementations. Returns an empty list if the agent declares no tools.
    • getAdditionalContext

      Optional<String> getAdditionalContext()
      Supplemental context to be folded into the prompt (e.g. project state, schema, current selection), or empty if none is provided.
    • getMaxTurnsPerInvocation

      default int getMaxTurnsPerInvocation()
      Maximum number of model turns — tool-calling rounds — the harness runs in a single invocation before it stops the loop. A single turn may run several tools at once, so this bounds rounds, not individual tool calls. Defaults to 20; agents backed by user config override this with their configured value. The harness additionally caps this at its own hard ceiling.
    • toBuilder

      default ComposedAgent.Builder toBuilder()
      Creates a new instance of ComposedAgent.Builder pre-populated with the current state of this agent.
      Returns:
      a builder initialized with this agent's data, allowing modifications and the creation of a new ComposedAgent instance.
      See Also:
      • invalid reference
        ComposedAgent.Builder#builder(Agent)