Skip to content

Commit beb9c4c

Browse files
igordayenigordayen
authored
Architectural Diagrams addition to User Guide: (#1258)
section Planners, Agent Platform, Agent Process
1 parent 62cc442 commit beb9c4c

File tree

7 files changed

+221
-0
lines changed

7 files changed

+221
-0
lines changed

‎embabel-agent-docs/src/main/asciidoc/reference/agent-platform/page.adoc‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,3 +4,10 @@
44
An `AgentPlatform` provides the ability to run agents in a specific environment.
55
This is an SPI interface, so multiple implementations are possible.
66

7+
8+
[graphviz, embabel_agent_platform_model.dot, png]
9+
----
10+
include::../diagrams/architecture/embabel_agent_platform_model.dot[]
11+
----
12+
13+

‎embabel-agent-docs/src/main/asciidoc/reference/agent-process/page.adoc‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,3 +21,10 @@ Allows fine grained control over logging prompts, LLM returns and detailed plann
2121
This is useful to avoid rate limiting.
2222

2323

24+
[graphviz, embabel_execution_context.dot, png]
25+
----
26+
include::../diagrams/architecture/embabel_execution_context.dot[]
27+
----
28+
29+
30+

‎embabel-agent-docs/src/main/asciidoc/reference/architecture/page.adoc‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,13 @@
11
[[reference.architecture]]
22
=== Embabel Architecture
3+
4+
Please refer to architectural diagrams in sections:
5+
6+
<<reference.planners>>
7+
8+
<<reference.agent-platform>>
9+
10+
<<reference.agent-process>>
11+
12+
13+

‎embabel-agent-docs/src/main/asciidoc/reference/diagrams/architecture/embabel_agent_platform_model.dot‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
digraph AgentPlatformModel {
2+
// Node styling - matching original diagram
3+
node [shape=box, style="filled,rounded", fontname="Arial", margin=0.2];
4+
edge [fontname="Arial", fontsize=10];
5+
6+
// Core platform components
7+
AgentPlatform [fillcolor=lightblue, label="AgentPlatform\n(Runtime deployment)"];
8+
Agent [fillcolor=lightgreen, label="Agent\n(Immutable agent description)"];
9+
AgentScope [fillcolor=lightyellow, label="AgentScope\n(Actions, goals, conditions)"];
10+
AgentProcess [fillcolor=lightcoral, label="AgentProcess\n(Single agent run)"];
11+
12+
// Programming model - annotations
13+
AgentAnnotation [fillcolor=pink, label="@Agent\n(Component annotation)"];
14+
ActionAnnotation [fillcolor=lightgrey, label="@action\n(Method annotation)"];
15+
ConditionAnnotation [fillcolor=lightcyan, label="@condition\n(Method annotation)"];
16+
CapabilitiesAnnotation [fillcolor=lavender, label="@AgentCapabilities\n(Shared capabilities)"];
17+
18+
// Configuration
19+
ProcessOptions [fillcolor=lightpink, label="ProcessOptions\n(Runtime configuration)"];
20+
21+
// Status tracking
22+
ProcessStatus [fillcolor=lightsteelblue, label="ProcessStatus\n(Runtime state)"];
23+
24+
// Domain types
25+
DataDictionary [fillcolor=lightsalmon, label="DataDictionary\n(Type registry)"];
26+
DomainType [fillcolor=lightseagreen, label="DomainType\n(Type representation)"];
27+
28+
// Core components from planning system
29+
Action [fillcolor=lightblue, label="Action\n(Executable step)"];
30+
Condition [fillcolor=lightgreen, label="Condition\n(Named predicate)"];
31+
Goal [fillcolor=pink, label="Goal\n(Desired end state)"];
32+
33+
// Core relationships
34+
AgentPlatform -> Agent [label="deploys"];
35+
AgentPlatform -> AgentProcess [label="creates"];
36+
Agent -> AgentScope [label="implements"];
37+
AgentProcess -> ProcessStatus [label="tracks"];
38+
AgentProcess -> ProcessOptions [label="configured by"];
39+
40+
// Programming model relationships
41+
AgentAnnotation -> Agent [label="defines"];
42+
ActionAnnotation -> Action [label="creates"];
43+
ConditionAnnotation -> Condition [label="creates"];
44+
CapabilitiesAnnotation -> AgentScope [label="contributes to"];
45+
46+
// Compositional relationships - Agent composed of Actions/Goals/Conditions
47+
Agent -> Action [label="composed of", style="bold"];
48+
Agent -> Goal [label="composed of", style="bold"];
49+
Agent -> Condition [label="composed of", style="bold"];
50+
51+
// AgentScope composition
52+
AgentScope -> Action [label="contains", style="dashed"];
53+
AgentScope -> Goal [label="contains", style="dashed"];
54+
AgentScope -> Condition [label="contains", style="dashed"];
55+
56+
// Action-Condition relationships
57+
Action -> Condition [label="has pre/post conditions"];
58+
59+
// Configuration relationships
60+
ProcessOptions -> AgentProcess [label="configures"];
61+
62+
// Schema relationships - inheritance/implementation
63+
AgentScope -> DataDictionary [label="implements", style="dashed"];
64+
Agent -> DataDictionary [label="implements", style="dashed"];
65+
AgentPlatform -> DataDictionary [label="implements", style="dashed"];
66+
DataDictionary -> DomainType [label="contains"];
67+
68+
// Additional platform relationships
69+
AgentPlatform -> AgentScope [label="acts as superset", style="dashed"];
70+
ProcessStatus -> AgentProcess [label="reports on", dir="back", style="dashed"];
71+
}

‎embabel-agent-docs/src/main/asciidoc/reference/diagrams/architecture/embabel_execution_context.dot‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
digraph ExecutionContext {
2+
// Simple layout improvements
3+
ranksep=1.0;
4+
nodesep=0.8;
5+
6+
// Node styling - matching original diagram
7+
node [shape=box, style="filled,rounded", fontname="Arial", margin=0.3, fontsize=12];
8+
edge [fontname="Arial", fontsize=11];
9+
10+
// Core context and LLM layer - grouped together
11+
{rank=same; ProcessContext; OperationContext; LlmOperations;}
12+
ProcessContext [fillcolor=lightblue, label="ProcessContext\n(Process-scoped services)"];
13+
OperationContext [fillcolor=lightgreen, label="OperationContext\n(Operation execution context)"];
14+
LlmOperations [fillcolor=lightgrey, label="LlmOperations\n(LLM backend services)"];
15+
16+
// Secondary context layer
17+
ActionContext [fillcolor=lightyellow, label="ActionContext\n(Action-specific context)"];
18+
19+
// LLM configuration
20+
PromptRunner [fillcolor=lightcoral, label="PromptRunner\n(LLM interaction API)"];
21+
LlmOptions [fillcolor=lightcyan, label="LlmOptions\n(Model configuration)"];
22+
23+
// Thinking capability
24+
ThinkingPromptRunnerOperations [fillcolor=lightsteelblue, label="ThinkingPromptRunnerOperations\n(Thinking-aware operations)"];
25+
ThinkingResponse [fillcolor=lightpink, label="ThinkingResponse\n(Result + thinking blocks)"];
26+
27+
// Tool system
28+
ToolGroup [fillcolor=pink, label="ToolGroup\n(Coherent tool set)"];
29+
ToolGroupRequirement [fillcolor=lavender, label="ToolGroupRequirement\n(Tool dependency)"];
30+
ToolObject [fillcolor=wheat, label="ToolObject\n(@Tool annotated object)"];
31+
32+
// State and data flow
33+
Blackboard [fillcolor=lightsalmon, label="Blackboard\n(Shared state store)"];
34+
IoBinding [fillcolor=lightseagreen, label="IoBinding\n(Input/output binding)"];
35+
36+
// Prompt system
37+
PromptContributor [fillcolor=lavender, label="PromptContributor\n(Prompt element)"];
38+
Message [fillcolor=lightsteelblue, label="Message\n(Conversation element)"];
39+
40+
// Context hierarchy relationships
41+
ProcessContext -> OperationContext [label="provides"];
42+
OperationContext -> ActionContext [label="specializes to"];
43+
44+
// LLM integration relationships
45+
OperationContext -> PromptRunner [label="creates"];
46+
ActionContext -> PromptRunner [label="enhances"];
47+
PromptRunner -> LlmOperations [label="delegates to"];
48+
PromptRunner -> LlmOptions [label="configured by"];
49+
50+
// Thinking integration
51+
PromptRunner -> ThinkingPromptRunnerOperations [label="withThinking()"];
52+
ThinkingPromptRunnerOperations -> ThinkingResponse [label="returns"];
53+
54+
// Tool integration relationships
55+
PromptRunner -> ToolGroup [label="with tool groups"];
56+
PromptRunner -> ToolObject [label="with tool objects"];
57+
ActionContext -> ToolGroupRequirement [label="declares"];
58+
ToolGroupRequirement -> ToolGroup [label="requires"];
59+
60+
// State and data relationships
61+
OperationContext -> Blackboard [label="accesses"];
62+
ActionContext -> Blackboard [label="reads/writes"];
63+
Blackboard -> IoBinding [label="stores via"];
64+
65+
// Prompt construction relationships
66+
PromptRunner -> PromptContributor [label="with contributors"];
67+
PromptRunner -> Message [label="with messages"];
68+
69+
// Additional flow relationships
70+
ProcessContext -> LlmOperations [label="provides", style="dashed"];
71+
ActionContext -> ToolObject [label="creates from domain objects", style="dashed"];
72+
OperationContext -> IoBinding [label="manages", style="dashed"];
73+
}

‎embabel-agent-docs/src/main/asciidoc/reference/diagrams/architecture/embabel_planning_system.dot‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
digraph PlanningSystem {
2+
// Node styling
3+
node [shape=box, style="filled,rounded", fontname="Arial", margin=0.2, fontsize=12];
4+
edge [fontname="Arial", fontsize=11];
5+
6+
// Key components
7+
Action [fillcolor=lightblue, label="Action\n(Core executable unit)"];
8+
Condition [fillcolor=lightgreen, label="Condition\n(Named predicate)"];
9+
Blackboard [fillcolor=lightyellow, label="Blackboard\n(Shared memory system)"];
10+
WorldState [fillcolor=lightcoral, label="WorldState\n(System conditions map)"];
11+
Plan [fillcolor=lightgrey, label="Plan\n(Sequence of Actions)"];
12+
Goal [fillcolor=pink, label="Goal\n(Desired end state)"];
13+
Planner [fillcolor=lightcyan, label="Planner\n(GOAP / Utility)"];
14+
PlanningSystem [fillcolor=lavender, label="PlanningSystem\n(Actions + Goals + Conditions)"];
15+
IoBinding [fillcolor=lightpink, label="IoBinding\n(Input/output binding)"];
16+
17+
// Relationships
18+
Action -> Condition [label="has preconditions"];
19+
Action -> WorldState [label="produces effects on"];
20+
Action -> Blackboard [label="reads from/writes to"];
21+
Action -> IoBinding [label="defines inputs/outputs via"];
22+
23+
Condition -> WorldState [label="evaluated against"];
24+
25+
Goal -> Condition [label="defined by"];
26+
27+
Blackboard -> WorldState [label="determines"];
28+
29+
WorldState -> Planner [label="informs"];
30+
31+
Planner -> Plan [label="creates"];
32+
Planner -> Action [label="selects"];
33+
Planner -> Goal [label="satisfies"];
34+
35+
Plan -> Action [label="contains sequence of"];
36+
Plan -> Goal [label="achieves"];
37+
38+
PlanningSystem -> Action [label="contains available"];
39+
PlanningSystem -> Goal [label="contains possible"];
40+
PlanningSystem -> Planner [label="used by"];
41+
42+
// Additional relationships
43+
Blackboard -> Condition [label="stores state for", style="dashed"];
44+
WorldState -> Action [label="determines achievability of", style="dashed"];
45+
Action -> Plan [label="executed according to", dir="back", style="dashed"];
46+
}

‎embabel-agent-docs/src/main/asciidoc/reference/planners/page.adoc‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -675,3 +675,9 @@ Both `SupervisorInvocation` and <<reference.tools__agentic-tools,AgenticTool>> p
675675

676676
Use `AgenticTool` when you need a tool that internally orchestrates other tools.
677677
Use `SupervisorInvocation` when you need a complete workflow that produces a typed result with full blackboard state management.
678+
679+
680+
[graphviz, embabel_planning_system.dot, png]
681+
----
682+
include::../diagrams/architecture/embabel_planning_system.dot[]
683+
----

0 commit comments

Comments
 (0)