> ## Documentation Index
> Fetch the complete documentation index at: https://phaseo.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage

> Define tools, run a Java agent, and resume after human review.

## Tool loop

```java theme={null}
import app.phaseo.agent.AgentSdk;
import java.util.List;
import java.util.Map;

var lookup = AgentSdk.defineTool(new AgentSdk.Tool(
    "lookup_docs",
    (input, context) -> Map.of("article", "Presets keep routing stable."),
    "Look up a documentation article",
    Map.of("type", "object"),
    java.time.Duration.ofSeconds(10)
));

var agent = AgentSdk.createAgent(new AgentSdk.AgentDefinition(
    "support-agent",
    "openai/gpt-5.4-nano",
    null,
    "Use tools when useful and answer concisely.",
    List.of(lookup),
    12,
    null,
    null,
    new AgentSdk.ModelRetryConfig(2, java.time.Duration.ofMillis(250)),
    new AgentSdk.ToolExecutionConfig(4)
));

var result = agent.run(new AgentSdk.RunOptions(
    "Explain presets",
    AgentSdk.createGatewayAgentClient(),
    null, null, null, null, null, null,
    event -> System.out.println(event.type()),
    AgentSdk.createAgentDevtools(".phaseo-devtools")
));
```

## Human review

Return `HumanReviewRequest` from `AgentDefinition.humanReview` to checkpoint a run. Persist the returned `RunResult`, collect a decision in your application, then call `continueRun(...)` with `humanInput`. The Agent SDK does not depend on hidden hosted state.

## Responses API options

Pass additional Responses API fields through `GatewayOptions.requestOptions`. Agent-owned `model`, `input`, `instructions`, and local function tools are applied by the adapter.

## Advanced runtime

Java supports validator and approval interfaces, HITL and manual tools, progress, recoverable errors, replayable iterables, stop helpers, dynamic turns, persisted `NextTurnParams`, normalized usage/cost, and `StateAccessor`.

## Streaming and cancellation

`Agent.stream(...)` and `Agent.continueStream(...)` consume the gateway's Responses SSE stream. Read `textStream()` or `fullStream()` for replayable results, and call `cancel()` to interrupt the active worker and HTTP read. Completed steps retain request IDs, provider metadata, finish reasons, warnings, usage, and cost.

## Related

* [Agent SDK overview](../agent-sdk/overview)
* [Java Client SDK](./overview)