tbd-agents

                 ████████╗██████╗ ██████╗      █████╗  ██████╗ ███████╗███╗   ██╗████████╗
                 ╚══██╔══╝██╔══██╗██╔══██╗    ██╔══██╗██╔════╝ ██╔════╝████╗  ██║╚══██╔══╝
                    ██║   ██████╔╝██║  ██║    ███████║██║  ███╗█████╗  ██╔██╗ ██║   ██║
                    ██║   ██╔══██╗██║  ██║    ██╔══██║██║   ██║██╔══╝  ██║╚██╗██║   ██║
                    ██║   ██████╔╝██████╔╝    ██║  ██║╚██████╔╝███████╗██║ ╚████║   ██║
                    ╚═╝   ╚═════╝ ╚═════╝     ╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═══╝   ╚═╝
                 

Your agents. Your rules. Your infrastructure.

⚡ Built by NAAICO ⚡

🎮 TBD — To Be Decided by you: what your agents do, which tools they use, and how far they go.

Build, control, and trigger custom AI agents over the web — no black boxes, no vendor lock-in. A clean REST API backed by the GitHub Copilot SDK that runs entirely on your infrastructure.

_{↑ Record a demo and drop the GIF at docs/demo.gif to show it here}

★ Highlights

🚀 Quick Start

Option A — Pull pre-built image (recommended for production)

# Pull the latest release
docker pull ghcr.io/naaico-tech/tbd-agents:latest

# Or pin to a specific version
docker pull ghcr.io/naaico-tech/tbd-agents:v0.1.0

# Start all services using the pre-built image
cp .env.example .env   # fill in GITHUB_TOKEN etc.
docker compose up

Option B — Build from source (for development)

git clone https://github.com/naaico-tech/tbd-agents.git
cd tbd-agents
cp .env.example .env
docker compose up --build

Your GitHub PAT needs the copilot scope — create one here.

See docs/getting-started/local-setup.md for detailed local development instructions.

Choosing a Vector Store

TBD Agents supports two vector store backends. Select one by setting
COMPOSE_PROFILES in your .env:

# .env
COMPOSE_PROFILES=qdrant    # or: pgvector
VECTOR_STORE_BACKEND=qdrant  # must match the profile above

See the pgvector guide for full setup instructions.

Choosing a Database Backend

The deployment profile controls both the vector store and the document/data store:

Use the pgvector profile to run a fully-PostgreSQL stack — one database for everything,
backed up with a single pg_dump.

# .env — all-PostgreSQL stack
COMPOSE_PROFILES=pgvector
VECTOR_STORE_BACKEND=pgvector
DB_BACKEND=postgres

See the PostgreSQL Backend Guide for full details,
including schema design, Alembic migrations, MongoDB→PostgreSQL data migration, and
observability queries.

📖 Documentation

🏗️ Architecture

graph TB
    subgraph Clients
        Dashboard([Dashboard])
        CLI([curl / CLI])
        Apps([Applications])
    end

    subgraph API["API Layer (FastAPI :8000)"]
        FastAPI[FastAPI + Uvicorn]
    end

    subgraph Broker["Message Broker"]
        Redis[(Redis\nBroker + Pub/Sub)]
    end

    subgraph Workers["Worker Pool (Celery)"]
        W1[Worker 1]
        W2[Worker 2]
        WN[Worker N]
    end

    subgraph External["External Services"]
        SDK[Copilot SDK\nJSON-RPC]
        Models[Copilot Models API]
        MCP1[MCP: Jira]
        MCP2[MCP: Datadog]
        MCPN[MCP: ...]
    end

    subgraph Storage
        Mongo[(MongoDB)]
        Qdrant[(Qdrant\nvector DB)]
    end

    Dashboard & CLI & Apps -->|HTTP + Auth| FastAPI
    FastAPI -->|Enqueue tasks| Redis
    FastAPI -->|Subscribe events| Redis
    FastAPI -->|SSE stream| Dashboard & CLI & Apps
    FastAPI -->|Read / Write| Mongo

    Redis -->|Deliver tasks| W1 & W2 & WN
    W1 & W2 & WN -->|Publish events| Redis
    W1 & W2 & WN -->|Persist state| Mongo
    W1 & W2 & WN -->|SDK session| SDK

    SDK --> Models
    SDK --> MCP1 & MCP2 & MCPN

    FastAPI -.->|Optional| Qdrant

