EventMesh Agent (v2 Streaming Agent Process)

The eventmesh-agent module is the v2 streaming-agent process: an independent JVM that registers with a running EventMesh runtime, subscribes its private lite channel, and bridges routed prompts to an OpenAI-compatible LLM gateway — streaming tokens back over the runtime to the requesting client.

Boot sequence

Register — POST /agent/register on the runtime traffic port; the runtime assigns the agent its agent-parent + client-reply-parent (§5.2 of the v2 design).
Subscribe — the agent subscribes agent.<agentId> on its parent via the lite wire (subscribeLiteBytes).
Ready — POST /agent/ready flips the registration ready; only now does matchmaking route sessions to this agent (ready-before-route).
Heartbeat — a virtual thread refreshes the TTL and reports active sessions every agent.heartbeat.intervalMs.

Quick start

# 1. runtime (defaults: memory storage, traffic 10105)
./gradlew :eventmesh-runtime:runRuntime   # or use the docker image

# 2. agent (needs an OpenAI-compatible endpoint)
LLM_BASE_URL=https://api.openai.com LLM_API_KEY=sk-... LLM_MODEL=gpt-4o-mini   ./bin/start-agent.sh                    # from dist-agent/

Dev runner without a distribution: ./gradlew :eventmesh-agent:runAgent -Dllm.api.key=sk-....

Configuration

All config is -D system properties; bin/start-agent.sh maps the AGENT_* / LLM_* env vars (see conf/agent.properties for the full list).

Key	Default	Description
`agent.runtime.url`	`http://localhost:10105`	Runtime traffic URL (control plane + lite wire)
`agent.id`	`agent-<ts>`	Agent identity; must be unique per process
`agent.capacity`	`100`	Advertised concurrent-stream capacity (matchmaking input)
`agent.heartbeat.intervalMs`	`10000`	Heartbeat cadence
`agent.heartbeat.failLimit`	`6`	Consecutive heartbeat failures before the process exits (supervisor restarts it)
`agent.conversation.maxHistory`	`20`	Per-conversation message sliding window
`agent.conversation.maxConversations`	`1000`	Live-conversation bound; least-recently-used conversations are evicted
`llm.base.url`	`https://api.openai.com`	OpenAI-compatible gateway base URL
`llm.api.key`	(empty)	Bearer key — required; empty fails fast at boot
`llm.api.key.optional`	`false`	Opt-out of the empty-key fail-fast (mock gateways)
`llm.model`	`gpt-4o-mini`	Default model; per-request model overrides win

Reliability behavior

Fail-fast on empty LLM key — an agent without a usable key would fail every routed request after registering READY, so boot refuses (unless llm.api.key.optional=true).
Heartbeat failure limit — after agent.heartbeat.failLimit consecutive failures the process exits nonzero (the runtime TTL has evicted the registration by then; a zombie serves nothing). Supervisors (systemd / K8s) restart it.
Bounded conversations — each conversation keeps a sliding window of turns, and the store evicts least-recently-used conversations past agent.conversation.maxConversations, bounding agent memory on long-lived processes.

Limitations

Conversation history is process-local (lost on restart); persistence is an explicit TODO.
Mode-1 (streaming calls) only — mode-2 pub/sub sessions are not routed to agents.
One LLM gateway per process (llm.base.url); multi-provider routing is future work.