# apache/flink-agents architecture

> Architecture diagram of the GitHub repository apache/flink-agents, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/apache/flink-agents
- Repository: https://github.com/apache/flink-agents

## Overview

Apache Flink Agents is a framework for building AI agents that execute with Flink. Users configure agents and resources, then events trigger planned actions such as chat-model calls, tool use, and context retrieval; results are emitted as events. The runtime provides durable execution and state recovery, while optional integrations supply model, vector-store, and MCP implementations. Skills extend agent context, and Python APIs and actions support cross-language use. The graph follows the documented context-retrieval and durable-state behavior; other links are limited to relationships visible in the supplied excerpts or source index.

Main entry points: [`plan/src/main/java/org/apache/flink/agents/plan/actions/ContextRetrievalAction.java`](https://github.com/apache/flink-agents/blob/main/plan/src/main/java/org/apache/flink/agents/plan/actions/ContextRetrievalAction.java) (Context Retrieval), [`plan/src/main/java/org/apache/flink/agents/plan/AgentPlan.java`](https://github.com/apache/flink-agents/blob/main/plan/src/main/java/org/apache/flink/agents/plan/AgentPlan.java) (Agent Plan), [`api/src/main/java/org/apache/flink/agents/api/AgentBuilder.java`](https://github.com/apache/flink-agents/blob/main/api/src/main/java/org/apache/flink/agents/api/AgentBuilder.java) (Agent Builder), [`plan/src/main/java/org/apache/flink/agents/plan/actions/ChatModelAction.java`](https://github.com/apache/flink-agents/blob/main/plan/src/main/java/org/apache/flink/agents/plan/actions/ChatModelAction.java) (Chat Action)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Agent API"]
  node_builder["Agent Builder<br/>[AgentBuilder.java]"]
  node_events["Event Model<br/>[Event.java]"]
  node_resources["Resource API"]
  node_messages["Chat Messages<br/>[ChatMessage.java]"]
end

subgraph group_planning["Plans and Actions"]
  node_plan["Agent Plan<br/>[AgentPlan.java]"]
  node_chat_action["Chat Action"]
  node_tool_action["Tool Actions"]
  node_retrieval["Context Retrieval"]
  node_routing["Model Routing"]
end

subgraph group_runtime["Flink Runtime"]
  node_durable["Durable Execution"]
  node_state[("Action State Store")]
end

subgraph group_integrations["Model Integrations"]
  node_chat_models["Chat Models"]
  node_embedding["Embedding Models"]
  node_vector[("Vector Stores")]
end

subgraph group_extensions["Skills and Python"]
  node_skills["Skill Manager<br/>[SkillManager.java]"]
  node_python_actions["Python Actions"]
  node_mcp["MCP Integration<br/>[MCPServer.java]"]
end

node_user(("Agent User"))
node_result(("Agent Events"))

node_user -.->|"configures"| node_builder
node_builder -.->|"defines"| node_plan
node_builder -.->|"configures"| node_resources
node_plan -.->|"dispatches"| node_chat_action
node_plan -.->|"dispatches"| node_tool_action
node_chat_action -.->|"invokes"| node_chat_models
node_chat_action -.->|"uses"| node_messages
node_routing -.->|"selects"| node_chat_models
node_retrieval -->|"queries"| node_vector
node_retrieval -->|"emits response"| node_events
node_retrieval -->|"looks up store"| node_resources
node_durable -->|"reads and writes"| node_state
node_durable -->|"executes actions"| node_plan
node_retrieval -->|"runs durably"| node_durable
node_retrieval -.->|"uses for search"| node_embedding
node_skills -->|"provides context"| node_resources
node_python_actions -->|"queries"| node_vector
node_python_actions -->|"emits response"| node_events
node_tool_action -.->|"may invoke"| node_mcp
node_events -.->|"delivers"| node_result

click node_builder "https://github.com/apache/flink-agents/blob/main/api/src/main/java/org/apache/flink/agents/api/AgentBuilder.java"
click node_events "https://github.com/apache/flink-agents/blob/main/api/src/main/java/org/apache/flink/agents/api/Event.java"
click node_resources "https://github.com/apache/flink-agents/blob/main/api/src/main/java/org/apache/flink/agents/api/resource/ResourceContext.java"
click node_messages "https://github.com/apache/flink-agents/blob/main/api/src/main/java/org/apache/flink/agents/api/chat/messages/ChatMessage.java"
click node_plan "https://github.com/apache/flink-agents/blob/main/plan/src/main/java/org/apache/flink/agents/plan/AgentPlan.java"
click node_chat_action "https://github.com/apache/flink-agents/blob/main/plan/src/main/java/org/apache/flink/agents/plan/actions/ChatModelAction.java"
click node_tool_action "https://github.com/apache/flink-agents/blob/main/plan/src/main/java/org/apache/flink/agents/plan/actions/ToolCallAction.java"
click node_retrieval "https://github.com/apache/flink-agents/blob/main/plan/src/main/java/org/apache/flink/agents/plan/actions/ContextRetrievalAction.java"
click node_routing "https://github.com/apache/flink-agents/blob/main/plan/src/main/java/org/apache/flink/agents/plan/routing/ModelRoutingResolver.java"
click node_durable "https://github.com/apache/flink-agents/blob/main/runtime/src/main/java/org/apache/flink/agents/runtime/operator/DurableExecutionManager.java"
click node_state "https://github.com/apache/flink-agents/blob/main/runtime/src/main/java/org/apache/flink/agents/runtime/operator/DurableExecutionManager.java"
click node_chat_models "https://github.com/apache/flink-agents/blob/main/integrations/chat-models/openai/src/main/java/org/apache/flink/agents/integrations/chatmodels/openai/OpenAICompletionsConnection.java"
click node_embedding "https://github.com/apache/flink-agents/blob/main/integrations/embedding-models/openai/src/main/java/org/apache/flink/agents/integrations/embeddingmodels/openai/OpenAIEmbeddingModelConnection.java"
click node_vector "https://github.com/apache/flink-agents/blob/main/api/src/main/java/org/apache/flink/agents/api/vectorstores/BaseVectorStore.java"
click node_skills "https://github.com/apache/flink-agents/blob/main/runtime/src/main/java/org/apache/flink/agents/runtime/skill/SkillManager.java"
click node_python_actions "https://github.com/apache/flink-agents/blob/main/python/flink_agents/plan/actions/context_retrieval_action.py"
click node_mcp "https://github.com/apache/flink-agents/blob/main/integrations/mcp/src/main/java/org/apache/flink/agents/integrations/mcp/MCPServer.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_builder,node_events,node_resources,node_messages,node_user toneBlue
class node_plan,node_chat_action,node_tool_action,node_retrieval,node_routing toneAmber
class node_durable,node_state toneMint
class node_chat_models,node_embedding,node_vector toneRose
class node_skills,node_python_actions,node_mcp,node_result toneIndigo
```

## Components

### Agent API

- [Agent Builder](https://github.com/apache/flink-agents/blob/main/api/src/main/java/org/apache/flink/agents/api/AgentBuilder.java): `api/src/main/java/org/apache/flink/agents/api/AgentBuilder.java`
- [Event Model](https://github.com/apache/flink-agents/blob/main/api/src/main/java/org/apache/flink/agents/api/Event.java): `api/src/main/java/org/apache/flink/agents/api/Event.java`
- [Resource API](https://github.com/apache/flink-agents/blob/main/api/src/main/java/org/apache/flink/agents/api/resource/ResourceContext.java): `api/src/main/java/org/apache/flink/agents/api/resource/ResourceContext.java`
- [Chat Messages](https://github.com/apache/flink-agents/blob/main/api/src/main/java/org/apache/flink/agents/api/chat/messages/ChatMessage.java): `api/src/main/java/org/apache/flink/agents/api/chat/messages/ChatMessage.java`

### Plans and Actions

- [Agent Plan](https://github.com/apache/flink-agents/blob/main/plan/src/main/java/org/apache/flink/agents/plan/AgentPlan.java): `plan/src/main/java/org/apache/flink/agents/plan/AgentPlan.java`
- [Chat Action](https://github.com/apache/flink-agents/blob/main/plan/src/main/java/org/apache/flink/agents/plan/actions/ChatModelAction.java): `plan/src/main/java/org/apache/flink/agents/plan/actions/ChatModelAction.java`
- [Tool Actions](https://github.com/apache/flink-agents/blob/main/plan/src/main/java/org/apache/flink/agents/plan/actions/ToolCallAction.java): `plan/src/main/java/org/apache/flink/agents/plan/actions/ToolCallAction.java`
- [Context Retrieval](https://github.com/apache/flink-agents/blob/main/plan/src/main/java/org/apache/flink/agents/plan/actions/ContextRetrievalAction.java): `plan/src/main/java/org/apache/flink/agents/plan/actions/ContextRetrievalAction.java`
- [Model Routing](https://github.com/apache/flink-agents/blob/main/plan/src/main/java/org/apache/flink/agents/plan/routing/ModelRoutingResolver.java): `plan/src/main/java/org/apache/flink/agents/plan/routing/ModelRoutingResolver.java`

### Flink Runtime

- [Durable Execution](https://github.com/apache/flink-agents/blob/main/runtime/src/main/java/org/apache/flink/agents/runtime/operator/DurableExecutionManager.java): `runtime/src/main/java/org/apache/flink/agents/runtime/operator/DurableExecutionManager.java`
- [Action State Store](https://github.com/apache/flink-agents/blob/main/runtime/src/main/java/org/apache/flink/agents/runtime/operator/DurableExecutionManager.java): `runtime/src/main/java/org/apache/flink/agents/runtime/operator/DurableExecutionManager.java`

### Model Integrations

- [Chat Models](https://github.com/apache/flink-agents/blob/main/integrations/chat-models/openai/src/main/java/org/apache/flink/agents/integrations/chatmodels/openai/OpenAICompletionsConnection.java): `integrations/chat-models/openai/src/main/java/org/apache/flink/agents/integrations/chatmodels/openai/OpenAICompletionsConnection.java`
- [Embedding Models](https://github.com/apache/flink-agents/blob/main/integrations/embedding-models/openai/src/main/java/org/apache/flink/agents/integrations/embeddingmodels/openai/OpenAIEmbeddingModelConnection.java): `integrations/embedding-models/openai/src/main/java/org/apache/flink/agents/integrations/embeddingmodels/openai/OpenAIEmbeddingModelConnection.java`
- [Vector Stores](https://github.com/apache/flink-agents/blob/main/api/src/main/java/org/apache/flink/agents/api/vectorstores/BaseVectorStore.java): `api/src/main/java/org/apache/flink/agents/api/vectorstores/BaseVectorStore.java`

### Skills and Python

- [Skill Manager](https://github.com/apache/flink-agents/blob/main/runtime/src/main/java/org/apache/flink/agents/runtime/skill/SkillManager.java): `runtime/src/main/java/org/apache/flink/agents/runtime/skill/SkillManager.java`
- [Python Actions](https://github.com/apache/flink-agents/blob/main/python/flink_agents/plan/actions/context_retrieval_action.py): `python/flink_agents/plan/actions/context_retrieval_action.py`
- [MCP Integration](https://github.com/apache/flink-agents/blob/main/integrations/mcp/src/main/java/org/apache/flink/agents/integrations/mcp/MCPServer.java): `integrations/mcp/src/main/java/org/apache/flink/agents/integrations/mcp/MCPServer.java`

### Other components

- **Agent User**
- **Agent Events**

## Connections

- Agent User → Agent Builder: configures
- Agent Builder → Agent Plan: defines
- Agent Builder → Resource API: configures
- Agent Plan → Chat Action: dispatches
- Agent Plan → Tool Actions: dispatches
- Chat Action → Chat Models: invokes
- Chat Action → Chat Messages: uses
- Model Routing → Chat Models: selects
- Context Retrieval → Vector Stores: queries (evidence: `plan/src/main/java/org/apache/flink/agents/plan/actions/ContextRetrievalAction.java`)
- Context Retrieval → Event Model: emits response (evidence: `plan/src/main/java/org/apache/flink/agents/plan/actions/ContextRetrievalAction.java`)
- Context Retrieval → Resource API: looks up store (evidence: `plan/src/main/java/org/apache/flink/agents/plan/actions/ContextRetrievalAction.java`)
- Durable Execution → Action State Store: reads and writes (evidence: `runtime/src/main/java/org/apache/flink/agents/runtime/operator/DurableExecutionManager.java`)
- Durable Execution → Agent Plan: executes actions (evidence: `runtime/src/main/java/org/apache/flink/agents/runtime/operator/DurableExecutionManager.java`)
- Context Retrieval → Durable Execution: runs durably (evidence: `plan/src/main/java/org/apache/flink/agents/plan/actions/ContextRetrievalAction.java`)
- Context Retrieval → Embedding Models: uses for search
- Skill Manager → Resource API: provides context (evidence: `api/src/main/java/org/apache/flink/agents/api/resource/ResourceContext.java`)
- Python Actions → Vector Stores: queries (evidence: `python/flink_agents/plan/actions/context_retrieval_action.py`)
- Python Actions → Event Model: emits response (evidence: `python/flink_agents/plan/actions/context_retrieval_action.py`)
- Tool Actions → MCP Integration: may invoke
- Event Model → Agent Events: delivers