Planning Flink Agents 0.4

[wenjin272]

Time Plan

• Target Feature Freeze: September 15 October 15
• Target Release: September 30 October 30

Must

• Highlight Features
  • Conduct a comprehensive review of the existing API and design a compatibility mechanism
    • [Tech Debt][Umbrella] Review and refine Flink Agents APIs for 0.4 #1055
  • Support asynchronous execution for Java durable execution on JDK versions below 21
  • Support Sub Agent primitives
    • [Discussion] Supervisor + Sub-Agent Orchestration: Concrete Multi-Agent Use Cases for Event-Driven Agents #660
    • [api][plan][runtime] Introduce AGENT resource type and sub-agent invocation API #938
  • Flink Agents Dev Skills: Provide Agent Skills to help users build flink-agents based Agent via coding agent
    • [Feature] Add a coding-agent development skill for Flink Agents applications #917
• Requirements from Production
  • API
    • Support invoking multimodal models
      • [Feature] Multimodal content blocks in ChatMessage #1059
    • Support injecting parameters into tool calls
      • [Feature] Support tool parameter injection #853
    • Support structured output from ChatModel
      • [Feature] Support making use of the native capabilities of models for structure output. #280
  • Runtime
    • Support dynamic updates to the AgentPlan, covering events, actions, and resources
• Important Experience Improvements
  • Observability
    • Support observing Memory through the EventLog
      • [Feature] Add memory events for agent memory observability #886
    • Support Per-Run Trace to visualize the execution path of a single record through the Agent
      • [Feature] Add Agent Trace recording to Event Log #1068
    • Metrics improvements
      • [Feature] Propagate metric groups to cross-language resources #857
      • [Feature] Track token usage metrics for embedding models #858
      • [Bug] Action-scoped metrics can be recorded under the wrong action for cached resources #859
  • CI & Infra
    • Support Flink 2.3
      • [Feature] Support Flink 2.3 #833
    • AI-assisted code review mechanism (explored within the release cycle; not tied to a release)
      • [Feature] Add AGENTS.md #877
      • [infra] Follow-up improvements to AGENTS.md and code_review.md #894

If Possible

• API
  • Support to-C sources such as Slack / GitHub / Gmail / Jira
  • Support conditional triggering of Actions
    • [api][plan][runtime] Support triggering action by Event field values #754
  • Provide syntactic sugar for common workflow patterns to reduce the effort of building Workflows
    • fan-out / fan-in API
• Runtime
  • MCP dynamic loading and refreshing
    • [Feature] Dynamic load MCP tools and prompts in runtime. #458
    • [Feature] Support MCP tools and prompts runtime discovery #606
  • Parallel tool call execution
    • Parallel Tool Call Execution #855
    • [Feature] Parallel Tool Call Execution #925
  • Agent Harness (governance layer)
    • WorkflowRunPolicy: max events / max actions / max tokens / timeout
      • [Feature] Per-agent token/cost budget guardrail (enforcement, not just reporting) #1065
    • Support safety guardrails and hooks
• CI & Infra
  • Support automated validation of the quick start example via GitHub Actions
    • [Tech Debt] Add e2e test for submitting example to flink standalone cluster. #642
• SQL Integration
  • Support invoking Agents from SQL jobs
  • Support Invoking Agents from CDC YAML
  • Agent-specific SQL syntax (Table / View as VectorStore / KeyedContext), Inject other Tables / Views as context into the Agent
  • Support SQL Function / Operator as Action, reusing existing SQL / DataFrame operator capabilities within Flink Agents

[weiqingy]

Thanks for starting the 0.4 planning thread. The current Must list looks like a good foundation to me. The split between highlight features, production requirements, experience improvements, and “if possible” items also makes sense.

A few thoughts / brainstorm ideas:

1. For sub-agent primitives, I’ll resolve the pending feedback in [Discussion] Supervisor + Sub-Agent Orchestration: Concrete Multi-Agent Use Cases for Event-Driven Agents #660 and follow up there with a concrete proposal [1].

