Skip to content

getting-started.md

Latest commit

 

History

History
146 lines (114 loc) · 3.55 KB

getting-started.md

File metadata and controls

146 lines (114 loc) · 3.55 KB

Getting Started with Autohand Java SDK

Prerequisites

  1. Java 21 or later installed
  2. Maven 3.9 or later
  3. Autohand CLI binary available on your system or in the cli/ directory

Official Agent SDK docs: https://autohand.ai/docs/agent-sdk/

Installation

Maven

Add the dependency to your pom.xml:

<dependency>
    <groupId>ai.autohand</groupId>
    <artifactId>code-agent-sdk-java</artifactId>
    <version>1.0.0</version>
</dependency>

Local Build

cd java/
mvn clean install

Configuration

SDK Configuration

SDKConfig config = SDKConfig.builder()
    .cwd(".")
    .cliPath(System.getenv("AUTOHAND_CLI_PATH"))
    .model("openrouter/auto")
    .appendSystemPrompt("Prefer concise Java examples.")
    .build();

CLI Configuration

The SDK uses the CLI's configuration file (~/.autohand/config.json). You can configure providers there:

{
  "provider": "openrouter",
  "openrouter": {
    "apiKey": "sk-or-...",
    "model": "openrouter/auto"
  }
}

Your First Agent

import ai.autohand.sdk.sdk.Agent;
import ai.autohand.sdk.sdk.AgentOptions;
import ai.autohand.sdk.types.*;

public class HelloAgent {
    public static void main(String[] args) throws Exception {
        Agent agent = Agent.create(AgentOptions.builder()
            .cwd(".")
            .model("openrouter/auto")
            .instructions("Be concise and helpful.")
            .build());

        try {
            var run = agent.send("Explain what this SDK does");

            run.stream(event -> {
                if (event instanceof Events.MessageUpdateEvent mue) {
                    System.out.print(mue.delta());
                }
            });

            System.out.println("\nDone!");
        } finally {
            agent.close();
        }
    }
}

Event Types

The SDK emits the following events via sealed interface Event:

  • AgentStartEvent - Agent started a session
  • AgentEndEvent - Agent ended a session
  • TurnStartEvent - Turn started
  • TurnEndEvent - Turn ended
  • MessageStartEvent - Message generation started
  • MessageUpdateEvent - Message content update (streaming)
  • MessageEndEvent - Message generation ended
  • ToolStartEvent - Tool execution started
  • ToolUpdateEvent - Tool output update (streaming)
  • ToolEndEvent - Tool execution ended
  • FileModifiedEvent - File was modified
  • PermissionRequestEvent - Permission request from agent
  • ErrorEvent - Error occurred

Use pattern matching to handle events:

run.stream(event -> {
    switch (event) {
        case Events.MessageUpdateEvent mue -> System.out.print(mue.delta());
        case Events.ToolStartEvent tse -> System.out.println("Running: " + tse.toolName());
        case Events.PermissionRequestEvent pre -> handlePermission(pre);
        default -> {}
    }
});

Permission Handling

sdk.streamPrompt(params, event -> {
    if (event instanceof Events.PermissionRequestEvent pre) {
        System.out.println("Allow " + pre.tool() + "?");
        sdk.allowPermission(pre.requestId(), DecisionScope.SESSION);
    }
});

Ergonomic helpers:

sdk.allowPermission(requestId, DecisionScope.ONCE);
sdk.denyPermission(requestId, DecisionScope.SESSION);
sdk.suggestPermissionAlternative(requestId, "Run mvn test first");

Next Steps

  • See examples/ for more examples
  • Read docs/advanced-patterns.md for streaming, plan mode, and hooks
  • Read docs/publishing.md for Maven Central release setup
  • Run scripts/validate-examples.sh before changing example code