volcengine/veadk-java

Dernière activité source enregistrée: 10 octobre 2026 à 09:15

Catalogue SkillsMP mis à jour: 5 novembre 2026 à 19:57

skills collectés: 2

Étoiles GitHub: 115
Forks GitHub: 10

Installer avec un assistant IA

Copiez ce prompt dans l’assistant IA que vous utilisez.

Follow https://skillsmp.com/skill-install/prompt.md to install Agent Skills from https://github.com/volcengine/veadk-java.

README du dépôt

Fichier source du README : README.md

Lire le README source

Afficher le README complet

# veadk-java An open-source Agent development toolkit that integrates the powerful capabilities of Volcengine. ## Quick Start ### Requirements - JDK `17` or above ```xml <dependency> <groupId>com.volcengine.veadk</groupId> <artifactId>veadk-java</artifactId> <version>0.0.2</version> </dependency> ``` ### Agent Use `Agent.builder()` as the VeADK Java entry point. It keeps the ADK Java `LlmAgent` execution path, while adding VeADK defaults and metadata that integrations can read without reflection. ```java import com.volcengine.veadk.Agent; Agent agent = Agent.builder() .name("quickstart-agent") .description("Answers user questions.") .instruction("You are a helpful assistant.") .model("doubao-seed-2-1-pro-260628") .modelApiKey(System.getenv("MODEL_AGENT_API_KEY")) .build(); ``` Without an explicit provider, VeADK follows veadk-python and uses the OpenAI-compatible path by default. Configure the API key with `modelApiKey(...)`, or leave it unset to read `MODEL_AGENT_API_KEY` from the environment. The default base URL is Ark's OpenAI-compatible endpoint; use `modelApiBase(...)` / `modelBaseUrl(...)` when you need OpenAI official, LiteLLM Proxy, or another compatible gateway. OpenAI-compatible endpoints are configured the same way, without requiring application code to construct an ADK `BaseLlm`: ```java Agent agent = Agent.builder() .name("openai-agent") .instruction("You are a helpful assistant.") .model("openai/gpt-4o") .modelApiKey(System.getenv("OPENAI_API_KEY")) .modelBaseUrl("https://api.openai.com/v1") .build(); ``` Use `modelProvider("ark")` only when you want the Ark-specific `ArkLlm` adapter: ```java Agent agent = Agent.builder() .name("ark-agent") .modelProvider("ark") .model("doubao-seed-2-1-pro-260628") .modelApiKey(System.getenv("MODEL_AGENT_API_KEY")) .modelApiBase("https://ark.cn-beijing.volces.com/api/v3") .build(); ``` For LiteLLM Proxy or an internal OpenAI-compatible gateway, set the base URL to that endpoint. Use `modelProvider("openai")` when the model name itself contains provider routing text: ```java Agent agent = Agent.builder() .name("litellm-agent") .modelProvider("openai") .model("anthropic/claude-sonnet-4") .modelApiKey(System.getenv("LITELLM_API_KEY")) .modelBaseUrl("http://localhost:4000/v1") .build(); ``` You can also provide an explicit ADK `BaseLlm` instance when you want to own the model configuration yourself: ```java import com.google.adk.models.BaseLlm; import com.volcengine.veadk.Agent; import com.volcengine.veadk.model.ArkLlm; BaseLlm model = new ArkLlm("doubao-seed-2-1-pro-260628"); Agent agent = Agent.builder() .name("custom-model-agent") .instruction("You are a helpful assistant.") .model(model) .build(); ``` Metadata is available through a typed extractor. For VeADK `Agent` instances it uses `Agent.metadataSnapshot()`; for plain ADK `LlmAgent` instances it falls back to public ADK getters. ```java import com.volcengine.veadk.AgentMetadata; import com.volcengine.veadk.AgentMetadataExtractor; AgentMetadata metadata = AgentMetadataExtractor.extract(agent); System.out.println(metadata.tools()); ``` For a simple blocking interaction, use the VeADK runner convenience API: ```java import com.volcengine.veadk.Runner; String answer = new Runner(agent).run("Hello"); ``` #### Local Skills Local skills are supported through ADK Java's `SkillToolset`. When `Agent.builder().skills(...)` is configured, VeADK Java automatically injects one `SkillToolset` unless the user already passed an explicit `SkillToolset` through `tools(...)`. A skill is a directory containing a required `SKILL.md` file: ```text skills/ expense-policy-reviewer/ SKILL.md references/ assets/ scripts/ ``` The `SKILL.md` file must start with frontmatter whose `name` matches the skill directory name: ```markdown --- name: expense-policy-reviewer description: Review employee reimbursement requests against the company policy. --- Follow the reimbursement policy and produce a concise review. ``` Pass a skills root directory, a single skill directory, a `SKILL.md`/`skill.md` file, or an explicit ADK `SkillSource`: ```java import java.nio.file.Path; Agent agent = Agent.builder() .name("expense-review-agent") .instruction("Use local skills before answering policy questions.") .modelName("doubao-seed-2-1-pro-260628") .skills(Path.of("example/src/main/resources/skills")) .skillsMode("local") .build(); ``` Supported entries for `skills(...)` are: - `Path` or `String`: local filesystem path. A directory with `SKILL.md` or `skill.md` is treated as one skill; otherwise the directory is treated as a skills root containing skill subdirectories. - `SkillSource`: any ADK Java skill source, including `LocalSkillSource` or `ClassPathSkillSource`. Multiple skill entries are merged in the order provided. If more than one entry exposes the same skill name, the later entry takes precedence for both `list_skills` and `load_skill`. For skills packaged in application resources, pass ADK's classpath source explicitly: ```java import com.google.adk.skills.ClassPathSkillSource; Agent agent = Agent.builder() .name("classpath-skill-agent") .skills(new ClassPathSkillSource("skills")) .skillsMode("local") .build(); ``` Remote skill source metadata and skill packages can be exposed through ADK Java's `SkillToolset` with `VeSkillSource`. The source ID can be an AgentKit Skill Space (`ss-...`) or SkillHub space (`sp-...`): ```java import com.google.adk.tools.skills.SkillToolset; import com.volcengine.veadk.skills.VeSkillSource; Agent agent = Agent.builder() .name("remote-skill-agent") .tools(new SkillToolset(new VeSkillSource(System.getenv("SKILL_SOURCE_ID")))) .build(); ``` `SkillToolset` reads the source metadata for every LLM request. Local file changes and remote metadata/version changes therefore become visible on the next request without rebuilding the agent. A refresh failure is returned to that request instead of silently reusing stale metadata. For Skills Sandbox delegation, configure an AgentKit Skill Space ID and expose only the `execute_skills` tool: ```java import com.volcengine.veadk.tools.builtin.sandbox.ExecuteSkillsTool; Agent agent = Agent.builder() .name("remote-sandbox-agent") .skills(System.getenv("SKILL_SPACE_ID")) .skillsMode("skills_sandbox") .tools(new ExecuteSkillsTool()) .build(); ``` Sandbox tools return structured errors when a tool call fails. Agents can use `error.code`, `error.message`, `error.suggestion`, and `error.retryable` to explain the failure or decide whether to retry: ```json { "error": { "code": "SKILLS_SANDBOX_A2A_FAILED", "message": "message/send failed: invalid skill request", "suggestion": "Check the Skills Sandbox A2A error message and retry only if the error is transient.", "retryable": false } } ``` #### MCP Router `McpRouterToolset` exposes tools aggregated by Volcengine MCP Router through ADK Java's streamable HTTP MCP client: ```java import com.volcengine.veadk.tools.builtin.mcp.McpRouterToolset; Agent agent = Agent.builder() .name("mcp-router-agent") .tools(McpRouterToolset.create()) .build(); try { new Runner(agent).run("Use the weather tool to check Beijing."); } finally { agent.close().blockingAwait(); } ``` Set `TOOL_MCP_ROUTER_URL` to the Router endpoint. Optionally set `TOOL_MCP_ROUTER_API_KEY`; it is sent as a Bearer token. To expose only selected Router tools, use `McpRouterToolset.create(url, apiKey, allowedToolNames)`. Closing the agent closes the MCP session. #### Short-Term Memory Short-term memory is session-scoped context. Configure it on the agent, then reuse the same `userId` and `sessionId` when running follow-up turns: ```java import com.volcengine.veadk.Agent; import com.volcengine.veadk.Runner; import com.volcengine.veadk.memory.ShortTermMemory; import com.google.adk.summarizer.EventsCompactionConfig; ShortTermMemory shortTermMemory = ShortTermMemory.builder() .local() .numRecentInvocationsToKeep(3) .eventsCompactionConfig(EventsCompactionConfig.builder() .compactionInterval(5) .overlapSize(1) .build()) .maxToolResultChars(4000) .toolResultSummaryChars(1000) .build(); Agent agent = Agent.builder() .name("memory_agent") .instruction("Remember what the user tells you.") .modelName("doubao-seed-2-1-pro-260628") .shortTermMemory(shortTermMemory) .build(); Runner runner = new Runner(agent, "memory_demo"); runner.run("user_1", "session_1", "My name is Ming."); runner.run("user_1", "session_1", "What is my name?"); ``` `numRecentInvocationsToKeep(...)` limits only the history sent in each model request. The session service still stores the complete event history, and the window keeps tool calls together with their responses. `eventsCompactionConfig(...)` uses ADK's native event summarizer. Configure `compactionInterval` plus `overlapSize` for invocation-based sliding compaction. `maxToolResultChars(...)` replaces oversized tool payloads in later model context with a bounded structured summary while preserving status/error diagnostics and the ADK function-call pairing. Mem0 saves are asynchronous by default. Completion means that Mem0 accepted the request; the new memory may not be immediately searchable. Use synchronous mode when the next operation must wait for Mem0 request processing. Exact search visibility still follows the consistency guarantees of the configured service: ```java import com.volcengine.veadk.memory.mem0.Mem0MemoryService; Mem0MemoryService memoryService = Mem0MemoryService.builder() .appName("memory_agent") .writeMode(Mem0MemoryService.WriteMode.SYNCHRONOUS) .build(); ``` The extracted metadata includes: - Basic agent fields: `id`, `name`, `description`, `instructionSummary`, `modelName`, and `autoSaveSession`. - `tools`: tool names with their source. `explicit` means the user passed the tool through `Agent.builder().tools(...)`; `auto` means the builder injected it from a configured VeADK component, such as `loadKnowledgebase`, `loadMemory`, or `SkillToolset`; `adk` is used when extracting from a plain ADK `LlmAgent`. - `subAgents`: the same metadata shape for each child agent. - `components`: stable component slots for `knowledgebase`, `longTermMemory`, `shortTermMemory`, `tracer`, `toolset`, and `plugin`. - `searchSources`: `web`, `knowledge`, and `memory`, each with an `enabled` flag and the associated tool name when applicable. The canonical tool names are `web_search`, `loadKnowledgebase`, and `loadMemory`. ### Model Credentials Examples that auto-create a model adapter or call `ArkLlm` need model credentials. The resolution order is: - `modelApiKey(...)`: explicit API key on the builder. - `MODEL_AGENT_API_KEY`: raw model API key from the environment. - `MODEL_AGENT_API_KEY_ID`: Ark API key ID. When set, VeADK resolves the raw key through Ark OpenAPI. - `MODEL_AGENT_API_KEY_NAME`: Ark API key name. When set, VeADK resolves the raw key through Ark OpenAPI. - Volcengine AK/SK fallback: when no key value or key name is configured, VeADK resolves the first Ark API key in the account through Ark OpenAPI. Ark OpenAPI fallback requires: - `VOLCENGINE_ACCESS_KEY` - `VOLCENGINE_SECRET_KEY` - Optional: `VOLCENGINE_SESSION_TOKEN` or `VOLC_SESSIONTOKEN` - Optional: `REGION`, defaulting to `cn-beijing` - Optional: `MODEL_AGENT_PROJECT_NAME`, defaulting to `default` - Optional: `CLOUD_PROVIDER=byteplus` for BytePlus control-plane routing Example setup (macOS / Linux): ```bash export MODEL_AGENT_API_KEY="<your-ark-api-key>" ``` ## Run the Project Examples ### Build the Project In the repository root, run: `./mvnw clean -DskipTests package` After building, the compiled artifacts needed by the examples will be generated in `example/target`. Example sources are grouped by feature module: - `example.basic`: minimal Agent, reusable Ark agent, and CLI runner. - `example.skills`: local skills, remote Skills Sandbox, and non-blocking remote skill tasks. - `example.knowledgebase`: Viking and OpenSearch knowledgebase examples. - `example.memory`: Mem0 memory example. - `example.web`: ADK Web startup example. Run the Agent example. It builds an Ark-backed `Agent`, registers a Java function tool, and calls `Runner.run(...)` directly: ```bash export MODEL_AGENT_API_KEY="<your-ark-api-key>" ./mvnw -pl example -am -q compile exec:java -Dexec.mainClass=com.volcengine.veadk.example.basic.AgentExample ``` Run the local skills example. It loads a reimbursement policy skill from `example/src/main/resources/skills` and pre-reviews a realistic expense claim: ```bash export MODEL_AGENT_API_KEY="<your-ark-api-key>" ./mvnw -pl example -am -q compile exec:java -Dexec.mainClass=com.volcengine.veadk.example.skills.LocalSkillsExpenseReviewAgent ``` ### Run the Example (CLI) Entry class: `com.volcengine.veadk.example.basic.AgentCliRunner`. Run it (without modifying the POM, directly via Maven Exec plugin coordinates): ```bash ./mvnw -pl example -am -q compile exec:java -Dexec.mainClass=com.volcengine.veadk.example.basic.AgentCliRunner ``` Interaction notes: - After startup, follow the prompt to input messages and interact with `ArkAgent`. - Type `quit` to exit. ### Run the Example (Web UI) Start command: ```bash ./mvnw -pl example -am -q compile exec:java \ -Dexec.mainClass=com.volcengine.veadk.example.web.AdkWeb ``` - Access URL: `http://localhost:8000` ### Run in IDE - Import the Maven multi-module project using IntelliJ IDEA or Eclipse. - Directly run the `main` method of `AgentCliRunner` or `AdkWeb`. - Ensure the required environment variables are injected in your IDE run configuration (or start the IDE from a shell that has them set). - If you need `web search`, `Viking Memory`, or `Viking Knowledgebase`, configure these environment variables: - `VOLCENGINE_ACCESS_KEY`: Volcengine AccessKey - `VOLCENGINE_SECRET_KEY`: Volcengine SecretKey - For Viking data-plane calls, you can configure API keys instead of AK/SK: - `DATABASE_VIKING_API_KEY`: Viking Knowledgebase search API key - `DATABASE_VIKINGMEM_API_KEY`: Viking Memory search and add-session API key - Explicit SDK API key parameters take precedence over the matching environment variable. Viking API keys cover Knowledgebase search, Memory search, and Memory add-session only. Collection management, Knowledgebase document ingestion, and TOS-backed `addDoc` still require AK/SK or IAM credentials. - If you need `Mem0 Memory`, configure either a direct Mem0 API key: - `DATABASE_MEM0_API_KEY`: Mem0 API Key - `DATABASE_MEM0_BASE_URL`: Mem0 endpoint, for example `https://api.mem0.ai` - Or configure Volcengine credentials and a Mem0 project/API key id so VeADK can resolve the Mem0 API key: - `VOLCENGINE_ACCESS_KEY`: Volcengine AccessKey - `VOLCENGINE_SECRET_KEY`: Volcengine SecretKey - `REGION`: Volcengine region, defaults to `cn-beijing` - `DATABASE_MEM0_PROJECT_ID`: Mem0 memory project id - `DATABASE_MEM0_API_KEY_ID`: optional Mem0 API key id - If you need TLS Trace, besides AK/SK, also configure the TLS topic: - `OBSERVABILITY_OPENTELEMETRY_TLS_SERVICE_NAME`: ID of the TLS service trace log topic Run the Mem0 memory example: ```bash ./mvnw -q install -DskipTests ./mvnw -pl example -am -q compile exec:java -Dexec.mainClass=com.volcengine.veadk.example.memory.Mem0MemoryAgent ``` ## Related Projects - Python version and documentation: [veadk-python](https://github.com/volcengine/veadk-python). ## Container image The official SDK base image contains the VeADK Java JAR and its runtime dependencies. See [Container image](docs/container-image.md) for release tags and usage. ## Supported Feature Scope The Java Agent provides a small, typed contract. It matches the Python package at the user-entry level (`Agent.builder()`, model, tools, sub-agents, memory/knowledgebase metadata), while Java records metadata from explicit builder state and ADK public accessors instead of dynamically scanning object internals. The Java Agent does not currently support these Python-side capabilities: - `runtime=codex/piagent` - `enableResponses` - `aio_sandbox` - `enableA2ui` - `enableTunnel` - YAML or dynamic tool discovery ## FAQ - Error on startup `Missing required configuration: <ENV_NAME>`: indicates a required environment variable is not set; please complete it according to the prompt. - Unable to access memory/knowledgebase/search services: check AK/SK and network connectivity. - Port occupied: if port `8000` is occupied, adjust via `--server.port` or in the startup parameters of `AdkWeb.main`. ## Security and privacy This project takes security seriously. For vulnerability reporting and supported versions, see [SECURITY.md](SECURITY.md) ## License This project uses the Apache License 2.0; see the `LICENSE` file for details. ## AgentKit Runtime HTTP example [Run a Java agent with AgentKit Simple App HTTP routes](docs/agentkit-runtime.md). The example includes local startup, container packaging and HTTP contract tests. Use an AgentKit CLI build with the `basic_java` lifecycle template for Java scaffolding and builds. See [Built-in tools](docs/builtin-tools.md) for web fetch, parallel search, TTS, PowerPoint, Lark, mobile use, and Vanna + ClickHouse setup.

Chargement du README du dépôt…

Skills dans ce dépôt

classification en attente

skill

métier

description

mis à jour

classpath-policy

non classé

Test skill served from classpath resources.

Langue du texte source : anglais

2026-10-10

expense-policy-reviewer

non classé

Review employee reimbursement requests against the company's sample expense policy and draft submission notes.

Langue du texte source : anglais

2026-10-10

Affichage de 2 skills collectés sur 2.