Skip to content

AgentTool SPI + module restructure: agent-plugin tree, agent -> agent-runtime, connector-api under connector-plugin (follow-up to #5408) - #5409

Merged
qqeasonchen merged 6 commits into
apache:developfrom
qqeasonchen:feat/agent-tool-spi
Sep 21, 2026
Merged

qqeasonchen merged 6 commits into
apache:developfrom
qqeasonchen:feat/agent-tool-spi

Conversation

@qqeasonchen

@qqeasonchen qqeasonchen commented Sep 21, 2026 •

Copy link
Copy Markdown
Contributor

Follow-up to #5408 (discussion in #5407): turn AgentTool into a real repo-standard SPI extension point plus the module restructure to host agent plugins in-tree.

Commit 1 — AgentTool SPI

  • @EventMeshSPI on AgentTool + a new AGENT_TOOL entry in EventMeshExtensionType. Implementations register via a META-INF/eventmesh/org.apache.eventmesh.agent.tool.AgentTool service file (mytool=com.example.MyTool) — the same convention as every other EventMesh plugin.
  • ToolRegistry.registerSpi(name) — resolves an implementation by SPI name through EventMeshExtensionFactory (singleton semantics, classpath + plugin-jar loaders).
  • -Dagent.tools.spi=<name,...> in AgentApplication — enables SPI tools alongside the connector-backed tools from Agent extension points: LlmClient/ConversationMemory SPI, connector-backed agent tools, event triggers #5408.
  • plugin/agent/ classpath convention — the agent launcher puts every jar under plugin/agent/ on the classpath (mirrors plugin/connector/ in the connector runtime).

Commit 2 — module restructure (rename detection = pure R100 moves)

  • eventmesh-connector-api → eventmesh-connector-plugin/eventmesh-connector-api — the connector SPI jar lives under its plugin family, like storage/protocol.
  • eventmesh-agent → eventmesh-agent-runtime — it is a process runtime, matching eventmesh-connector-runtime.
  • New eventmesh-agent-plugin/ tree — umbrella + eventmesh-agent-plugin-http-fetch (first in-tree AgentTool plugin: fetch a URL, return the truncated body; pluginType=agentTool, pluginName=http-fetch, service file included). New in-tree tools need zero wiring: dist-agent installs every pluginType==agentTool module into dist-agent/plugin/agent/<name>/.
  • All references updated: settings.gradle, root build.gradle (findProject paths + the new plugin install block), all 23 connector plugin build.gradle files, architecture-guard, runtime test dep, docs (agent-tools.md, client-java.md).

User-facing workflows after this PR

# in-tree plugin (shipped): already built into dist-agent/plugin/agent/http-fetch/
AGENT_TOOLS_SPI=http-fetch

# third-party: implement AgentTool, ship the service file, drop the jar into plugin/agent/
AGENT_TOOLS_SPI=risk-check

Tests

  • AgentToolSpiTest.registerSpiResolvesThroughTheFactory — resolves echo-test through the real EventMeshExtensionFactory using a test service file + EchoTestTool, invokes it end-to-end
  • AgentToolSpiTest.registerSpiRejectsUnknownName — unknown SPI name throws IllegalArgumentException
  • Full agent suite: 11/11 green; HttpFetchTool compiles + checkstyle clean
  • Moves are pure renames (git R100, zero content diff) — no semantic change to moved code

Notes

  • eventmesh-agent-runtime gains an explicit compile dep on eventmesh-spi (the factory module); already transitively present via the SDK.

- Annotate AgentTool with @EventMeshSPI (new AGENT_TOOL extension type);
  custom tools now register via META-INF/eventmesh/<AgentTool-FQCN> service
  files exactly like storage/connector plugins
- ToolRegistry.registerSpi(name) resolves implementations through
  EventMeshExtensionFactory (singleton semantics, classpath + plugin-jar
  loaders)
- AgentApplication: -Dagent.tools.spi=<name,...> enables SPI tools alongside
  connector-backed tools
- start-agent.sh: jars under plugin/agent/ join the agent classpath (same
  convention as plugin/connector/ in the connector runtime)
- Tests: AgentToolSpiTest drives the real factory + a test service file
  (echo-test) through registerSpi; unknown-name rejection path covered
- Docs: agent-tools.md SPI section + config-table entry; agent.properties
  key doc
…nector-plugin, agent -> agent-runtime, new agent-plugin tree

- Move eventmesh-connector-api -> eventmesh-connector-plugin/eventmesh-connector-api
  (SPI jar lives with its plugin family, like storage/protocol)
- Rename eventmesh-agent -> eventmesh-agent-runtime (it is a process runtime, matching
  eventmesh-connector-runtime)
- New eventmesh-agent-plugin/ tree: umbrella + eventmesh-agent-plugin-http-fetch (first
  in-tree AgentTool plugin: fetch a URL, return truncated body; pluginType=agentTool,
  pluginName=http-fetch, META-INF service file included)
- dist-agent now installs pluginType==agentTool modules into dist-agent/plugin/agent/<name>/
  (same convention as dist-connector/plugin/connector)
- References updated: settings.gradle, root build.gradle (findProject paths), all 23
  connector plugin build files, architecture-guard, runtime test dep, docs
@qqeasonchen qqeasonchen changed the title AgentTool SPI: plugin-jar deployment for custom agent tools (follow-up to #5408) AgentTool SPI + module restructure: agent-plugin tree, agent -> agent-runtime, connector-api under connector-plugin (follow-up to #5408) Sep 21, 2026
@qqeasonchen
qqeasonchen merged commit 2c738b7 into apache:develop Sep 21, 2026
10 of 11 checks passed
@qqeasonchen

Copy link
Copy Markdown
Contributor Author

Docs pass added (13c5f500): cross-links the agent story end to end —

qqeasonchen added a commit that referenced this pull request Sep 22, 2026
…ter #5409 was merged) (#5410)

These changes were pushed to the #5409 branch minutes after it was squash-merged
and missed the merge; resubmitting on top of develop:/n/n- README.md / README.zh-CN.md: LLM streaming agent runtime feature bullet,
  Agent tools & event triggers capability row, docs-list entries
- Connector Runtime and A2A / Agent Gateway promoted to Beta (the
  Testcontainers E2E gate #5340 closed 2026-09)
- docs/feature/a2a.md: Related capabilities section pairing A2A with the
  streaming agent runtime
- docs/index.md: A2A entry cross-links agent-tools
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant