heddles / agent-orca

# Agent ORCAstrator
Agent orcastrator is a Kubernetes-native platform for deploying, managing, and running AI agents at scale. It lets you declaratively define agents, route them to the correct LLM, equip them with tools, and execute them as one-off jobs or long-running services with checkpoints, cost tracking, guardrails, and RAG built in.
> **Open source, Apache 2.0.** See CONTRIBUTING.md to get started,
> CODE_OF_CONDUCT.md for the community standard, and
> SECURITY.md for how to report vulnerabilities.
---
## Quick Start
**Quick-start prerequisites:**
>__NOTE__: You need to activate mise in your shell for this to work. Here is an zsh example: `echo 'eval "$(mise activate zsh)"' >> ~/.zshrc`
1. Install `mise` via Homebrew: `brew install mise`
1. Bootstrap the environment: `sudo mise install --system`
1. Ensure Docker is running.
1. Have an API key for at least one model provider (OpenAI, Anthropic, Google, or **Poolside**; providers are LiteLLM-compatible).
From zero to a chatting agent on your laptop in ~3 commands:
>__NOTE__: You may need to run `skaffold dev -p dev` multiple times if this is a brand new local cluster stand up. Typically 3 runs of the command will work for initial cluster standup.
 [code] 
Now go to `http://localhost:8080` to chat with your agent. We recommend asking:
`What will happen to the economy in 5 years if there is a shortage of wheat for one
year?` (this is the demo-financial-analysis prompt) or any question to the quickstart
agent. The output should be an interactive user interface.
**What the `dev` profile deploys:**
| Component | Chart / Manifest | Namespace | Notes |
|---|---|---|---|
| CloudNativePG operator + Postgres | `charts/cloudnative-pg` + `charts/cluster` | `agent-orca-system` | Operator + single-instance Postgres for run archival |
| agent-orca operator | `charts/agent-orca` | `agent-orca-system` | CRDs, controllers, webhooks (Ignore mode), APIs |
| agent-orca-resources | `charts/agent-orca-resources` | `agent-orca-system` | Base resource templates |
| Bundled Redis | (subchart) | `agent-orca-system` | State store for checkpoints, spend, token streams |
| Model + credential CRs | `charts/model-providers` | `agent-orca-system` | OpenAI, Anthropic, Google, Poolside, Ollama-embed |
| In-cluster Ollama (embeddings) | `config/samples/ollama-embedding-cluster.yaml` | `agent-orca-system` | `nomic-embed-text` for RAG; pulled at deploy time |
**Local ports forwarded by the `dev` Skaffold profile:**
| Port | Surface | Purpose |
|------|---------|---------|
| `8080` | UI (via UIProxy BFF) | React SPA + `/api/deployments/...` chat endpoints |
| `8000` | ACP API | Agent discovery, manifest introspection, self-service run execution |
| `8084` | External Task API | Programmatic task submit/poll/stream/cancel (OAuth2 / federated OIDC / K8s SA) |
| `8083` | UI API (cluster-internal) | Operator's own UI API; reachable in dev for testing OIDC callbacks |
| `8080` | Operator metrics | controller-runtime metrics (`agent-or