Eino Orchestration Agent¶

A deterministic orchestration agent built with Eino framework that provides more predictable and reliable workflow execution for finding verified statistics.

Overview¶

This project now includes two orchestration agents with different characteristics:

1. ADK Orchestration (Port 8000)¶

Framework: Google ADK (Agent Development Kit)
Approach: LLM-based decision making (Gemini 2.0 Flash)
Characteristics:
Flexible, adaptive behavior
Uses LLM for orchestration decisions
More dynamic but less predictable
Ideal for complex decision-making workflows

2. Eino Orchestration (Port 8003) ⭐ RECOMMENDED¶

Framework: Eino
Approach: Deterministic graph-based workflow
Characteristics:
Deterministic, predictable behavior
Type-safe graph orchestration
Compile-time validation
More reliable and faster
Recommended for production use

Why Eino for Orchestration?¶

Deterministic Workflow¶

The Eino orchestrator uses a directed graph with explicit nodes and edges, ensuring: - Same input → Same workflow execution path - No LLM decision-making for orchestration logic - Predictable resource usage and timing

Type Safety¶

Eino provides compile-time type checking:

Graph[*models.OrchestrationRequest, *models.OrchestrationResponse]

This ensures all nodes have compatible input/output types.

Performance¶

Faster: No LLM calls for orchestration decisions
Lower cost: Only uses LLMs in research/verification agents
More reliable: Graph compilation validates workflow before execution

Eino Workflow Graph¶

The Eino orchestrator implements this deterministic workflow:

START
  ↓
[1. Validate Input]
  ↓
[2. Research] ──────────→ Call Research Agent
  ↓
[3. Verification] ──────→ Call Verification Agent
  ↓
[4. Quality Check] ────→ Deterministic decision (verified >= target?)
  ↓
[5. Retry Research?] ──→ If needed, request more candidates
  ↓
[6. Format Response]
  ↓
END

Node Descriptions¶

Validate Input: Set defaults, validate parameters
Research: HTTP call to research agent for candidates
Verification: HTTP call to verification agent
Quality Check: Deterministic comparison (verified count vs target)
Retry Research: Conditional retry based on quality check
Format Response: Build final JSON output

Usage¶

Running the Eino Orchestrator¶

Option 1: Run with Eino orchestrator¶

make run-all-eino

This starts: - Research Agent (8001/9001) - Verification Agent (8002/9002) - Eino Orchestration Agent (8003/9003) ⭐

Option 2: Run Eino orchestrator separately¶

# Terminal 1: Research Agent
make run-research

# Terminal 2: Verification Agent
make run-verification

# Terminal 3: Eino Orchestrator
make run-orchestration-eino

API Calls¶

HTTP API¶

curl -X POST http://localhost:8003/orchestrate \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "climate change",
    "min_verified_stats": 10,
    "max_candidates": 30,
    "reputable_only": true
  }'

A2A Protocol (Port 9003)¶

The Eino orchestrator also supports A2A protocol for agent-to-agent communication.

Comparison: trpc-agent vs Eino¶

Feature	trpc-agent Orchestrator	Eino Orchestrator
Port	8000 (HTTP), 9000 (A2A)	8003 (HTTP), 9003 (A2A)
Decision Making	LLM-based	Deterministic
Predictability	Variable	Consistent
Performance	Slower (LLM calls)	Faster (no LLM)
Cost	Higher (LLM tokens)	Lower (no LLM)
Flexibility	High	Moderate
Type Safety	Runtime	Compile-time
Workflow	Dynamic	Static graph
Best For	Complex adaptive tasks	Predictable workflows

When to Use Which?¶

Use Eino Orchestrator When:¶

✅ You need deterministic, reproducible results
✅ You want faster response times
✅ You need lower costs (no LLM for orchestration)
✅ Your workflow is well-defined and stable
✅ You want compile-time type safety

Use ADK Orchestrator When:¶