🔌 API Reference

All endpoints (except /health) require Authorization: Bearer <GITHUB_TOKEN> header.

♥ Health

GET /health

🤖 Agents

POST   /api/agents              ← Create agent
GET    /api/agents              ← List agents
GET    /api/agents/{id}         ← Get agent
PUT    /api/agents/{id}         ← Update agent
DELETE /api/agents/{id}         ← Delete agent

🧩 Skills

POST   /api/skills              ← Create skill
GET    /api/skills              ← List skills
GET    /api/skills/{id}         ← Get skill
PUT    /api/skills/{id}         ← Update skill
DELETE /api/skills/{id}         ← Delete skill

🔧 MCP Servers

POST   /api/mcps                ← Register MCP server
GET    /api/mcps                ← List MCP servers
GET    /api/mcps/{id}           ← Get MCP server
POST   /api/mcps/{id}/test      ← Test MCP connection
GET    /api/mcps/{id}/tools     ← List tools from MCP server
DELETE /api/mcps/{id}           ← Remove MCP server

📚 Knowledge Sources

POST   /api/knowledge-sources              ← Register knowledge source (vector_db or mongo_db)
GET    /api/knowledge-sources              ← List sources (optional ?tags= filter)
GET    /api/knowledge-sources/{id}         ← Get source
PUT    /api/knowledge-sources/{id}         ← Update source
DELETE /api/knowledge-sources/{id}         ← Delete source (cascade-deletes items)
POST   /api/knowledge-sources/{id}/test    ← Test connection

📄 Knowledge Items

POST   /api/knowledge-items                ← Create text knowledge item
POST   /api/knowledge-items/upload         ← Upload file/image (multipart)
GET    /api/knowledge-items                ← List items (?source_id=, ?tags=, ?content_type=)
GET    /api/knowledge-items/{id}           ← Get item metadata
GET    /api/knowledge-items/{id}/content   ← Download file content
PUT    /api/knowledge-items/{id}           ← Update item tags/metadata
DELETE /api/knowledge-items/{id}           ← Delete item
POST   /api/knowledge-items/query          ← Query items by tags

⚙️ Workflows

POST   /api/workflows                        ← Create workflow
POST   /api/workflows/{id}/prompt            ← Send prompt (returns 201, runs via worker)
GET    /api/workflows/{id}                   ← Get workflow state + logs + messages
GET    /api/workflows/{id}/stream            ← SSE stream of real-time events
GET    /api/workflows                        ← List your workflows
POST   /api/workflows/{id}/skills/{skill_id} ← Install skill into workflow
DELETE /api/workflows/{id}/skills/{skill_id} ← Remove skill from workflow

🕹️ Usage Examples

Stage 1 — Create an Agent

curl -X POST http://localhost:8000/api/agents \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "code-reviewer",
    "system_prompt": "You are an expert code reviewer. Analyze code for bugs, security issues, and improvements.",
    "model": "gpt-4.1"
  }'

Stage 2 — Register an MCP Server

curl -X POST http://localhost:8000/api/mcps \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "datadog",
    "transport_type": "stdio",
    "connection_config": {
      "command": "npx",
      "args": ["-y", "@datadog/mcp-server-datadog"],
      "env": {"DD_API_KEY": "...", "DD_APP_KEY": "...", "DD_SITE": "datadoghq.com"}
    }
  }'

Stage 3 — Create a Workflow and Send a Prompt

