System Context
Understanding where the Ainalyn SDK fits in the overall system architecture.
Application Architecture
SDK as a Compiler
The most important concept to understand: The SDK is a compiler, not a runtime.
Key Boundaries
What the SDK Does
| Responsibility | Description |
|---|---|
| Define | Provides builders to define Agent structure |
| Validate | Checks definition correctness before submission |
| Export | Produces platform-compatible YAML format |
| Compile | Complete workflow: validate → serialize → output |
What the SDK Does NOT Do
| NOT Responsibility | Why |
|---|---|
| Execute agents | Platform Core handles execution |
| Call LLMs | Platform Core manages LLM interactions |
| Manage state | Platform Core handles runtime state |
| Handle I/O | Platform Core manages external integrations |
The Compilation Analogy
Think of Ainalyn SDK like a programming language compiler:
┌─────────────────────────────────────────────────────────────────────┐
│ Traditional Compiler │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ Source Code (.py) ──▶ Compiler ──▶ Bytecode (.pyc) │
│ │
│ The compiler doesn't run your program; │
│ it produces something that can be run later. │
│ │
└─────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────┐
│ Ainalyn SDK │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ Python Builders ──▶ SDK ──▶ Agent Definition (YAML) │
│ │
│ The SDK doesn't run your agent; │
│ it produces a definition that Platform Core executes. │
│ │
└─────────────────────────────────────────────────────────────────────┘Data Flow Overview
Developer SDK Platform
──────── ─── ────────
│ │ │
│ 1. Write Python code │ │
│ using builders │ │
│ │ │
├─────────────────────────▶│ │
│ │ │
│ │ 2. Validate structure │
│ │ Check references │
│ │ Detect cycles │
│ │ │
│ │ 3. Serialize to YAML │
│ │ │
│◀─────────────────────────┤ │
│ 4. Return YAML / errors │ │
│ │ │
│ │ │
├──────────────────────────┼────────────────────────────▶│
│ 5. Submit YAML to platform │
│ │ │
│ │ │ 6. Parse YAML
│ │ │ 7. Execute agent
│ │ │ 8. Call LLMs
│ │ │ 9. Return results
│ │ │Why This Separation?
Benefits of Compiler Pattern
-
Offline Validation
- Catch errors before deployment
- No network calls needed for validation
- Fast feedback loop for developers
-
Platform Independence
- SDK produces a standard format (YAML)
- Platform can evolve independently
- Multiple platforms could consume the same format
-
Clear Responsibility
- SDK: definition correctness
- Platform: execution correctness
- No confusion about where bugs originate
-
Testability
- Test definitions without running agents
- Mock-free unit tests for SDK
- Integration tests only at platform level
What Gets Compiled
The SDK compiles your Python builder calls into an Agent Definition:
Input (Python):
from ainalyn import AgentBuilder, WorkflowBuilder, NodeBuilder
agent = (
AgentBuilder("customer-support")
.version("1.0.0")
.description("Handles customer inquiries")
.add_workflow(
WorkflowBuilder("handle-inquiry")
.add_node(NodeBuilder("classify").type("llm").build())
.add_node(NodeBuilder("respond").type("llm").build())
.add_edge("classify", "respond")
.build()
)
.build()
)Output (YAML):
name: customer-support
version: 1.0.0
description: Handles customer inquiries
workflows:
- name: handle-inquiry
nodes:
- id: classify
type: llm
- id: respond
type: llm
edges:
- from: classify
to: respondRelated Pages
- Hexagonal Architecture - Internal SDK architecture
- Compilation Flow - Detailed compilation process