How heddles/agent-orca works
Agent ORCAstrator is a Kubernetes-native platform for defining, deploying, and running AI agents. Its principal workflow begins with an operator or integrator submitting an AgentRun or deploying an AgentDeployment; controllers assemble execution configuration and agent pods, while the model router handles inference and tool dispatch. Results and run state feed APIs and the UI for live execution, history, cost, and system views. The README documents additional workflow DAGs, RAG/KnowledgeBases, MCP, guardrails, and egress sinks. Edges reflect shown source references or README statements; unsampled internals are represented conservatively.
Main entry points: agentrun_controller.go Run reconciler · router.go Model router · agent_types.go Agent resource types · agentdeployment_controller.go Deployment reconciler
Components 28
Kubernetes control plane
- Agent resource types
api/v1alpha1/agent_types.go - Agent controller
internal/controller/agent_controller.go - Deployment reconciler
internal/controller/agentdeployment_controller.go - Run reconciler
internal/controller/agentrun_controller.go - Workflow reconciler
internal/controller/agentworkflow_controller.go - Run validation
internal/webhook/agentrun_webhook.go
Agent execution
- Agent pod builder
internal/podbuilder/builder.go - Model router
internal/router/router.go - Tool executor
internal/executor/executor.go - Model router service
cmd/model-router/main.go
Knowledge and integrations
- Knowledge controller
internal/controller/knowledgebase_controller.go - RAG pipeline
internal/rag/pipeline.go - Vector store
internal/rag/qdrant.go - MCP client
internal/mcp/client.go - MCP ingester
cmd/mcp-ingester/main.go
APIs and interfaces
- Operator APIs
internal/apiserver/apiserver.go - UI proxy
cmd/ui-proxy/main.go - Operations UI
ui/src/main.tsx - API and streams
ui/src/api/sse.ts - aoctl CLI
cmd/aoctl/main.go
State and results
- Run checkpoints
internal/checkpoint/store.go - Conversation state
internal/state/store.go - Run archive
internal/postgresql/store.go - Result delivery
internal/egress/egress.go
Other components
- Operator
- API integrator
- LLM provider
- Configured sink
Connections 34
- Operator → Agent resource types: defines resources
README.md - Agent resource types → Deployment reconciler: configures
- Agent resource types → Run reconciler: configures
- Agent resource types → Workflow reconciler: configures
- Agent resource types → Knowledge controller: configures
- Run reconciler → Agent pod builder: builds pod
internal/controller/agentrun_controller.go - Deployment reconciler → Agent pod builder: builds deployment
internal/controller/agentdeployment_controller.go - Run reconciler → Model router: configures routing
internal/controller/agentrun_controller.go - Deployment reconciler → Model router: configures routing
internal/controller/agentdeployment_controller.go - Run reconciler → Conversation state: configures state
internal/controller/agentrun_controller.go - Run reconciler → Run archive: archives runs
internal/controller/agentrun_controller.go - Run reconciler → Result delivery: publishes results
internal/controller/agentrun_controller.go - Run reconciler → MCP client: resolves tools
internal/controller/agentrun_controller.go - Deployment reconciler → MCP client: resolves tools
internal/controller/agentdeployment_controller.go - Model router service → Model router: starts router
cmd/model-router/main.go - Model router service → Conversation state: creates store
cmd/model-router/main.go - Model router service → Tool executor: binds executor
cmd/model-router/main.go - Model router → Tool executor: dispatches tools
internal/router/router.go - Model router → Conversation state: uses state
internal/router/router.go - Model router → MCP client: calls MCP tools
internal/router/router.go - Model router → LLM provider: requests inference
- Knowledge controller → RAG pipeline: uses RAG
internal/controller/knowledgebase_controller.go - MCP ingester → MCP client: discovers documents
cmd/mcp-ingester/main.go - MCP ingester → RAG pipeline: chunks and embeds
cmd/mcp-ingester/main.go - RAG pipeline → Vector store: stores vectors
- Operator → Operations UI: views operations
README.md - Operations UI → UI proxy: requests UI APIs
README.md - Operations UI → API and streams: renders live views
ui/src/main.tsx - API and streams → Operator APIs: fetches and streams
- API integrator → aoctl CLI: submits tasks
README.md - aoctl CLI → Operator APIs: calls task APIs
- API integrator → Operator APIs: submits tasks
README.md - Result delivery → Configured sink: delivers results
- Run reconciler → Run checkpoints: supports checkpoints