2. The observability part already covers the main things I was thinking about: memory observation through EventLog, per-run trace [Discussion] Agent observability: tracing & evaluation beyond metrics + event log #710, and metrics improvements [2][3][4]. I don’t have extra items to add there beyond agreeing that these are important for production debugging and evaluation. This also matches what other agent runtimes emphasize: execution timelines, trace visualization, and evaluation/debugging loops are treated as core production capabilities [8][9].

3. One possible area to brainstorm is durable external signal handling. I’d frame this less as generic human-in-the-loop and more as event-driven durable correlation: wait/resume/timeout based on a callback or another stream event. Flink Agents already has durable execution, action-state recovery, reconcilers, and request_id-style correlation in built-in events [5]. The missing part may be a generic pattern/API for “this keyed run is pending until a later correlated event arrives or times out.” Restate and LangGraph both show a similar need around durable waiting/resuming long-running agent or workflow executions, though Flink Agents may want to express it in a more event-stream-native way [8][9].
   Example: a support agent sends a fraud-check request to an external risk service. The response comes back later on Kafka. The agent should not block a thread; it should persist pending state, resume on the callback event, or emit a timeout path.

4. Flow/cost control seems partly covered by the proposed Agent Harness (max events / max actions / max tokens / timeout) and parallel tool call execution Parallel Tool Call Execution #855 [7]. One possible extension to consider is resource-scoped guardrails: per-model, per-tool, per-key, or per-tenant concurrency/rate limits. A global async pool prevents unlimited threads [6], but it does not express “this tenant gets max N concurrent model calls” or “this external CRM tool gets max QPS.” This could maybe fit under Agent Harness or the parallel tool execution work rather than being a separate top-level feature. Restate calls out cost/concurrency control for agent invocations as an explicit runtime concern, which seems like a useful reference point here [8].

References:

[1] #660 Sub-agent discussion: #660
[2] Monitoring docs: https://github.com/apache/flink-agents/blob/main/docs/content/docs/operations/monitoring.md
[3] #710 tracing/evaluation discussion: #710
[4] #876 memory observation discussion: #876
[5] Deployment / exactly-once action consistency docs: https://github.com/apache/flink-agents/blob/main/docs/content/docs/operations/deployment.md
[6] Configuration docs: https://github.com/apache/flink-agents/blob/main/docs/content/docs/operations/configuration.md
[7] #855 parallel tool execution discussion: #855
[8] Restate AI Agents: https://docs.restate.dev/use-cases/ai-agents
[9] LangGraph overview: https://docs.langchain.com/oss/python/langgraph/overview

[Zhuoxi2000]

I’d like to pick up the “Support invoking multimodal models” Must item, starting with a design discussion.

My initial thought is to extend ChatMessage with typed content parts (text / image / document) in both Java and Python, while keeping plain-string content backward compatible. Each provider can then map those parts to its native format.

For 0.4, I’d keep the scope realistic: define the content-part API and support one or two providers first, then add the rest incrementally.

Two things probably worth settling in the design: cross-language/YAML serialization, and how large media content should interact with Event Log truncation and trace recording.

If no one is already working on this, I’m happy to open a [Discussion] with a concrete proposal.

[wenjin272]

Thanks for volunteering. As far as I know, no one is currently working on this, so please feel free to pick it up. The overall direction and phased scope look reasonable to me.

[da-daken]

As a system that runs 24/7, I would like to dynamically adjust some parameters without restarting the Flink job, such as parallelism, prompts, changing MCP addresses, etc. Will the community consider this direction?

[GreatEugenius]

Thanks for bringing this up! I believe this is part of the planned “Support dynamic updates to the AgentPlan, covering events, actions, and resources” work. We already have some related PoCs exploring this direction. Thank you for the suggestion!

[da-daken]

Wow, I'm excited to see the related design proposals – that would be very helpful.

[wenjin272]

As discussed during our Community Sync, some community developers have recently been focusing on the internal adoption of Flink Agents, and a few tasks planned for the 0.4 release are still in progress. Given the current status, we have decided to adjust the 0.4 release schedule: the code freeze will be postponed from September 15 to October 15, and the release date will be moved from September 30 to October 30.