agent99 0.0.4 → 0.0.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (92) hide show
  1. checksums.yaml +4 -4
  2. data/A2A_SPEC-dev.md +1829 -0
  3. data/CHANGELOG.md +31 -0
  4. data/COMMITS.md +196 -0
  5. data/DOCS.md +96 -0
  6. data/README.md +200 -78
  7. data/Rakefile +62 -0
  8. data/docs/AI/htm.md +215 -0
  9. data/docs/AI/htm.rb +141 -0
  10. data/docs/AI/htm_demo.db +0 -0
  11. data/docs/AI/notes_on_htm_implementation.md +1319 -0
  12. data/docs/AI/some_code.rb +692 -0
  13. data/docs/advanced-topics/a2a-protocol.md +13 -0
  14. data/docs/{control_actions.md → advanced-topics/control-actions.md} +2 -0
  15. data/docs/advanced-topics/model-context-protocol.md +4 -0
  16. data/docs/advanced-topics/multi-agent-processing.md +674 -0
  17. data/docs/agent-development/request-response-handling.md +512 -0
  18. data/docs/api-reference/agent99-base.md +463 -0
  19. data/docs/api-reference/message-clients.md +495 -0
  20. data/docs/api-reference/registry-client.md +470 -0
  21. data/docs/api-reference/schemas.md +518 -0
  22. data/docs/assets/css/custom.css +27 -0
  23. data/docs/assets/images/agent-lifecycle.svg +73 -0
  24. data/docs/assets/images/agent-registry-process.svg +86 -0
  25. data/docs/assets/images/agent-registry-processes.svg +114 -0
  26. data/docs/assets/images/agent-types-overview.svg +51 -0
  27. data/docs/assets/images/agent99-architecture.svg +85 -0
  28. data/docs/assets/images/agent99_logo.png +0 -0
  29. data/docs/assets/images/control-actions-state.svg +83 -0
  30. data/docs/assets/images/knowledge-graph.svg +77 -0
  31. data/docs/assets/images/message-processing-flow.svg +148 -0
  32. data/docs/assets/images/multi-agent-system.svg +66 -0
  33. data/docs/assets/images/proxy-pattern-sequence.svg +48 -0
  34. data/docs/assets/images/request-flow.svg +97 -0
  35. data/docs/assets/images/request-processing-lifecycle.svg +50 -0
  36. data/docs/assets/images/request-response-sequence.svg +39 -0
  37. data/docs/{agent_lifecycle.md → core-concepts/agent-lifecycle.md} +2 -0
  38. data/docs/core-concepts/agent-types.md +255 -0
  39. data/docs/{architecture.md → core-concepts/architecture.md} +5 -5
  40. data/docs/{what_is_an_agent.md → core-concepts/what-is-an-agent.md} +1 -1
  41. data/docs/diagrams/message-flow-sequence.svg +198 -0
  42. data/docs/diagrams/p2p-network-topology.svg +181 -0
  43. data/docs/diagrams/smart-transport-routing.svg +165 -0
  44. data/docs/diagrams/three-layer-architecture.svg +77 -0
  45. data/docs/diagrams/transport-extension-api.svg +309 -0
  46. data/docs/diagrams/transport-extension-architecture.svg +234 -0
  47. data/docs/diagrams/transport-selection-flowchart.svg +264 -0
  48. data/docs/examples/advanced-examples.md +951 -0
  49. data/docs/examples/basic-examples.md +268 -0
  50. data/docs/{agent_registry_processes.md → framework-components/agent-registry.md} +1 -1
  51. data/docs/{message_processing.md → framework-components/message-processing.md} +3 -1
  52. data/docs/getting-started/basic-example.md +306 -0
  53. data/docs/getting-started/installation.md +160 -0
  54. data/docs/getting-started/overview.md +64 -0
  55. data/docs/getting-started/quick-start.md +179 -0
  56. data/docs/index.md +97 -0
  57. data/examples/DEMO.md +148 -0
  58. data/examples/README.md +50 -0
  59. data/examples/bad_agent.rb +32 -0
  60. data/examples/registry.rb +0 -8
  61. data/examples/run_demo.rb +433 -0
  62. data/lib/agent99/amqp_message_client.rb +2 -2
  63. data/lib/agent99/base.rb +1 -1
  64. data/lib/agent99/message_processing.rb +6 -12
  65. data/lib/agent99/registry_client.rb +4 -1
  66. data/lib/agent99/version.rb +1 -1
  67. data/lib/agent99.rb +1 -1
  68. data/mkdocs.yml +195 -0
  69. data/p2p_plan.md +533 -0
  70. data/p2p_roadmap.md +299 -0
  71. data/registry_plan.md +1818 -0
  72. metadata +89 -32
  73. data/docs/README.md +0 -57
  74. data/docs/diagrams/agent_registry_processes.dot +0 -42
  75. data/docs/diagrams/agent_registry_processes.png +0 -0
  76. data/docs/diagrams/high_level_architecture.dot +0 -26
  77. data/docs/diagrams/high_level_architecture.png +0 -0
  78. data/docs/diagrams/request_flow.dot +0 -42
  79. data/docs/diagrams/request_flow.png +0 -0
  80. /data/docs/{advanced_features.md → advanced-topics/advanced-features.md} +0 -0
  81. /data/docs/{extending_the_framework.md → advanced-topics/extending-the-framework.md} +0 -0
  82. /data/docs/{custom_agent_implementation.md → agent-development/custom-agent-implementation.md} +0 -0
  83. /data/docs/{error_handling_and_logging.md → agent-development/error-handling-and-logging.md} +0 -0
  84. /data/docs/{schema_definition.md → agent-development/schema-definition.md} +0 -0
  85. /data/docs/{api_reference.md → api-reference/overview.md} +0 -0
  86. /data/docs/{agent_discovery.md → framework-components/agent-discovery.md} +0 -0
  87. /data/docs/{messaging_system.md → framework-components/messaging-system.md} +0 -0
  88. /data/docs/{breaking_change_v0.0.4.md → operations/breaking-changes.md} +0 -0
  89. /data/docs/{configuration.md → operations/configuration.md} +0 -0
  90. /data/docs/{preformance_considerations.md → operations/performance-considerations.md} +0 -0
  91. /data/docs/{security.md → operations/security.md} +0 -0
  92. /data/docs/{troubleshooting.md → operations/troubleshooting.md} +0 -0
