26 docs tagged with "how-to"

Walks you through a minimal but real Agent main path: AgentBuilder default wiring, the ReActRuntime step loop, AgentModelClient protocol adaptation, AgentMemory write-back, and AgentResult convergence.

Explains ai4j-agent Skills: how the SDK discovers and scopes SKILL.md, the workspace-safe vs user-home roots, request-scoped AgentSkillResolver for tenants, and why Skills never bypass tool authorization.

Shortest path to confirm starter wiring, task API exposure, and two minimal flows (without and with an LLM) running the full validate -> run -> result -> report chain, plus pitfalls in the demo's default model configuration and a troubleshooting order.

Explains how AI4J uses the @McpService/@McpTool annotations, adapters, and McpServerEngine to publish Java capabilities as an MCP Server, covering the real differences across the Tool/Resource/Prompt capability chains and the three server-side transports.

Recommended deployment for the AI4J docs site: Docusaurus + Cloudflare Pages + a custom domain. Covers GitHub-integrated automatic builds, global CDN delivery, the free tier, custom domain configuration, and the continuous release flow.

The shortest path to get ai4j-cli running: build the fat jar, run a one-shot and a persistent session, and verify session, workspace, and provider/model state for a minimum validation.

How to contribute to AI4J — reporting issues, proposing changes, running docs-site local checks and Java module tests, and following the security disclosure policy.

Uses a weather-analysis two-agent workflow to clarify SequentialWorkflow's outputText relay, the WorkflowContext side channel, per-node session isolation, and minimal observation via NamedNode, plus when to upgrade to StateGraphWorkflow.

Custom nodes are how a capability is formally wired into the Flowgram front-end and back-end execution contract: the back-end FlowGramNodeExecutor extension point, the getType protocol name, input/output contract stability, and the three things that must land together on both sides.

Covers only the backend executor half: the FlowGramNodeExecutor interface, runtime recognition and registration timing, getType protocol-name stability, and the input parsing and context fields the runtime has already completed before execute.

Turning a new node in ai4j-flowgram-webapp-demo into an editable, validatable, serializable, backend-mappable frontend node: type enum, FlowNodeRegistry, the onAdd schema factory, and backend type mapping.

Explains IImageService image generation and streaming listener usage, covering OpenAI and Doubao adapters, request fields, the event model, and common integration issues.

Distinguishes the three layers of the Coding Agent — build, Maven release, and end-user CLI installation — notes that the repo already ships a fat jar and platform launchers, and names the fat jar as the most stable distribution baseline along with the current release gaps.

The interception layer of ai4j-agent: ToolInterceptor (block/modify/routeTo sandbox) and PromptInterceptor map to Claude Code's PreToolUse/PostToolUse/UserPromptSubmit, plus observe-only lifecycle hooks, with a hooks facade and CLI configuration.

Explains the sixth plugin capability, ExtensionCapability.LIFECYCLE: plugins register an AgentLifecycleHook via context.lifecycle().register(hook) to receive AgentLifecycleEvent at session/turn/model/tool/compact event points, used for observation, telemetry, and auditing — it contributes no tools or resources.

Explains Claude-Code-style shell-command lifecycle hooks (PreToolUse/PostToolUse/UserPromptSubmit/Stop/PreCompact/SessionStart/SessionEnd): their configuration, intercept vs. observe routing, and exit code protocol, plus the workspace trust gate and the ai4j-cli trust command that let these hooks load safely.

Break down the 7-layer execution chain a third-party MCP travels from config file into the Agent reasoning loop until it is finally invoked by the model, covering projection, call dispatch, multi-tenant fallback, and trace diagnostic points.

Focused on single-server mode: the real lifecycle of McpClient, what connect() does and how AUTO differs from the legacy profile, caching and heartbeat/reconnect semantics, callTool failure semantics, and common troubleshooting paths.

Covers IMusicService music generation usage: submitMusic/submitLyrics to submit tasks, fetch to poll task results, Suno adapter, task lifecycle, field model, and polling notes.

A hands-on guide for third-party plugin authors: use the CLI to generate a minimal plugin project, stabilize the manifest and public ID naming rules, write a structured tool input schema, keep apply() as a lightweight registration function, and complete manifest/resource/schema validation and pre-release declarations.

Assembly recipes for plugin consumers: after the jar is on the classpath, how to use CLI plan/check for pre-wiring checks, with enable/allow/expose configuration for Java, Spring Boot, Agent, Coding Agent, and multi-plugin combinations, distinguishing command and tool exposure semantics.

The shortest path to integrate AI4J into a plain Java / Maven project: from dependencies and environment variables to your first synchronous Chat request, with copy-ready Configuration→AiService→IChatService closed-loop code and success criteria.

The shortest path to wire AI4J into a Spring Boot project: pull in the starter, write a minimal application.yml, inject the AiService Bean, and ship a complete controller that sends the first model request.

The shortest path to a working AI4J integration in Spring Boot: add the starter, configure ai.*, inject AiService, and issue your first ChatCompletion.

AI4J production troubleshooting entry point. Instead of listing every exception stack, it locates problems to the right page and checklist by capability layer: model call failures check provider key; Chat works but Responses doesn't, check provider support; Streaming has no incremental output, check the consumption pattern.

Explains IVideoService video generation usage: create to submit a task, retrieve to poll status, content to fetch the result byte stream, and remix to rework; covers the OpenAI-compatible gateway, multipart submission, and the async polling model.