How adam-h-ds/tinyagents works
Project type and purpose
• TinyAgents is an open-source Python library for building and orchestrating agentic applications using a lightweight graph DSL.
• It provides decorators to wrap existing functions or classes as “chainable” nodes, compiles graphs into runners, and optionally integrates with Ray Serve and OpenTelemetry tracing.
File structure
• Core package (tinyagents/):
• graph.py – graph builder, compile & invoke API
• decorators.py, callbacks.py, handlers.py – glue code for node execution & lifecycle hooks
• deployment_utils.py – Ray Serve integration
• tracing/ – OpenTelemetry instrumentation
• utils.py, types.py – shared utilities and type definitions
• Configuration: pyproject.toml, mypy.ini
• CI/CD: .github/workflows/publish.yml
• Docs & Examples: docs/, examples/
• Tests: test/
• Metadata: README.md, LICENSE, .gitignore
README for additional insights
• Two execution backends:
a. Local executor (ThreadPoolExecutor)
b. Ray Serve (via deployment_utils)
• Tracing via OpenTelemetry following OpenInference conventions, visualizable in Arize Phoenix.
1. User application
• Chainable functions & classes decorated by @chainable
• Graph definition (using operators |, &, /, loop())
2. TinyAgents core
• Graph Builder (tinyagents/graph.py)
• Node Types (tinyagents/nodes/)
• Decorators & Callbacks
• Utils & Types
3. Execution Layer
• Local Executor (ThreadPoolExecutor)
• Ray Serve Deployment (deployment_utils.py → Ray Serve cluster)
4. Tracing
• OpenTelemetry instrumentation (tinyagents/tracing/)
• External Collector / Arize Phoenix
5. CI/CD & Packaging
• GitHub Actions → PyPI publishing
• Configuration files
• From User App → Graph Builder: “define & compile graph”
• Graph Builder → Execution Layer: “runner.invoke()”
• Execution Layer → Node implementations (via decorators, callbacks)
• Execution Layer → Tracing: “emit spans” → Collector
• Ray Serve path: Graph Builder (compile with use_ray=True) → Ray deployments → client requests
c. Architectural patterns & principles
• DSL / Fluent API for graph composition
• Decorator pattern to wrap user code as nodes
• Strategy pattern for pluggable executors (ThreadPool vs Ray)
• OpenTelemetry instrumentation inserted transparently when enabled
d. Key technologies & frameworks
• Python 3.8+
• ThreadPoolExecutor (stdlib)
• Ray & Ray Serve
• OpenTelemetry (semantic conventions from OpenInference)
• Pydantic (in examples)