data/docs/assets/images/message-processing-flow.svg ADDED
@@ -0,0 +1,148 @@
1
+ <svg viewBox="0 0 800 600" xmlns="http://www.w3.org/2000/svg" style="background: transparent;">
2
+ <!-- Dark theme styles -->
3
+ <defs>
4
+ <style>
5
+ .title { fill: #e5e7eb; font-family: 'Arial', sans-serif; font-size: 18px; font-weight: bold; }
6
+ .subtitle { fill: #d1d5db; font-family: 'Arial', sans-serif; font-size: 14px; font-weight: bold; }
7
+ .text { fill: #d1d5db; font-family: 'Arial', sans-serif; font-size: 12px; }
8
+ .small-text { fill: #9ca3af; font-family: 'Arial', sans-serif; font-size: 10px; }
9
+ .request-box { fill: #1e40af; stroke: #3b82f6; stroke-width: 2; }
10
+ .response-box { fill: #dc2626; stroke: #ef4444; stroke-width: 2; }
11
+ .control-box { fill: #059669; stroke: #10b981; stroke-width: 2; }
12
+ .process-box { fill: #374151; stroke: #6b7280; stroke-width: 2; }
13
+ .arrow { stroke: #9ca3af; stroke-width: 2; fill: #9ca3af; }
14
+ .validation-box { fill: #7c2d12; stroke: #ea580c; stroke-width: 2; }
15
+ </style>
16
+ </defs>
17
+
18
+ <!-- Title -->
19
+ <text x="400" y="30" class="title" text-anchor="middle">Agent99 Message Processing Flow</text>
20
+
21
+ <!-- Incoming Messages Section -->
22
+ <text x="50" y="70" class="subtitle">Incoming Messages</text>
23
+
24
+ <!-- Request Message -->
25
+ <rect x="50" y="90" width="120" height="60" rx="5" class="request-box"/>
26
+ <text x="110" y="110" class="text" text-anchor="middle" fill="white">Request</text>
27
+ <text x="110" y="125" class="text" text-anchor="middle" fill="white">Message</text>
28
+ <text x="110" y="140" class="small-text" text-anchor="middle" fill="#bfdbfe">Client → Agent</text>
29
+
30
+ <!-- Response Message -->
31
+ <rect x="200" y="90" width="120" height="60" rx="5" class="response-box"/>
32
+ <text x="260" y="110" class="text" text-anchor="middle" fill="white">Response</text>
33
+ <text x="260" y="125" class="text" text-anchor="middle" fill="white">Message</text>
34
+ <text x="260" y="140" class="small-text" text-anchor="middle" fill="#fecaca">Agent → Client</text>
35
+
36
+ <!-- Control Message -->
37
+ <rect x="350" y="90" width="120" height="60" rx="5" class="control-box"/>
38
+ <text x="410" y="110" class="text" text-anchor="middle" fill="white">Control</text>
39
+ <text x="410" y="125" class="text" text-anchor="middle" fill="white">Message</text>
40
+ <text x="410" y="140" class="small-text" text-anchor="middle" fill="#a7f3d0">System Control</text>
41
+
42
+ <!-- Arrows pointing down -->
43
+ <path d="M110 160 L110 190" class="arrow" marker-end="url(#arrowhead)"/>
44
+ <path d="M260 160 L260 190" class="arrow" marker-end="url(#arrowhead)"/>
45
+ <path d="M410 160 L410 190" class="arrow" marker-end="url(#arrowhead)"/>
46
+
47
+ <!-- Validation Layer -->
48
+ <text x="50" y="220" class="subtitle">Validation &amp; Routing</text>
49
+
50
+ <!-- Schema Validation -->
51
+ <rect x="50" y="240" width="140" height="50" rx="5" class="validation-box"/>
52
+ <text x="120" y="260" class="text" text-anchor="middle" fill="white">Schema</text>
53
+ <text x="120" y="275" class="text" text-anchor="middle" fill="white">Validation</text>
54
+
55
+ <!-- Message Router -->
56
+ <rect x="220" y="240" width="140" height="50" rx="5" class="process-box"/>
57
+ <text x="290" y="260" class="text" text-anchor="middle" fill="white">Message</text>
58
+ <text x="290" y="275" class="text" text-anchor="middle" fill="white">Router</text>
59
+
60
+ <!-- Error Handler -->
61
+ <rect x="390" y="240" width="140" height="50" rx="5" class="validation-box"/>
62
+ <text x="460" y="260" class="text" text-anchor="middle" fill="white">Error</text>
63
+ <text x="460" y="275" class="text" text-anchor="middle" fill="white">Handler</text>
64
+
65
+ <!-- Arrows from validation to handlers -->
66
+ <path d="M120 300 L120 330" class="arrow" marker-end="url(#arrowhead)"/>
67
+ <path d="M290 300 L290 330" class="arrow" marker-end="url(#arrowhead)"/>
68
+ <path d="M460 300 L460 330" class="arrow" marker-end="url(#arrowhead)"/>
69
+
70
+ <!-- Processing Handlers -->
71
+ <text x="50" y="360" class="subtitle">Message Handlers</text>
72
+
73
+ <!-- Request Handler -->
74
+ <rect x="50" y="380" width="140" height="80" rx="5" class="request-box"/>
75
+ <text x="120" y="400" class="text" text-anchor="middle" fill="white">receive_request</text>
76
+ <text x="120" y="415" class="small-text" text-anchor="middle" fill="#bfdbfe">• Validate payload</text>
77
+ <text x="120" y="430" class="small-text" text-anchor="middle" fill="#bfdbfe">• Process action</text>
78
+ <text x="120" y="445" class="small-text" text-anchor="middle" fill="#bfdbfe">• Send response</text>
79
+
80
+ <!-- Response Handler -->
81
+ <rect x="220" y="380" width="140" height="80" rx="5" class="response-box"/>
82
+ <text x="290" y="400" class="text" text-anchor="middle" fill="white">receive_response</text>
83
+ <text x="290" y="415" class="small-text" text-anchor="middle" fill="#fecaca">• Process result</text>
84
+ <text x="290" y="430" class="small-text" text-anchor="middle" fill="#fecaca">• Trigger follow-up</text>
85
+ <text x="290" y="445" class="small-text" text-anchor="middle" fill="#fecaca">• Update state</text>
86
+
87
+ <!-- Control Handler -->
88
+ <rect x="390" y="380" width="140" height="80" rx="5" class="control-box"/>
89
+ <text x="460" y="395" class="small-text" text-anchor="middle" fill="white">Control Actions:</text>
90
+ <text x="460" y="410" class="small-text" text-anchor="middle" fill="#a7f3d0">• handle_shutdown</text>
91
+ <text x="460" y="425" class="small-text" text-anchor="middle" fill="#a7f3d0">• handle_pause</text>
92
+ <text x="460" y="440" class="small-text" text-anchor="middle" fill="#a7f3d0">• handle_resume</text>
93
+ <text x="460" y="455" class="small-text" text-anchor="middle" fill="#a7f3d0">• handle_status</text>
94
+
95
+ <!-- Final Processing -->
96
+ <path d="M120 470 L120 510" class="arrow" marker-end="url(#arrowhead)"/>
97
+ <path d="M290 470 L290 510" class="arrow" marker-end="url(#arrowhead)"/>
98
+ <path d="M460 470 L460 510" class="arrow" marker-end="url(#arrowhead)"/>
99
+
100
+ <!-- Results -->
101
+ <text x="50" y="540" class="subtitle">Results</text>
102
+
103
+ <rect x="50" y="560" width="120" height="30" rx="5" class="process-box"/>
104
+ <text x="110" y="580" class="small-text" text-anchor="middle" fill="white">Response Sent</text>
105
+
106
+ <rect x="200" y="560" width="120" height="30" rx="5" class="process-box"/>
107
+ <text x="260" y="580" class="small-text" text-anchor="middle" fill="white">Action Completed</text>
108
+
109
+ <rect x="350" y="560" width="120" height="30" rx="5" class="process-box"/>
110
+ <text x="410" y="580" class="small-text" text-anchor="middle" fill="white">State Updated</text>
111
+
112
+ <!-- Error Flow -->
113
+ <path d="M190 265 L350 265" class="arrow" stroke="#ef4444" stroke-dasharray="5,5"/>
114
+ <text x="270" y="260" class="small-text" fill="#ef4444">validation fails</text>
115
+
116
+ <!-- Arrow marker definition -->
117
+ <defs>
118
+ <marker id="arrowhead" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
119
+ <polygon points="0 0, 10 3.5, 0 7" fill="#9ca3af"/>
120
+ </marker>
121
+ </defs>
122
+
123
+ <!-- Legend -->
124
+ <rect x="550" y="90" width="200" height="180" rx="5" fill="none" stroke="#6b7280" stroke-width="1" stroke-dasharray="3,3"/>
125
+ <text x="560" y="110" class="subtitle">Message Types</text>
126
+
127
+ <rect x="560" y="120" width="15" height="15" class="request-box"/>
128
+ <text x="580" y="132" class="small-text">Request Messages</text>
129
+
130
+ <rect x="560" y="140" width="15" height="15" class="response-box"/>
131
+ <text x="580" y="152" class="small-text">Response Messages</text>
132
+
133
+ <rect x="560" y="160" width="15" height="15" class="control-box"/>
134
+ <text x="580" y="172" class="small-text">Control Messages</text>
135
+
136
+ <rect x="560" y="180" width="15" height="15" class="process-box"/>
137
+ <text x="580" y="192" class="small-text">Processing Steps</text>
138
+
139
+ <rect x="560" y="200" width="15" height="15" class="validation-box"/>
140
+ <text x="580" y="212" class="small-text">Validation/Errors</text>
141
+
142
+ <text x="560" y="230" class="subtitle">Flow Types</text>
143
+ <line x1="560" y1="240" x2="580" y2="240" class="arrow"/>
144
+ <text x="585" y="244" class="small-text">Normal Flow</text>
145
+
146
+ <line x1="560" y1="250" x2="580" y2="250" stroke="#ef4444" stroke-dasharray="3,3" stroke-width="2"/>
147
+ <text x="585" y="254" class="small-text">Error Flow</text>
148
+ </svg>
data/docs/assets/images/multi-agent-system.svg ADDED
@@ -0,0 +1,66 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 500" style="background: transparent;">
2
+ <defs>
3
+ <linearGradient id="grad1" x1="0%" y1="0%" x2="100%" y2="100%">
4
+ <stop offset="0%" style="stop-color:#2a2a3e;stop-opacity:1" />
5
+ <stop offset="100%" style="stop-color:#1a1a2e;stop-opacity:1" />
6
+ </linearGradient>
7
+ <filter id="shadow">
8
+ <feGaussianBlur in="SourceAlpha" stdDeviation="3"/>
9
+ <feOffset dx="2" dy="2" result="offsetblur"/>
10
+ <feComponentTransfer>
11
+ <feFuncA type="linear" slope="0.3"/>
12
+ </feComponentTransfer>
13
+ <feMerge>
14
+ <feMergeNode/>
15
+ <feMergeNode in="SourceGraphic"/>
16
+ </feMerge>
17
+ </filter>
18
+ </defs>
19
+
20
+ <!-- Process 1 Container -->
21
+ <rect x="50" y="50" width="280" height="180" rx="10" fill="url(#grad1)" stroke="#66b3ff" stroke-width="2" stroke-dasharray="5,3" filter="url(#shadow)"/>
22
+ <text x="190" y="75" text-anchor="middle" font-family="monospace" font-size="14" fill="#99ccff" font-weight="bold">Process 1</text>
23
+
24
+ <!-- Agents in Process 1 -->
25
+ <rect x="80" y="100" width="70" height="40" rx="5" fill="#2a2a3e" stroke="#66ff99" stroke-width="2"/>
26
+ <text x="115" y="125" text-anchor="middle" font-family="monospace" font-size="12" fill="#e0e0e0">Agent A</text>
27
+
28
+ <rect x="170" y="100" width="70" height="40" rx="5" fill="#2a2a3e" stroke="#66ff99" stroke-width="2"/>
29
+ <text x="205" y="125" text-anchor="middle" font-family="monospace" font-size="12" fill="#e0e0e0">Agent B</text>
30
+
31
+ <rect x="125" y="160" width="70" height="40" rx="5" fill="#2a2a3e" stroke="#66ff99" stroke-width="2"/>
32
+ <text x="160" y="185" text-anchor="middle" font-family="monospace" font-size="12" fill="#e0e0e0">Agent C</text>
33
+
34
+ <!-- Process 2 Container -->
35
+ <rect x="470" y="50" width="280" height="180" rx="10" fill="url(#grad1)" stroke="#ff9966" stroke-width="2" stroke-dasharray="5,3" filter="url(#shadow)"/>
36
+ <text x="610" y="75" text-anchor="middle" font-family="monospace" font-size="14" fill="#ffcc99" font-weight="bold">Process 2</text>
37
+
38
+ <!-- Agents in Process 2 -->
39
+ <rect x="530" y="100" width="70" height="40" rx="5" fill="#2a2a3e" stroke="#ff66ff" stroke-width="2"/>
40
+ <text x="565" y="125" text-anchor="middle" font-family="monospace" font-size="12" fill="#e0e0e0">Agent D</text>
41
+
42
+ <rect x="620" y="100" width="70" height="40" rx="5" fill="#2a2a3e" stroke="#ff66ff" stroke-width="2"/>
43
+ <text x="655" y="125" text-anchor="middle" font-family="monospace" font-size="12" fill="#e0e0e0">Agent E</text>
44
+
45
+ <!-- Message Broker Container -->
46
+ <rect x="250" y="320" width="300" height="100" rx="10" fill="#1a1a2e" stroke="#9966ff" stroke-width="3" filter="url(#shadow)"/>
47
+ <text x="400" y="350" text-anchor="middle" font-family="monospace" font-size="16" fill="#cc99ff" font-weight="bold">Message Broker</text>
48
+ <text x="400" y="380" text-anchor="middle" font-family="monospace" font-size="14" fill="#b388ff">NATS/AMQP</text>
49
+
50
+ <!-- Connection lines -->
51
+ <!-- From Process 1 agents to Message Broker -->
52
+ <path d="M 115 140 L 350 320" stroke="#66ff99" stroke-width="1.5" stroke-dasharray="3,2" opacity="0.7"/>
53
+ <path d="M 205 140 L 380 320" stroke="#66ff99" stroke-width="1.5" stroke-dasharray="3,2" opacity="0.7"/>
54
+ <path d="M 160 200 L 340 320" stroke="#66ff99" stroke-width="1.5" stroke-dasharray="3,2" opacity="0.7"/>
55
+
56
+ <!-- From Process 2 agents to Message Broker -->
57
+ <path d="M 565 140 L 450 320" stroke="#ff66ff" stroke-width="1.5" stroke-dasharray="3,2" opacity="0.7"/>
58
+ <path d="M 655 140 L 480 320" stroke="#ff66ff" stroke-width="1.5" stroke-dasharray="3,2" opacity="0.7"/>
59
+
60
+ <!-- Connection dots -->
61
+ <circle cx="350" cy="320" r="4" fill="#66ff99"/>
62
+ <circle cx="380" cy="320" r="4" fill="#66ff99"/>
63
+ <circle cx="340" cy="320" r="4" fill="#66ff99"/>
64
+ <circle cx="450" cy="320" r="4" fill="#ff66ff"/>
65
+ <circle cx="480" cy="320" r="4" fill="#ff66ff"/>
66
+ </svg>
data/docs/assets/images/proxy-pattern-sequence.svg ADDED
@@ -0,0 +1,48 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 700 500" style="background: transparent;">
2
+ <defs>
3
+ <marker id="arrow-prx" markerWidth="10" markerHeight="10" refX="9" refY="5" orient="auto">
4
+ <path d="M0,0 L10,5 L0,10" fill="none" stroke="#66b3ff" stroke-width="1.5"/>
5
+ </marker>
6
+ </defs>
7
+
8
+ <!-- Client -->
9
+ <rect x="50" y="40" width="100" height="40" rx="5" fill="#2a2a3e" stroke="#66b3ff" stroke-width="2"/>
10
+ <text x="100" y="65" text-anchor="middle" font-family="monospace" font-size="14" fill="#e0e0e0">Client</text>
11
+ <line x1="100" y1="80" x2="100" y2="460" stroke="#444" stroke-width="1" stroke-dasharray="5,5"/>
12
+
13
+ <!-- Hybrid Agent -->
14
+ <rect x="280" y="40" width="120" height="40" rx="5" fill="#2a2a3e" stroke="#ff9966" stroke-width="2"/>
15
+ <text x="340" y="65" text-anchor="middle" font-family="monospace" font-size="14" fill="#e0e0e0">Hybrid Agent</text>
16
+ <line x1="340" y1="80" x2="340" y2="460" stroke="#444" stroke-width="1" stroke-dasharray="5,5"/>
17
+
18
+ <!-- Server -->
19
+ <rect x="530" y="40" width="100" height="40" rx="5" fill="#2a2a3e" stroke="#66b3ff" stroke-width="2"/>
20
+ <text x="580" y="65" text-anchor="middle" font-family="monospace" font-size="14" fill="#e0e0e0">Server</text>
21
+ <line x1="580" y1="80" x2="580" y2="460" stroke="#444" stroke-width="1" stroke-dasharray="5,5"/>
22
+
23
+ <!-- Request from Client -->
24
+ <path d="M 100 120 L 330 120" stroke="#66b3ff" stroke-width="2" marker-end="url(#arrow-prx)"/>
25
+ <text x="215" y="110" text-anchor="middle" font-family="monospace" font-size="11" fill="#99ccff">Request</text>
26
+
27
+ <!-- Check cache/policy -->
28
+ <rect x="325" y="140" width="30" height="50" rx="3" fill="#3a3a5e" stroke="#ff9966" stroke-width="1"/>
29
+ <text x="370" y="160" font-family="monospace" font-size="10" fill="#ffcc99">Check cache/</text>
30
+ <text x="370" y="175" font-family="monospace" font-size="10" fill="#ffcc99">policy</text>
31
+
32
+ <!-- Forward request -->
33
+ <path d="M 340 220 L 570 220" stroke="#66b3ff" stroke-width="2" marker-end="url(#arrow-prx)"/>
34
+ <text x="455" y="210" text-anchor="middle" font-family="monospace" font-size="11" fill="#99ccff">Forward request</text>
35
+
36
+ <!-- Response from Server -->
37
+ <path d="M 580 280 L 350 280" stroke="#66ff99" stroke-width="2" marker-end="url(#arrow-prx)"/>
38
+ <text x="465" y="270" text-anchor="middle" font-family="monospace" font-size="11" fill="#99ffcc">Response</text>
39
+
40
+ <!-- Update cache/stats -->
41
+ <rect x="325" y="300" width="30" height="50" rx="3" fill="#3a3a5e" stroke="#ff9966" stroke-width="1"/>
42
+ <text x="370" y="320" font-family="monospace" font-size="10" fill="#ffcc99">Update cache/</text>
43
+ <text x="370" y="335" font-family="monospace" font-size="10" fill="#ffcc99">stats</text>
44
+
45
+ <!-- Forward response -->
46
+ <path d="M 340 380 L 110 380" stroke="#66ff99" stroke-width="2" marker-end="url(#arrow-prx)"/>
47
+ <text x="225" y="370" text-anchor="middle" font-family="monospace" font-size="11" fill="#99ffcc">Forward response</text>
48
+ </svg>
data/docs/assets/images/request-flow.svg ADDED
@@ -0,0 +1,97 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 700 650" style="background: transparent;">
2
+ <defs>
3
+ <marker id="arrow-req" markerWidth="10" markerHeight="10" refX="9" refY="5" orient="auto">
4
+ <path d="M0,0 L10,5 L0,10 L5,5 z" fill="#66b3ff"/>
5
+ </marker>
6
+ <marker id="arrow-err" markerWidth="10" markerHeight="10" refX="9" refY="5" orient="auto">
7
+ <path d="M0,0 L10,5 L0,10 L5,5 z" fill="#ff6666"/>
8
+ </marker>
9
+ <filter id="shadow">
10
+ <feGaussianBlur in="SourceAlpha" stdDeviation="2"/>
11
+ <feOffset dx="1" dy="1" result="offsetblur"/>
12
+ <feComponentTransfer>
13
+ <feFuncA type="linear" slope="0.3"/>
14
+ </feComponentTransfer>
15
+ <feMerge>
16
+ <feMergeNode/>
17
+ <feMergeNode in="SourceGraphic"/>
18
+ </feMerge>
19
+ </filter>
20
+ </defs>
21
+
22
+ <!-- Title -->
23
+ <text x="350" y="30" text-anchor="middle" font-family="monospace" font-size="18" fill="#e0e0e0" font-weight="bold">Request Message Processing Flow</text>
24
+
25
+ <!-- Start: Message Arrives -->
26
+ <ellipse cx="350" cy="80" rx="80" ry="30" fill="#2a2a3e" stroke="#66b3ff" stroke-width="2" filter="url(#shadow)"/>
27
+ <text x="350" y="85" text-anchor="middle" font-family="monospace" font-size="12" fill="#99ccff">Message Arrives</text>
28
+
29
+ <!-- dispatcher() -->
30
+ <rect x="250" y="140" width="200" height="60" rx="8" fill="#2a2a3e" stroke="#9966ff" stroke-width="2" filter="url(#shadow)"/>
31
+ <text x="350" y="165" text-anchor="middle" font-family="monospace" font-size="12" fill="#cc99ff" font-weight="bold">dispatcher()</text>
32
+ <text x="350" y="185" text-anchor="middle" font-family="monospace" font-size="10" fill="#b388ff">Message Processing Loop</text>
33
+
34
+ <!-- process_request(message) -->
35
+ <rect x="250" y="240" width="200" height="50" rx="8" fill="#2a2a3e" stroke="#66ff99" stroke-width="2" filter="url(#shadow)"/>
36
+ <text x="350" y="265" text-anchor="middle" font-family="monospace" font-size="12" fill="#99ffcc">process_request(message)</text>
37
+
38
+ <!-- validate_schema() -->
39
+ <rect x="250" y="330" width="200" height="50" rx="8" fill="#2a2a3e" stroke="#ffcc66" stroke-width="2" filter="url(#shadow)"/>
40
+ <text x="350" y="355" text-anchor="middle" font-family="monospace" font-size="12" fill="#ffdd99">validate_schema()</text>
41
+
42
+ <!-- Decision Diamond (represented as polygon) -->
43
+ <polygon points="350,410 420,440 350,470 280,440" fill="#3a3a5e" stroke="#66b3ff" stroke-width="2"/>
44
+ <text x="350" y="445" text-anchor="middle" font-family="monospace" font-size="11" fill="#99ccff">Valid?</text>
45
+
46
+ <!-- Success Path: receive_request() -->
47
+ <rect x="100" y="510" width="200" height="60" rx="8" fill="#2a2a3e" stroke="#66ff99" stroke-width="2" filter="url(#shadow)"/>
48
+ <text x="200" y="535" text-anchor="middle" font-family="monospace" font-size="12" fill="#99ffcc" font-weight="bold">receive_request()</text>
49
+ <text x="200" y="555" text-anchor="middle" font-family="monospace" font-size="10" fill="#66ff99">Agent Implementation</text>
50
+
51
+ <!-- send_response() -->
52
+ <rect x="100" y="600" width="200" height="50" rx="8" fill="#2a2a3e" stroke="#66b3ff" stroke-width="2" filter="url(#shadow)" stroke-dasharray="5,3" opacity="0.8"/>
53
+ <text x="200" y="620" text-anchor="middle" font-family="monospace" font-size="12" fill="#99ccff">send_response()</text>
54
+ <text x="200" y="635" text-anchor="middle" font-family="monospace" font-size="10" fill="#66b3ff">Optional Response</text>
55
+
56
+ <!-- Error Path: Error Handler -->
57
+ <rect x="400" y="510" width="200" height="50" rx="8" fill="#2a2a3e" stroke="#ff6666" stroke-width="2" filter="url(#shadow)"/>
58
+ <text x="500" y="535" text-anchor="middle" font-family="monospace" font-size="12" fill="#ff9999">Error Handler</text>
59
+
60
+ <!-- Send Error Response -->
61
+ <rect x="400" y="600" width="200" height="50" rx="8" fill="#2a2a3e" stroke="#ff6666" stroke-width="2" filter="url(#shadow)"/>
62
+ <text x="500" y="625" text-anchor="middle" font-family="monospace" font-size="12" fill="#ff9999">Send Error Response</text>
63
+
64
+ <!-- Arrows -->
65
+ <!-- Main flow -->
66
+ <path d="M 350 110 L 350 140" stroke="#66b3ff" stroke-width="2" marker-end="url(#arrow-req)"/>
67
+ <path d="M 350 200 L 350 240" stroke="#9966ff" stroke-width="2" marker-end="url(#arrow-req)"/>
68
+ <path d="M 350 290 L 350 330" stroke="#66ff99" stroke-width="2" marker-end="url(#arrow-req)"/>
69
+ <path d="M 350 380 L 350 410" stroke="#ffcc66" stroke-width="2" marker-end="url(#arrow-req)"/>
70
+
71
+ <!-- Success path -->
72
+ <path d="M 280 440 L 200 510" stroke="#66ff99" stroke-width="2" marker-end="url(#arrow-req)"/>
73
+ <text x="220" y="475" font-family="monospace" font-size="10" fill="#66ff99">Valid</text>
74
+
75
+ <!-- Optional response (dashed) -->
76
+ <path d="M 200 570 L 200 600" stroke="#66b3ff" stroke-width="1.5" stroke-dasharray="5,3" marker-end="url(#arrow-req)"/>
77
+
78
+ <!-- Error path -->
79
+ <path d="M 420 440 L 500 510" stroke="#ff6666" stroke-width="2" marker-end="url(#arrow-err)"/>
80
+ <text x="470" y="475" font-family="monospace" font-size="10" fill="#ff6666">Invalid</text>
81
+
82
+ <path d="M 500 560 L 500 600" stroke="#ff6666" stroke-width="2" marker-end="url(#arrow-err)"/>
83
+
84
+ <!-- Notes -->
85
+ <rect x="30" y="320" width="180" height="70" rx="5" fill="#3a3a4e" stroke="#666" stroke-width="1" opacity="0.9"/>
86
+ <text x="120" y="340" text-anchor="middle" font-family="monospace" font-size="10" fill="#ffdd99" font-weight="bold">Schema validation</text>
87
+ <text x="120" y="355" text-anchor="middle" font-family="monospace" font-size="9" fill="#ccc">ensures message</text>
88
+ <text x="120" y="370" text-anchor="middle" font-family="monospace" font-size="9" fill="#ccc">integrity</text>
89
+
90
+ <rect x="30" y="480" width="180" height="70" rx="5" fill="#3a3a4e" stroke="#666" stroke-width="1" opacity="0.9"/>
91
+ <text x="120" y="500" text-anchor="middle" font-family="monospace" font-size="10" fill="#99ffcc" font-weight="bold">Custom processing</text>
92
+ <text x="120" y="515" text-anchor="middle" font-family="monospace" font-size="9" fill="#ccc">in agent subclass</text>
93
+
94
+ <!-- Dotted lines to notes -->
95
+ <path d="M 250 355 L 210 355" stroke="#666" stroke-width="1" stroke-dasharray="2,2"/>
96
+ <path d="M 100 540 L 30 515" stroke="#666" stroke-width="1" stroke-dasharray="2,2"/>
97
+ </svg>
data/docs/assets/images/request-processing-lifecycle.svg ADDED
@@ -0,0 +1,50 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 700 500" style="background: transparent;">
2
+ <defs>
3
+ <marker id="arrow-lc" markerWidth="10" markerHeight="10" refX="9" refY="5" orient="auto">
4
+ <path d="M0,0 L10,5 L0,10" fill="none" stroke="#66b3ff" stroke-width="1.5"/>
5
+ </marker>
6
+ </defs>
7
+
8
+ <!-- Message Broker -->
9
+ <rect x="50" y="40" width="140" height="40" rx="5" fill="#2a2a3e" stroke="#9966ff" stroke-width="2"/>
10
+ <text x="120" y="65" text-anchor="middle" font-family="monospace" font-size="14" fill="#e0e0e0">Message Broker</text>
11
+ <line x1="120" y1="80" x2="120" y2="460" stroke="#444" stroke-width="1" stroke-dasharray="5,5"/>
12
+
13
+ <!-- Agent -->
14
+ <rect x="280" y="40" width="100" height="40" rx="5" fill="#2a2a3e" stroke="#66b3ff" stroke-width="2"/>
15
+ <text x="330" y="65" text-anchor="middle" font-family="monospace" font-size="14" fill="#e0e0e0">Agent</text>
16
+ <line x1="330" y1="80" x2="330" y2="460" stroke="#444" stroke-width="1" stroke-dasharray="5,5"/>
17
+
18
+ <!-- process_request -->
19
+ <rect x="480" y="40" width="140" height="40" rx="5" fill="#2a2a3e" stroke="#66ff99" stroke-width="2"/>
20
+ <text x="550" y="65" text-anchor="middle" font-family="monospace" font-size="14" fill="#e0e0e0">process_request</text>
21
+ <line x1="550" y1="80" x2="550" y2="460" stroke="#444" stroke-width="1" stroke-dasharray="5,5"/>
22
+
23
+ <!-- Incoming message -->
24
+ <path d="M 120 110 L 320 110" stroke="#9966ff" stroke-width="2" marker-end="url(#arrow-lc)"/>
25
+ <text x="220" y="100" text-anchor="middle" font-family="monospace" font-size="11" fill="#cc99ff">Incoming message</text>
26
+
27
+ <!-- Validate headers -->
28
+ <rect x="315" y="130" width="30" height="35" rx="3" fill="#3a3a5e" stroke="#66b3ff" stroke-width="1"/>
29
+ <text x="360" y="152" font-family="monospace" font-size="10" fill="#99ccff">Validate headers</text>
30
+
31
+ <!-- Parse payload -->
32
+ <rect x="315" y="180" width="30" height="35" rx="3" fill="#3a3a5e" stroke="#66b3ff" stroke-width="1"/>
33
+ <text x="360" y="202" font-family="monospace" font-size="10" fill="#99ccff">Parse payload</text>
34
+
35
+ <!-- Call process_request -->
36
+ <path d="M 330 240 L 540 240" stroke="#66b3ff" stroke-width="2" marker-end="url(#arrow-lc)"/>
37
+ <text x="435" y="230" text-anchor="middle" font-family="monospace" font-size="11" fill="#99ccff">Call process_request(payload)</text>
38
+
39
+ <!-- Business logic -->
40
+ <rect x="535" y="260" width="30" height="35" rx="3" fill="#3a3a5e" stroke="#66ff99" stroke-width="1"/>
41
+ <text x="580" y="282" font-family="monospace" font-size="10" fill="#99ffcc">Business logic</text>
42
+
43
+ <!-- send_response/error -->
44
+ <path d="M 550 320 L 340 320" stroke="#66ff99" stroke-width="2" marker-end="url(#arrow-lc)"/>
45
+ <text x="445" y="310" text-anchor="middle" font-family="monospace" font-size="11" fill="#99ffcc">send_response() or send_error()</text>
46
+
47
+ <!-- Outgoing response -->
48
+ <path d="M 330 380 L 130 380" stroke="#9966ff" stroke-width="2" marker-end="url(#arrow-lc)"/>
49
+ <text x="230" y="370" text-anchor="middle" font-family="monospace" font-size="11" fill="#cc99ff">Outgoing response</text>
50
+ </svg>
data/docs/assets/images/request-response-sequence.svg ADDED
@@ -0,0 +1,39 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 600 400" style="background: transparent;">
2
+ <defs>
3
+ <marker id="arrow-seq" markerWidth="10" markerHeight="10" refX="9" refY="5" orient="auto">
4
+ <path d="M0,0 L10,5 L0,10" fill="none" stroke="#66b3ff" stroke-width="1.5"/>
5
+ </marker>
6
+ <filter id="glow">
7
+ <feGaussianBlur stdDeviation="2" result="coloredBlur"/>
8
+ <feMerge>
9
+ <feMergeNode in="coloredBlur"/>
10
+ <feMergeNode in="SourceGraphic"/>
11
+ </feMerge>
12
+ </filter>
13
+ </defs>
14
+
15
+ <!-- Client Agent -->
16
+ <rect x="80" y="40" width="120" height="40" rx="5" fill="#2a2a3e" stroke="#66b3ff" stroke-width="2"/>
17
+ <text x="140" y="65" text-anchor="middle" font-family="monospace" font-size="14" fill="#e0e0e0">Client Agent</text>
18
+ <line x1="140" y1="80" x2="140" y2="350" stroke="#444" stroke-width="1" stroke-dasharray="5,5"/>
19
+
20
+ <!-- Server Agent -->
21
+ <rect x="380" y="40" width="120" height="40" rx="5" fill="#2a2a3e" stroke="#66b3ff" stroke-width="2"/>
22
+ <text x="440" y="65" text-anchor="middle" font-family="monospace" font-size="14" fill="#e0e0e0">Server Agent</text>
23
+ <line x1="440" y1="80" x2="440" y2="350" stroke="#444" stroke-width="1" stroke-dasharray="5,5"/>
24
+
25
+ <!-- Request -->
26
+ <path d="M 140 120 L 430 120" stroke="#66b3ff" stroke-width="2" marker-end="url(#arrow-seq)" filter="url(#glow)"/>
27
+ <rect x="240" y="105" width="140" height="25" rx="3" fill="#1a1a2e" stroke="#66b3ff" stroke-width="1"/>
28
+ <text x="310" y="122" text-anchor="middle" font-family="monospace" font-size="12" fill="#99ccff">Request (payload)</text>
29
+
30
+ <!-- Process -->
31
+ <rect x="425" y="160" width="30" height="60" rx="3" fill="#3a3a5e" stroke="#ff9966" stroke-width="1"/>
32
+ <text x="490" y="193" font-family="monospace" font-size="11" fill="#ffcc99">Process</text>
33
+ <text x="490" y="208" font-family="monospace" font-size="11" fill="#ffcc99">request</text>
34
+
35
+ <!-- Response -->
36
+ <path d="M 440 260 L 150 260" stroke="#66ff99" stroke-width="2" marker-end="url(#arrow-seq)" filter="url(#glow)"/>
37
+ <rect x="240" y="245" width="140" height="25" rx="3" fill="#1a1a2e" stroke="#66ff99" stroke-width="1"/>
38
+ <text x="310" y="262" text-anchor="middle" font-family="monospace" font-size="12" fill="#99ffcc">Response (result)</text>
39
+ </svg>
data/docs/{agent_lifecycle.md → core-concepts/agent-lifecycle.md} RENAMED
@@ -6,6 +6,8 @@ The lifecycle of an agent within Agent99 consists of several key stages that are
6
6
 
7
7
  ### Lifecycle Stages
8
8
 
9
+ ![Agent Lifecycle](../assets/images/agent-lifecycle.svg)
10
+
9
11
  1. **Creation**: An agent is instantiated through the `Agent99::Base` class.
10
12
  2. **Initialization**: The agent sets up resources and establishes connections.
11
13
  3. **Running**: The agent processes messages and performs its designated tasks.