✅ You need adaptive decision making
✅ Workflow logic changes based on content
✅ You want LLM reasoning for orchestration (Gemini 2.0 Flash)
✅ Requirements are less well-defined
✅ You need complex decision trees in orchestration

Eino Graph Implementation¶

Key Components¶

1. Lambda Nodes¶

Each step is implemented as an InvokableLambda:

validateInputLambda := compose.InvokableLambda(
    func(ctx context.Context, req *models.OrchestrationRequest) (*models.OrchestrationRequest, error) {
        // Validation logic
        return req, nil
    }
)
g.AddLambdaNode("validate_input", validateInputLambda)

2. Type-Safe State¶

State is passed through typed structs: - OrchestrationRequest → Input - ResearchState → After research - VerificationState → After verification - QualityDecision → After quality check - OrchestrationResponse → Output

3. Graph Edges¶

Edges define workflow sequence:

g.AddEdge(compose.START, "validate_input")
g.AddEdge("validate_input", "research")
g.AddEdge("research", "verification")
// ... etc

4. Graph Compilation¶

Graph is compiled before execution:

compiledGraph, err := oa.graph.Compile(ctx)
result, err := compiledGraph.Invoke(ctx, req)

Configuration¶

Environment Variables¶

ORCHESTRATOR_EINO_URL=http://localhost:8003

Add to your .env file to configure the Eino orchestrator URL.

Architecture Diagram¶

┌──────────────────────────────────────────────────────────┐
│                    USER REQUEST                          │
└──────────────────┬───────────────────────────────────────┘
                   │
                   │ Choose orchestrator:
                   ├─────────────────┬─────────────────────┐
                   │                 │                     │
                   ▼                 ▼                     ▼
         ┌─────────────────┐  ┌──────────────────┐  ┌────────────┐
         │   ORCHESTRATOR  │  │  ORCHESTRATOR    │  │   Direct   │
         │   (trpc-agent)  │  │    (Eino)        │  │   Call     │
         │   Port 8000     │  │   Port 8003      │  │            │
         │                 │  │                  │  │            │
         │  LLM-based      │  │  Deterministic   │  │            │
         │  decisions      │  │  graph workflow  │  │            │
         └────────┬────────┘  └────────┬─────────┘  └──────┬─────┘
                  │                    │                   │
                  └────────────┬───────┴───────────────────┘
                               │
                ┌──────────────┴──────────────┐
                │                             │
                ▼                             ▼
    ┌──────────────────────┐     ┌──────────────────────┐
    │  RESEARCH AGENT      │     │ VERIFICATION AGENT   │
    │  Port 8001           │     │ Port 8002            │
    └──────────────────────┘     └──────────────────────┘

Benefits of Dual Orchestrators¶

Flexibility: Choose the right tool for your use case
Comparison: A/B test different orchestration approaches
Migration: Gradually move from LLM to deterministic workflows
Learning: Compare results between approaches

Technology Stack¶

Eino: CloudWeGo's LLM application framework
Graph Orchestration: Directed graph with typed nodes
A2A Protocol: trpc-a2a-go for agent communication
Type Safety: Compile-time validation

Logging¶

The Eino orchestrator provides detailed logging with [Eino] prefix:

[Eino] Validating input for topic: climate change
[Eino] Executing research for topic: climate change
[Eino] Verifying 15 candidates
[Eino] Quality check: 12 verified (target: 10)
[Eino] Quality target met
[Eino] Formatting response with 12 verified statistics

Next Steps¶

Install Eino:
```
go get github.com/cloudwego/eino
```
Build:
```
make build
```
Run with Eino:
```
make run-all-eino
```

Test:

curl -X POST http://localhost:8003/orchestrate -H "Content-Type: application/json" -d '{"topic": "AI statistics", "min_verified_stats": 5}'

Contributing¶

Contributions to improve the Eino orchestration workflow are welcome!