Agent Architecture

Beever Atlas uses Google ADK (Agent Development Kit) to orchestrate complex multi-stage processes. Each major function — ingestion, querying, wiki generation — is implemented as a hierarchy of specialized agents that collaborate to produce results.

Why Agent-Based Architecture?

Traditional monolithic systems are brittle: one component failure can break the entire pipeline. Agent-based architecture provides:

Isolation: Each agent is independently deployable and fault-tolerant

Parallelism: Agents can execute simultaneously where possible

Flexibility: Agents can be swapped or upgraded independently

Observability: Each agent logs its inputs, outputs, and reasoning

Graceful degradation: If one agent fails, others can continue with reduced functionality

Agent Hierarchy Overview

Ingestion Pipeline Agents

Query Pipeline Agents

Wiki Service Agents

Agent Communication

Agent Types

LlmAgent: Uses LLM for reasoning (Fact Extractor, Query Router)

• Has system prompt
• Streaming responses
• Tool calling

SequentialAgent: Chains agents in sequence (Ingestion Pipeline)

• Output of one agent → Input of next
• Error handling and rollback

ParallelAgent: Runs agents simultaneously (Fact + Entity extraction)

• Independent execution
• Merged results

LoopAgent: Repeats until condition (Consolidation)

• Iterative processing
• Convergence detection

Tool Calling

Agents expose tools for other agents to call:

Semantic Agent Tools:

• search_weaviate_hybrid(query, channel_id, alpha)
• get_tier0_summary(channel_id)
• get_tier1_clusters(channel_id, topic)

Graph Agent Tools:

• traverse_neo4j(entities, channel_id, max_hops)
• temporal_chain(entity_name, channel_id)
• fuzzy_match_entities(query, channel_id)

Wiki Agent Tools:

• assign_to_clusters(channel_id, facts)
• build_wiki(channel_id)

Fallback Hierarchy

Each agent has a fallback chain:

Fallback trigger: 3 consecutive failures or 30s timeout

Recovery: Circuit breaker HALF_OPEN after 30s, one probe request

Error Handling

Agent-Level

Retry: Each agent retries failed operations 3 times with exponential backoff

Timeout: Each agent has 30s timeout per operation

Fallback: Cascade to fallback model if primary unavailable

Logging: All inputs, outputs, and errors logged for debugging

Pipeline-Level

Skip non-critical stages: If entity extraction fails, continue with facts only

Queue for backfill: Failed operations queued for retry when dependencies recover

Circuit breakers: Open circuit after 3 consecutive failures, auto-recover after 30s

Partial results: Return best available results rather than failing completely

Observability

Agent Logging

Each agent logs:

• Input parameters (sanitized)
• Output results
• LLM prompts and responses (redacted)
• Tool calls and results
• Errors and retries
• Performance metrics (latency, cost)

Tracing

Distributed tracing across agent calls:

• Trace ID propagated through all agents
• Spans for each agent execution
• Parent-child relationships for sub-agents
• Timeline view of pipeline execution

Metrics

Per-agent metrics:

• Invocation count
• Success/failure rate
• Average latency
• Cost per operation
• Fallback rate

Next Steps

• See Ingestion Pipeline for agent orchestration details
• Learn about Query Router agent decision-making
• Understand Resilience features for fault tolerance