# Create workflow with Notion output + infinite session
WORKFLOW=$(curl -s -X POST http://localhost:8000/api/workflows \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "<AGENT_ID>",
    "max_turns": 10,
    "output_format": "markdown",
    "infinite_session": true,
    "caveman": true,
    "output_destination": {
      "notion_base_page_id": "abc123..."
    }
  }')

WORKFLOW_ID=$(echo "$WORKFLOW" | python3 -c "import sys, json; print(json.load(sys.stdin)['id'])")

# Send prompt — dispatched to a Celery worker
curl -X POST "http://localhost:8000/api/workflows/$WORKFLOW_ID/prompt" \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Investigate the spike in p99 latency on the payments service over the last 24 hours."}'

Stage 4 — Stream Results in Real-Time

curl -N "http://localhost:8000/api/workflows/$WORKFLOW_ID/stream"

Stage 5 — Add a Knowledge Base

# Register a local MongoDB-backed knowledge source
curl -X POST http://localhost:8000/api/knowledge-sources \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "product-docs",
    "source_type": "mongo_db",
    "tags": ["docs", "product"]
  }'

# Upload a text knowledge item tagged for retrieval
curl -X POST http://localhost:8000/api/knowledge-items \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source_id": "<SOURCE_ID>",
    "name": "API rate limits",
    "content_type": "text",
    "text_content": "Rate limit is 1000 req/min per API key. Burst limit is 50 req/s.",
    "tags": ["docs", "api"]
  }'

# Upload a file via multipart form
curl -X POST http://localhost:8000/api/knowledge-items/upload \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -F "[email protected]" \
  -F "source_id=<SOURCE_ID>" \
  -F 'tags=["docs", "architecture"]'

# Attach knowledge to an agent by tags
curl -X PUT http://localhost:8000/api/agents/<AGENT_ID> \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"knowledge_tags": ["docs"]}'

Stage 6 — Connect a Qdrant Vector Database

To use an external Qdrant instance as a knowledge source:

# 1. Store the Qdrant API key in the encrypted token store
curl -X POST http://localhost:8000/api/tokens \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "qdrant-api-key",
    "value": "your-qdrant-api-key-here",
    "description": "Qdrant Cloud API key"
  }'

# 2. Register the Qdrant source
curl -X POST http://localhost:8000/api/knowledge-sources \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "qdrant-docs",
    "source_type": "vector_db",
    "connection_config": {
      "url": "https://your-cluster.qdrant.io:6333",
      "collection": "documents",
      "api_key_token_name": "qdrant-api-key"
    },
    "tags": ["vector", "docs"]
  }'

# 3. Test the connection
curl -X POST http://localhost:8000/api/knowledge-sources/<SOURCE_ID>/test \
  -H "Authorization: Bearer $GITHUB_TOKEN"

# 4. Attach to an agent by ID or tags
curl -X PUT http://localhost:8000/api/agents/<AGENT_ID> \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"knowledge_source_ids": ["<SOURCE_ID>"]}'

For local development, set COMPOSE_PROFILES=qdrant in your .env, run docker compose up, and use http://qdrant:6333 as the URL.

🧠 Supported Models

Any model available through GitHub Copilot is supported. Currently includes:

🏗️ Tech Stack

Component	Technology
API	FastAPI + Uvicorn
Agent engine	GitHub Copilot SDK (JSON-RPC)
Task queue	Celery + Redis
Event bus	Redis Pub/Sub
Database	MongoDB + Beanie ODM
Vector DB	Qdrant (optional, for knowledge)
Frontend	Flutter web + legacy HTML dashboard
Containers	Docker Compose · Pre-built images on GHCR

📦 Releases

TBD Agents uses Semantic Versioning. Pre-built Docker images are published to GitHub Container Registry on every release.

docker pull ghcr.io/naaico-tech/tbd-agents:latest

See CHANGELOG.md for the full release history and GitHub Releases for release notes.

📜 License

Apache 2.0 — © NAAICO