Skip to main content
Version: Next — Unreleased

Quick start

This guide gets a minimal AgentForge4j workflow running in an existing Java application. Every code block below is included from the runnable quick-start example, so it always matches source.

1. Provide a workflow definition​

Author a workflow JSON document, validated against the workflow schema:

quick-start.workflow/workflow.json
{
  "kind": "WORKFLOW",
  "schemaVersion": 1,
  "id": "quick-start",
  "name": "Quick Start",
  "description": "A single agent step that completes immediately — the shortest runnable workflow.",
  "steps": [
    {
      "kind": "STEP",
      "stepId": "greet",
      "name": "Greet",
      "behaviour": {
        "type": "AGENT",
        "agentRef": "quick-start-agent",
        "transition": "AUTO"
      }
    }
  ]
}

2. Assemble the runtime​

Wire the framework to your workflow and agent directories and an LLM provider, then build the facade:

QuickStartExample.java
FakeScript script = new FakeScript(1, Map.of(
    new FakeScriptKey(WORKFLOW_ID, STEP_ID, AGENT_ID, 0),
    new FakeResponse(SCRIPTED_COMPLETE, null)));
LlmClient fakeLlmClient = new FakeLlmClient(new StaticFakeResponseSource(script));

return AgentForge4jBootstrap.defaults()
    .withWorkflowsDir(resourceDirectory("/workflows"))
    .withAgentsDir(resourceDirectory("/agents"))
    .withLoadShippedWorkflows(false)
    .withLoadShippedAgents(false)
    .withLlmClientResolver(new DefaultLlmClientResolver(List.of(fakeLlmClient)))
    .build();

3. Run it​

Start the workflow and read its terminal state:

QuickStartExample.java
AgentForge4j agentForge4j = assemble();

String runId = agentForge4j.start(WORKFLOW_ID);
WorkflowState state = agentForge4j.runtime().getState(runId);

System.out.printf("Workflow '%s' (run %s) finished with status: %s%n", WORKFLOW_ID, runId, state.getStatus());
System.out.printf("Step outputs: %s%n", state.getStepOutputs());

See Configure an LLM provider to swap the deterministic test provider for a real one.

Next steps​