Files

T

alex cf47476f1c Update agent_hub_spec.md

2026-05-29 16:04:19 +02:00

56 KiB

Raw Blame History

AgentHub Specification v0.3

Status: Accepted baseline for initial development License direction: Apache-2.0 Primary target users: Small engineering teams Primary reference workflow: Gitea issue to spec to pull request Secondary reference workflow: Generic webhook summarizer First vertical slice: Manual workflow → Kimi prompt stage → artifact → approval gate

1. Product Summary

AgentHub is a self-hosted, general-purpose agent workflow and orchestration platform for small engineering teams.

It provides a control plane for defining, managing, running, observing, and governing AI agents across external systems and workflows.

AgentHub is not a single coding agent, Git bot, CrewAI wrapper, or model frontend. It is a platform layer that coordinates:

connectors
triggers
monitors
workflows
workflow runs
agent definitions
agent teams
model routing
runtime adapters
tool grants
sandboxing
policies
approvals
artifacts
memory
observability
audit logs

The first complete reference workflow is a self-hosted Git workflow:

Gitea issue
  ↓
label or comment trigger
  ↓
workflow starts
  ↓
spec generation
  ↓
human spec approval
  ↓
implementation agent
  ↓
branch pushed
  ↓
draft pull request opened
  ↓
CI monitored
  ↓
review/revision loop
  ↓
human-approved merge or merge-ready state

AgentHub must remain general enough to support non-Git workflows, such as webhook processing, scheduled monitoring, document generation, support triage, release automation, infrastructure checks, and internal business workflows.

2. Product Identity

AgentHub is a:

general-purpose self-hosted agent workflow platform

Its first strong use case is developer automation, but the core architecture must not be Git-specific.

2.1 First Target Users

The first target users are:

small engineering teams

This means the product should prioritize:

Docker Compose deployment
multi-user support
team and project support
practical approvals
visible run history
simple configuration
useful defaults
explicit security boundaries
self-hosted operation
extensibility without enterprise complexity

3. Product Principles

3.1 Platform Orchestration vs Agent Orchestration

AgentHub owns deterministic platform orchestration.

Agent runtimes own task execution.

AgentHub owns

workflow state
stage transitions
approval gates
policy checks
trigger matching
monitor execution
runtime selection
model routing
artifact handling
event logs
audit logs
secret scoping
sandbox allocation
human interaction

Agent runtimes own

reasoning loops
tool use within granted permissions
multi-agent collaboration
code editing
reviewing
summarizing
planning
runtime-specific execution

3.2 Runtime-Agnostic Architecture

AgentHub must support multiple runtime adapters.

MVP runtime adapters:

llm_prompt
script
mini_swe_agent
crewai

Future runtime adapters:

openhands
langgraph
pr_agent
custom_docker_agent
http_agent
local_model_worker

CrewAI is useful for hierarchical teams, planning, spec generation, and review boards. It is not the platform core.

mini-SWE-agent is useful for implementation tasks, especially issue-to-code and bug-fix workflows. It is not the platform core.

3.3 Human Control

Agents may propose, prepare, summarize, implement, review, and recommend.

Humans approve sensitive actions.

AgentHub policy gates own sensitive side effects such as:

posting external comments
accessing secrets
indexing memory
pushing branches
opening pull requests
merging pull requests
running network-enabled sandboxes
using expensive models

3.4 Explicit Context and Memory

AgentHub should not silently remember or index everything.

Memory exists from day one, but indexing is explicit, scoped, inspectable, and permission-controlled.

4. Goals

4.1 Product Goals

AgentHub should allow users to:

Create workspaces.
Create teams.
Create projects.
Connect external systems.
Define event-based triggers.
Define polling or condition-based monitors.
Define YAML-first workflows.
Run workflows manually or from external events.
Configure agents and agent teams.
Configure hierarchical agent teams.
Route different agents to different models.
Route different workflow stages to different runtimes.
Enforce explicit tool grants.
Run agents in Docker sandboxes.
Disable network access by default.
Use vector memory with explicit scoped indexing.
Store artifacts in MinIO.
Require human approvals for sensitive stages.
Allow controlled merge after approval and successful CI when configured.
Record all major events and audit-relevant actions.
Inspect workflow timelines, logs, artifacts, approvals, memory use, and policy decisions.
Support Gitea first, while keeping GitLab, GitHub, and Forgejo support open.

4.2 Engineering Goals

AgentHub should be:

self-hosted
Docker Compose first
Kubernetes-compatible later
model-provider agnostic
runtime-adapter agnostic
connector-adapter agnostic
workflow-engine swappable later
secure by default
observable by default
auditable by default
permissively open-source

5. Non-Goals for MVP

The MVP should not attempt to:

Build a hosted SaaS platform.
Build a visual drag-and-drop workflow editor.
Replace CI systems.
Replace Git provider review workflows.
Automatically merge changes by default.
Support every Git provider completely.
Implement full event sourcing.
Implement Kubernetes runners.
Implement Firecracker or gVisor sandboxes.
Implement full GitOps configuration.
Implement custom RBAC DSLs.
Let agents freely spawn sub-workflows.
Let agents access all tools by default.
Store hidden model reasoning.
Silently index all data into memory.
Build a custom LLM framework from scratch.

6. Implementation Stack

6.1 Final Implementation Decisions

Monorepo: Turbo + pnpm
Frontend: Next.js + TypeScript
Backend: FastAPI
ORM: SQLAlchemy
Migrations: Alembic
Worker: Celery
Queue broker: Redis
Database: PostgreSQL
Vector database: pgvector
Artifact storage: MinIO
Sandbox: Docker per run
Authentication: Authentik OIDC first
First model provider: Kimi
Second model provider: OpenAI
License: Apache-2.0

6.2 Recommended App Structure

agenthub/
  apps/
    web/
    api/
    worker/

  packages/
    shared/
    workflow-schema/
    ui/
    client-sdk/

  python/
    agenthub_core/
      workflow/
      policy/
      connectors/
      runtimes/
      models/
      artifacts/
      memory/
      sandbox/
      events/
      auth/

  connectors/
    gitea/
    generic_webhook/
    http/
    future_gitlab/
    future_github/

  runtimes/
    llm_prompt/
    script/
    mini_swe_agent/
    crewai/

  workflows/
    examples/
      manual-prompt-artifact-approval.yaml
      generic-webhook-summarizer.yaml
      gitea-issue-to-pr.yaml

  agents/
    examples/
      summarizer-agent.yaml
      gitea-triage-agent.yaml
      gitea-spec-team.yaml
      mini-swe-implementation-agent.yaml
      pr-review-team.yaml

  policies/
    examples/
      default-secure-policy.yaml
      gitea-merge-policy.yaml

  infra/
    docker-compose.yml
    docker/
    k8s/

  docs/
    architecture.md
    development.md
    security.md
    workflow-format.md
    connector-sdk.md
    runtime-sdk.md
    model-gateway.md
    gitea-reference-workflow.md

7. Deployment Model

7.1 MVP Docker Compose Deployment

AgentHub must run locally and on a small server with Docker Compose.

Required services:

agenthub-web
agenthub-api
agenthub-worker
postgres
redis
minio

Recommended optional local services:

authentik
ollama
gitea
local OpenAI-compatible model endpoint

7.2 Future Deployment

Future deployment should support Kubernetes.

The architecture should avoid assumptions that prevent later migration to:

Kubernetes jobs
Temporal
Hatchet
Windmill
external secret managers
external object storage
external vector databases
external model gateways

8. Authentication and Authorization

8.1 Authentication

MVP authentication uses:

Authentik OIDC

Local password login is not required for MVP unless needed as an emergency development fallback.

8.2 Workspace Model

AgentHub supports multi-user operation with teams and projects from the start.

A workspace is the top-level collaboration boundary.

workspace
  ├─ users
  ├─ teams
  ├─ projects
  ├─ connectors
  ├─ workflows
  ├─ agents
  ├─ models
  ├─ policies
  └─ secrets

8.3 Projects

Projects group workflows, connectors, agents, artifacts, and memory around a domain.

Examples:

Platform Engineering
Backend Services
Internal Tools
Customer Support Automation
Release Automation

A project can be owned by one user or one or more teams.

8.4 MVP Roles

admin
operator
maintainer
developer
viewer

admin

Can manage the instance, workspaces, users, teams, secrets, models, and global policies.

operator

Can manage workflows, agents, connectors, monitors, and runs.

maintainer

Can approve high-risk workflow stages, Git specs, PR readiness, and merge actions where configured.

developer

Can trigger allowed workflows, inspect runs, comment, and provide input.

viewer

Can view allowed projects, runs, artifacts, and logs.

9. Architecture Overview

Web UI
  ↓
Backend API
  ↓
Workflow Engine
  ↓
Postgres-backed durable state machine
  ↓
Redis / Celery queue
  ↓
Worker pool
  ↓
Runtime adapters
    ├─ LLM prompt adapter
    ├─ script adapter
    ├─ mini-SWE-agent adapter
    └─ CrewAI adapter

Platform services
  ├─ connector registry
  ├─ trigger engine
  ├─ monitor engine
  ├─ model gateway
  ├─ policy engine
  ├─ tool registry
  ├─ sandbox manager
  ├─ secret store
  ├─ vector memory
  ├─ artifact store
  ├─ event log
  └─ audit log

10. Persistence and Event Model

AgentHub uses a pragmatic hybrid model:

Postgres is the source of truth.
Redis is only a queue.
Workflow, stage, and agent run rows store current state.
Every meaningful transition appends an event.
Audit-relevant actions also append audit log entries.

This is not full event sourcing in the MVP, but it keeps a future path open.

10.1 Required Tables for Current State

workspaces
projects
teams
users
memberships
connectors
triggers
monitors
workflows
workflow_versions
workflow_runs
stage_runs
agents
agent_teams
agent_runs
models
tools
policies
approvals
artifacts
secrets
memory_collections
memory_items
events
audit_logs

10.2 Required Event Discipline

Every transition should follow this pattern:

validate input
  ↓
evaluate policy
  ↓
append event
  ↓
update current-state row
  ↓
enqueue next job if needed
  ↓
append audit log if security-relevant

Examples of internal events:

workflow_run.created
workflow_run.started
stage_run.queued
stage_run.started
agent_run.started
artifact.created
approval.requested
approval.approved
connector_action.executed
stage_run.completed
workflow_run.completed
policy.denied

11. Workflow System

11.1 Workflow Engine

The MVP uses a custom lightweight workflow engine.

It must be designed so it can later be replaced by or integrated with:

Temporal
Hatchet
Windmill
LangGraph
custom durable workflow engine

The AgentHub workflow definition format must remain independent from the execution backend.

11.2 Workflow Authoring

Workflows are YAML-first.

The MVP UI must provide:

YAML editor
schema validation
validation error display
read-only graph preview
run history
stage timeline

A visual builder is not required for MVP.

11.3 Workflow Storage

Workflows are stored in PostgreSQL first.

YAML import/export must be supported early.

GitOps workflow storage is a future feature.

11.4 Workflow Versioning

Every workflow edit creates a new workflow version.

Every workflow run stores an immutable snapshot of:

workflow definition
agent definitions
agent team definitions
model routing decisions
policy versions
prompt template versions
runtime adapter versions where practical

Active runs are not affected by later workflow edits.

11.5 Supported MVP Stage Types

agent
agent_team
script
connector_action
approval
condition
wait_for_condition
notification
terminal

Future stage types:

parallel
subworkflow
human_input
wait_for_event
manual_task
deployment

11.6 Agents Starting Sub-Workflows

In the MVP, agents cannot directly start sub-workflows.

Agents may recommend a workflow action:

recommended_actions:
  - type: start_workflow
    workflow: security-review
    reason: "Authentication code changed."

The platform or a human decides whether to start it.

Future versions may allow policy-approved sub-workflows.

12. First Vertical Slice Workflow

The first vertical slice validates the core platform before connector complexity.

12.1 Goal

A user can manually run a workflow that:

manual trigger
  ↓
Kimi LLM prompt stage
  ↓
markdown artifact created in MinIO
  ↓
approval requested
  ↓
human approves or rejects
  ↓
workflow completes

12.2 Acceptance Criteria

The first vertical slice is complete when:

Authentik OIDC login works.
A workspace exists.
A project exists.
A workflow can be authored in YAML.
The workflow can be manually triggered.
A workflow run snapshot is stored.
Celery executes the stage.
The model gateway calls Kimi.
The LLM prompt runtime returns structured output.
A markdown artifact is stored in MinIO.
An approval gate is created.
A user can approve or reject the gate.
The workflow continues or terminates accordingly.
The UI shows the run timeline.
The UI shows logs, events, and artifacts.

12.3 Example Workflow

id: manual-prompt-artifact-approval
name: Manual Prompt Artifact Approval
version: 1
enabled: true

triggers:
  - id: manual
    type: manual

stages:
  - id: draft_summary
    type: agent
    agent: simple-summary-agent
    input:
      prompt: "{{ input.prompt }}"
    outputs:
      summary: result

  - id: create_artifact
    type: connector_action
    connector: artifact-store
    action: artifact.create_markdown
    input:
      name: summary.md
      content: "{{ summary.outputs.markdown }}"
    outputs:
      artifact: result

  - id: approve
    type: approval
    title: "Approve generated artifact"
    required_roles:
      - maintainer
    input:
      artifact: "{{ artifact }}"

  - id: complete
    type: terminal
    status: success

13. Trigger System

Triggers start workflows from events.

Supported MVP triggers:

manual trigger
generic webhook trigger
Gitea issue label trigger
Gitea comment mention trigger
scheduled trigger

Future triggers:

GitLab events
GitHub events
Slack/Matrix commands
email events
RSS events
database events
workflow events

13.1 Trigger Deduplication

All external events must be deduplicated.

Deduplication examples:

connector_id + external_event_id
repository + issue_number + label + workflow_id
webhook_delivery_id

13.2 Trigger Authorization

Before starting a workflow:

connector is enabled
workflow is enabled
actor is authorized if applicable
trigger filter matches
policy permits run creation
duplicate active run is not already present

14. Monitor System

Monitors watch external conditions and emit internal events.

Supported MVP monitor:

basic polling monitor

For the Git workflow, monitors are used to watch:

pull request CI/check status
unresolved review comments
stale agent PRs

Future monitors:

RSS/security advisory monitor
HTTP health monitor
queue backlog monitor
scheduled stale issue monitor
email inbox monitor
deployment status monitor

15. Connector System

15.1 Connector Strategy

The first complete Git connector is:

Gitea

The connector abstraction must remain open for:

GitLab
GitHub
Forgejo
generic Git
generic HTTP
generic webhook

Gitea is required because self-hosting is core to the product.

GitLab support is highly desirable after Gitea.

GitHub support should be straightforward if the provider abstraction is clean.

15.2 MVP Connectors

Gitea connector
generic webhook connector
HTTP connector
artifact-store connector

15.3 Future Connectors

GitLab
GitHub
Forgejo
Slack
Matrix
Jira
Linear
email
RSS
Kubernetes
database
S3-compatible storage

15.4 Git Provider Abstraction

Git providers must expose common operations:

read repository
read issue
list issue comments
post issue comment
add/remove label
create branch
push commits
open pull request
update pull request
read pull request
list PR comments
read CI/check status
merge pull request if configured and allowed

15.5 Git Auth Strategy

MVP uses a hybrid strategy:

API access: provider token
Git clone/push: HTTPS token or SSH key

Future production strategies:

GitHub App
GitLab OAuth/application integration
Gitea OAuth/application tokens where available
short-lived credentials
provider-specific app models

16. Secondary Reference Workflow: Generic Webhook Summarizer

This workflow proves AgentHub is not only a Git bot.

16.1 Workflow

external webhook received
  ↓
summarization agent runs
  ↓
approval gate
  ↓
HTTP callback posts result
  ↓
artifact and audit log recorded

16.2 Example Workflow

id: generic-webhook-summarizer
name: Generic Webhook Summarizer
version: 1
enabled: true

triggers:
  - id: incoming-webhook
    type: webhook_event
    connector: generic-webhook
    path: /incoming/summarize

stages:
  - id: summarize
    type: agent
    agent: summarizer-agent
    input:
      payload: "{{ event.payload }}"
    outputs:
      summary: result

  - id: approve
    type: approval
    title: "Approve summary before callback"
    required_roles:
      - maintainer
    input:
      summary: "{{ summary }}"

  - id: post_result
    type: connector_action
    connector: http
    action: http.post
    input:
      url: "{{ event.payload.callback_url }}"
      body:
        summary: "{{ summary.outputs.text }}"

  - id: complete
    type: terminal
    status: success

17. Gitea Issue-to-PR Reference Workflow

17.1 Provider Priority

The first complete Git provider is:

Gitea

The provider abstraction must keep room for:

GitLab
GitHub
Forgejo

17.2 Default Workflow

issue labeled "agent-ready"
  ↓
load issue context
  ↓
triage
  ↓
generate spec
  ↓
human spec approval
  ↓
run mini-SWE-agent implementation
  ↓
collect diff
  ↓
run tests
  ↓
push branch
  ↓
open draft pull request
  ↓
wait for CI
  ↓
review
  ↓
human review
  ↓
mark ready or merge if configured

17.3 Workflow YAML

id: gitea-issue-to-pr
name: Gitea Issue to Pull Request
version: 1
enabled: true

triggers:
  - id: issue-agent-ready
    type: connector_event
    connector: gitea-main
    event: gitea.issue.labeled
    filter:
      all:
        - path: "$.label.name"
          equals: "agent-ready"
        - path: "$.issue.state"
          equals: "open"

  - id: issue-mentioned
    type: connector_event
    connector: gitea-main
    event: gitea.issue.commented
    filter:
      contains:
        path: "$.comment.body"
        value: "@agenthub"

stages:
  - id: load_issue
    type: connector_action
    connector: gitea-main
    action: gitea.load_issue_context
    input:
      repository: "{{ event.payload.repository.full_name }}"
      issue_number: "{{ event.payload.issue.number }}"
    outputs:
      issue_context: result

  - id: triage
    type: agent
    agent: gitea-triage-agent
    input:
      issue_context: "{{ issue_context }}"
    outputs:
      triage: result

  - id: maybe_stop
    type: condition
    expression: "{{ triage.outputs.suitable == true }}"
    on_true: generate_spec
    on_false: comment_not_suitable

  - id: comment_not_suitable
    type: connector_action
    connector: gitea-main
    action: gitea.create_issue_comment
    input:
      repository: "{{ issue_context.repository }}"
      issue_number: "{{ issue_context.number }}"
      body: "AgentHub triaged this issue as not suitable for automation: {{ triage.outputs.reason }}"
    next: complete_not_suitable

  - id: complete_not_suitable
    type: terminal
    status: success

  - id: generate_spec
    type: agent_team
    team: gitea-spec-team
    input:
      issue_context: "{{ issue_context }}"
      triage: "{{ triage }}"
    outputs:
      spec_bundle: result

  - id: approve_spec
    type: approval
    title: "Approve generated spec"
    required_roles:
      - maintainer
    input:
      spec_bundle: "{{ spec_bundle }}"

  - id: implement
    type: agent
    agent: mini-swe-implementation-agent
    input:
      issue_context: "{{ issue_context }}"
      spec_bundle: "{{ spec_bundle }}"
    outputs:
      implementation: result

  - id: open_pr
    type: connector_action
    connector: gitea-main
    action: gitea.open_draft_pr
    input:
      repository: "{{ issue_context.repository }}"
      issue_number: "{{ issue_context.number }}"
      implementation: "{{ implementation }}"
    outputs:
      pull_request: result

  - id: wait_for_ci
    type: wait_for_condition
    connector: gitea-main
    condition: gitea.pr_checks_completed
    timeout_minutes: 60
    input:
      repository: "{{ issue_context.repository }}"
      pull_request_number: "{{ pull_request.number }}"
    outputs:
      ci_result: result

  - id: review_pr
    type: agent_team
    team: pr-review-team
    input:
      pull_request: "{{ pull_request }}"
      spec_bundle: "{{ spec_bundle }}"
      ci_result: "{{ ci_result }}"
    outputs:
      review: result

  - id: human_review
    type: approval
    title: "Approve PR readiness"
    required_roles:
      - maintainer
    input:
      pull_request: "{{ pull_request }}"
      review: "{{ review }}"

  - id: maybe_merge
    type: condition
    expression: "{{ workflow.config.merge.mode == 'merge_after_approval' }}"
    on_true: merge_pr
    on_false: mark_ready

  - id: mark_ready
    type: connector_action
    connector: gitea-main
    action: gitea.create_pr_comment
    input:
      repository: "{{ issue_context.repository }}"
      pull_request_number: "{{ pull_request.number }}"
      body: "AgentHub marked this PR as ready for human merge."
    next: complete

  - id: merge_pr
    type: connector_action
    connector: gitea-main
    action: gitea.merge_pr
    input:
      repository: "{{ issue_context.repository }}"
      pull_request_number: "{{ pull_request.number }}"
      strategy: squash
    next: complete

  - id: complete
    type: terminal
    status: success

17.4 Spec Storage

Default:

specs:
  store_as_artifacts: true
  commit_to_branch: true
  commit_to_default_branch: false

Generated specs should be visible in AgentHub and optionally included in the PR branch.

17.5 Spec Bundle Layout

.agenthub/specs/issue-123/
  metadata.yaml
  conversation.md
  spec.md
  plan.md
  tasks.md
  test-plan.md
  decisions.md
  implementation-log.md

17.6 PR Revision Loop

PR review/comment received
  ↓
authorized command or changes requested detected
  ↓
workflow revision stage starts
  ↓
comments summarized
  ↓
implementation agent updates branch
  ↓
tests run
  ↓
PR updated
  ↓
status comment posted

18. Agent System

18.1 Agent Definition

Agents are configured units that perform tasks.

Each agent has:

name
role
runtime
model routing policy
prompt templates
tool grants
sandbox configuration
output schema
limits
permissions

18.2 Agent Roles

Common roles:

triage
planner
spec_writer
researcher
coder
reviewer
tester
security_reviewer
documentation_writer
operator
manager
judge
router

18.3 Agent Teams and Hierarchy

AgentHub has its own native team abstraction.

Team patterns:

sequential
parallel
hierarchical
supervisor_worker
debate_judge
router_specialist
review_board

These are mapped onto runtime-specific implementations.

Example mappings:

AgentHub hierarchical team → CrewAI hierarchical process
AgentHub coding worker → mini-SWE-agent
AgentHub review board → CrewAI or custom parallel runner
Future AgentHub graph team → LangGraph

18.4 CrewAI Role

CrewAI is an optional runtime adapter for agent teams.

It is useful for:

hierarchical spec generation
planning
research
review boards
risk analysis
multi-perspective critique
manager-worker execution

It is not the core platform orchestration engine.

19. Runtime Adapter System

19.1 Runtime Adapter Interface

Every runtime adapter should expose:

validate definition
prepare run
start run
stream events/logs
cancel run
collect result
cleanup

19.2 MVP Runtime Adapters

llm_prompt
script
mini_swe_agent
crewai

19.3 Runtime Result Contract

All runtimes must return a normalized result:

status: success | failed | cancelled | timed_out | needs_input | blocked
summary: string
outputs: object
artifacts: []
events: []
cost:
  input_tokens: number
  output_tokens: number
  estimated_cost: number
errors: []
recommended_actions: []

20. Model Gateway and Model Registry

20.1 Supported MVP Providers

AgentHub must normalize model access across:

Kimi
OpenAI
Anthropic
Ollama
OpenAI-compatible endpoints

Implementation order:

1. Kimi
2. OpenAI
3. OpenAI-compatible generic endpoint
4. Anthropic
5. Ollama

Kimi should be supported as a first-class provider profile through the normalized model gateway, using OpenAI-compatible API behavior where possible.

20.2 Model Routing

AgentHub uses a global model registry with workflow, agent, and stage overrides.

Resolution order:

stage explicit model
  ↓
agent explicit model
  ↓
team member explicit model
  ↓
workflow model routing policy
  ↓
project model routing policy
  ↓
workspace/global model routing policy
  ↓
system default model

20.3 Model Gateway Requirement

All model calls should route through AgentHub where technically possible.

The model gateway enables:

provider abstraction
cost tracking
token tracking
fallbacks
routing
rate limiting
redaction
audit records
model health checks

Some third-party runtimes may require direct model credentials. Those exceptions must be explicit.

20.4 Model Provider Definition

id: kimi-main
type: kimi
name: Kimi Main
base_url: https://api.moonshot.ai/v1
api_key_secret: kimi_api_key
enabled: true

models:
  - id: kimi-default
    model_name: kimi-k2
    capabilities:
      - chat
      - structured_output
      - tool_calling

21. Tool Registry and Tool Grants

Tools are explicitly granted per agent or per team.

No agent receives all tools by default.

Default grants:

no shell
no filesystem write
no external write
no secret access
no merge

Tool categories:

filesystem
shell
git
http
browser
database
connector_action
vector_search
code_search
notification
artifact
human_input

Tool risk levels:

low
medium
high
critical

Examples:

read issue: low
post comment: medium
write file: medium
push branch: high
merge pull request: critical
access secret: critical
deploy production: critical

22. Policy Engine

22.1 MVP Policy Engine

AgentHub uses a native YAML policy engine in the MVP.

It should later remain compatible with or replaceable by:

OPA/Rego
Cedar
CEL
custom policy DSL

22.2 Policy Decisions

Policies return:

decision: allow | deny | require_approval
reason: string
matched_rules: []
risk_level: low | medium | high | critical
required_approvals: []

22.3 Policy Evaluation Points

Evaluate policies before:

starting workflow
starting stage
invoking model
granting tool
accessing secret
running shell command
writing file
calling connector action
posting external comment
opening pull request
merging pull request
sending notification
indexing memory
retrying with elevated permissions

22.4 Example Policy

id: default-secure-policy
name: Default Secure Policy
enabled: true

rules:
  - id: deny-secret-file-read
    effect: deny
    action: filesystem.read
    paths:
      - ".env"
      - "**/*.pem"
      - "**/*.key"

  - id: require-approval-for-network
    effect: require_approval
    action: sandbox.network.enable
    required_roles:
      - maintainer

  - id: require-approval-for-pr-merge
    effect: require_approval
    action: git.pull_request.merge
    required_roles:
      - maintainer

  - id: max-cost-per-run
    effect: deny
    action: model.invoke
    condition:
      estimated_cost_usd_gt: 10

23. Secrets

23.1 MVP Secret Store

AgentHub uses an internal encrypted secret store in the MVP.

Secrets must be:

encrypted at rest
scoped to workspace/project/connector/agent
masked in logs
not exposed to agents by default
granted only when needed
audited when accessed

23.2 Future Secret Providers

HashiCorp Vault
Kubernetes Secrets
AWS Secrets Manager
GCP Secret Manager
Azure Key Vault
1Password Connect
Doppler

24. Sandbox and Execution Security

24.1 MVP Sandbox

Each code-executing agent run uses a Docker sandbox.

Default sandbox behavior:

one container per run
resource limits
timeout
non-privileged
no host Docker socket
network disabled by default
controlled environment variables
workspace mounted explicitly
logs captured and redacted
artifacts extracted safely

24.2 Network Access

Network access is disabled by default.

It may be enabled per workflow, stage, or agent after policy evaluation.

24.3 Runner Images

Use a shared default runner image:

agenthub/runner:latest

Allow per-agent override:

sandbox:
  image: custom/image:tag

25. Memory and Vector Indexing

25.1 Vector Database

AgentHub includes vector memory from day one using:

PostgreSQL + pgvector

25.2 Memory Philosophy

Memory is explicit, scoped, inspectable, and permission-controlled.

AgentHub must not silently index everything.

25.3 Indexing Policy

Indexing is explicit.

Users or workflows choose what to index.

Supported memory scopes:

workspace
project
team
repository
connector
workflow
run
artifact

25.4 First Memory Sources

Memory may store:

workflow artifacts
run summaries
repository knowledge
issue and PR context
documentation snippets
connector/resource knowledge
human-approved notes

25.5 Memory Requirements

Memory items should include:

source reference
scope
created_at
updated_at
freshness metadata
permissions
embedding model
content hash

26. Artifact Storage

AgentHub uses MinIO from day one.

Artifacts include:

markdown
json
yaml
text
patch
diff
log
test_report
html
image
screenshot
pull_request_reference
external_link
decision_record
model_trace

Artifacts must be:

versioned where needed
previewable in UI
downloadable
linked to runs and stages
available in approvals
referenced by later stages
immutable once finalized

27. Approval System

27.1 Approval Types

stage_approval
action_approval
policy_approval
spec_approval
merge_approval
secret_access_approval
cost_approval
memory_indexing_approval

27.2 Git Workflow Defaults

Spec approval is required by default.

Merge approval is required if AgentHub is configured to merge.

27.3 Merge Behavior

Merge behavior is configurable per project, repository, or workflow.

Default:

merge:
  mode: mark_ready_only
  allow_agenthub_merge: false

Optional controlled merge:

merge:
  mode: merge_after_approval
  allow_agenthub_merge: true
  require_human_approval: true
  require_ci_success: true
  require_no_unresolved_threads: true
  strategy: squash

Agents must never merge directly.

Merge is a platform connector action gated by policy and approval.

28. Logging, Prompts, and Traces

28.1 Default Storage

AgentHub stores:

redacted prompts
model outputs
tool calls
runtime logs
artifacts
policy decisions
approval decisions
connector actions
cost metadata

AgentHub does not store hidden model reasoning or private chain-of-thought.

28.2 Configurable Trace Storage

Future versions may allow per-workspace or per-workflow trace settings:

trace_storage:
  store_full_prompts: false
  store_redacted_prompts: true
  store_model_outputs: true
  store_tool_calls: true
  store_hidden_reasoning: false

29. External Comments and Commands

External comments may trigger commands if authorized.

For the Gitea workflow, supported commands should include:

@agenthub status
@agenthub generate spec
@agenthub approve spec
@agenthub start implementation
@agenthub revise
@agenthub retry
@agenthub cancel
@agenthub merge

Before accepting a command:

actor must be authorized
workflow must allow external commands
command must be valid for current state
policy must allow the action
approval may be required

External issue/PR content is always treated as untrusted context.

30. User Interface Requirements

Dashboard
Workspaces
Projects
Teams
Workflows
Runs
Agents
Agent Teams
Models
Connectors
Triggers
Monitors
Tools
Memory
Approvals
Artifacts
Policies
Secrets
Audit Log
Settings

30.2 Dashboard

Show:

active workflow runs
waiting approvals
failed runs
recently completed runs
agent runs by status
connector health
model usage
token/cost estimates
sandbox activity
recent audit events

30.3 Run Detail Page

Show:

workflow version
trigger source
input payload
current stage
stage timeline
agent runs
logs
artifacts
approvals
policy decisions
events
errors
cost estimate

Actions:

cancel
retry failed stage
approve
reject
request changes
download artifacts
copy run link

30.4 Workflow Detail Page

Tabs:

Overview
YAML Definition
Graph Preview
Runs
Triggers
Monitors
Policies
Versions
Settings

30.5 Agent Team Page

Support:

team type
manager agent
member agents
model assignments
runtime adapter
tool grants
recent runs
test run

30.6 Memory Page

Support:

collections
scopes
indexed sources
search
delete memory item
inspect source
re-index
permissions

31. Data Model

31.1 Workspaces

workspaces (
  id uuid primary key,
  name text not null,
  slug text unique not null,
  created_at timestamptz not null,
  updated_at timestamptz not null
)

31.2 Users

users (
  id uuid primary key,
  workspace_id uuid references workspaces(id),
  email text not null,
  name text,
  external_subject text,
  role text not null,
  created_at timestamptz not null,
  updated_at timestamptz not null,
  unique(workspace_id, email)
)

31.3 Projects

projects (
  id uuid primary key,
  workspace_id uuid references workspaces(id),
  name text not null,
  slug text not null,
  description text,
  created_at timestamptz not null,
  updated_at timestamptz not null,
  unique(workspace_id, slug)
)

31.4 Teams

teams (
  id uuid primary key,
  workspace_id uuid references workspaces(id),
  name text not null,
  slug text not null,
  created_at timestamptz not null,
  updated_at timestamptz not null,
  unique(workspace_id, slug)
)

31.5 Team Memberships

team_memberships (
  id uuid primary key,
  team_id uuid references teams(id),
  user_id uuid references users(id),
  role text not null,
  created_at timestamptz not null
)

31.6 Project Memberships

project_memberships (
  id uuid primary key,
  project_id uuid references projects(id),
  user_id uuid references users(id),
  team_id uuid references teams(id),
  role text not null,
  created_at timestamptz not null,
  check (
    user_id is not null or team_id is not null
  )
)

31.7 Connectors

connectors (
  id uuid primary key,
  workspace_id uuid references workspaces(id),
  project_id uuid references projects(id),
  name text not null,
  type text not null,
  enabled boolean not null default true,
  config jsonb not null,
  secret_refs jsonb not null default '[]',
  health_status text not null default 'unknown',
  created_at timestamptz not null,
  updated_at timestamptz not null
)

31.8 Workflows

workflows (
  id uuid primary key,
  workspace_id uuid references workspaces(id),
  project_id uuid references projects(id),
  name text not null,
  slug text not null,
  enabled boolean not null default false,
  current_version integer not null default 1,
  description text,
  created_by uuid references users(id),
  created_at timestamptz not null,
  updated_at timestamptz not null,
  unique(project_id, slug)
)

31.9 Workflow Versions

workflow_versions (
  id uuid primary key,
  workflow_id uuid references workflows(id),
  version integer not null,
  definition jsonb not null,
  created_by uuid references users(id),
  created_at timestamptz not null,
  unique(workflow_id, version)
)

31.10 Workflow Runs

workflow_runs (
  id uuid primary key,
  workspace_id uuid references workspaces(id),
  project_id uuid references projects(id),
  workflow_id uuid references workflows(id),
  workflow_version_id uuid references workflow_versions(id),
  status text not null,
  trigger_event_id uuid,
  input jsonb not null,
  state jsonb not null default '{}',
  definition_snapshot jsonb not null,
  current_stage text,
  correlation_id text not null,
  started_by uuid references users(id),
  started_at timestamptz,
  completed_at timestamptz,
  created_at timestamptz not null,
  updated_at timestamptz not null
)

31.11 Stage Runs

stage_runs (
  id uuid primary key,
  workflow_run_id uuid references workflow_runs(id),
  stage_id text not null,
  stage_type text not null,
  status text not null,
  input jsonb not null default '{}',
  output jsonb,
  error jsonb,
  attempts integer not null default 0,
  started_at timestamptz,
  completed_at timestamptz,
  created_at timestamptz not null,
  updated_at timestamptz not null
)

31.12 Agents

agents (
  id uuid primary key,
  workspace_id uuid references workspaces(id),
  project_id uuid references projects(id),
  name text not null,
  slug text not null,
  type text not null,
  runtime text not null,
  enabled boolean not null default true,
  definition jsonb not null,
  created_by uuid references users(id),
  created_at timestamptz not null,
  updated_at timestamptz not null,
  unique(project_id, slug)
)

31.13 Agent Teams

agent_teams (
  id uuid primary key,
  workspace_id uuid references workspaces(id),
  project_id uuid references projects(id),
  name text not null,
  slug text not null,
  type text not null,
  runtime text,
  enabled boolean not null default true,
  definition jsonb not null,
  created_by uuid references users(id),
  created_at timestamptz not null,
  updated_at timestamptz not null,
  unique(project_id, slug)
)

31.14 Agent Runs

agent_runs (
  id uuid primary key,
  workflow_run_id uuid references workflow_runs(id),
  stage_run_id uuid references stage_runs(id),
  agent_id uuid references agents(id),
  agent_team_id uuid references agent_teams(id),
  runtime text not null,
  status text not null,
  input jsonb not null,
  output jsonb,
  error jsonb,
  cost jsonb,
  started_at timestamptz,
  completed_at timestamptz,
  created_at timestamptz not null,
  updated_at timestamptz not null
)

31.15 Models

models (
  id uuid primary key,
  workspace_id uuid references workspaces(id),
  name text not null,
  provider text not null,
  model_name text not null,
  enabled boolean not null default true,
  config jsonb not null,
  limits jsonb not null default '{}',
  capabilities jsonb not null default '[]',
  created_at timestamptz not null,
  updated_at timestamptz not null
)

31.16 Tools

tools (
  id uuid primary key,
  workspace_id uuid references workspaces(id),
  name text not null,
  type text not null,
  enabled boolean not null default true,
  definition jsonb not null,
  risk_level text not null default 'medium',
  created_at timestamptz not null,
  updated_at timestamptz not null
)

31.17 Policies

policies (
  id uuid primary key,
  workspace_id uuid references workspaces(id),
  project_id uuid references projects(id),
  name text not null,
  enabled boolean not null default true,
  scope text not null,
  definition jsonb not null,
  created_by uuid references users(id),
  created_at timestamptz not null,
  updated_at timestamptz not null
)

31.18 Approvals

approvals (
  id uuid primary key,
  workflow_run_id uuid references workflow_runs(id),
  stage_run_id uuid references stage_runs(id),
  type text not null,
  status text not null,
  title text not null,
  description text,
  requested_by uuid references users(id),
  resolved_by uuid references users(id),
  required_roles jsonb not null default '[]',
  context jsonb not null default '{}',
  resolved_comment text,
  expires_at timestamptz,
  created_at timestamptz not null,
  resolved_at timestamptz
)

31.19 Artifacts

artifacts (
  id uuid primary key,
  workspace_id uuid references workspaces(id),
  project_id uuid references projects(id),
  workflow_run_id uuid references workflow_runs(id),
  stage_run_id uuid references stage_runs(id),
  agent_run_id uuid references agent_runs(id),
  type text not null,
  name text not null,
  uri text not null,
  content_type text,
  metadata jsonb not null default '{}',
  hash text,
  created_at timestamptz not null
)

31.20 Memory Collections

memory_collections (
  id uuid primary key,
  workspace_id uuid references workspaces(id),
  project_id uuid references projects(id),
  name text not null,
  scope text not null,
  config jsonb not null default '{}',
  created_at timestamptz not null,
  updated_at timestamptz not null
)

31.21 Memory Items

memory_items (
  id uuid primary key,
  collection_id uuid references memory_collections(id),
  source_type text not null,
  source_id text,
  content text not null,
  content_hash text not null,
  metadata jsonb not null default '{}',
  embedding vector,
  created_at timestamptz not null,
  updated_at timestamptz not null
)

31.22 Events

events (
  id uuid primary key,
  workspace_id uuid references workspaces(id),
  project_id uuid references projects(id),
  type text not null,
  source text not null,
  connector_id uuid references connectors(id),
  workflow_run_id uuid references workflow_runs(id),
  correlation_id text,
  external_id text,
  actor jsonb,
  resource jsonb,
  payload jsonb not null,
  created_at timestamptz not null
)

31.23 Audit Logs

audit_logs (
  id uuid primary key,
  workspace_id uuid references workspaces(id),
  project_id uuid references projects(id),
  actor_type text not null,
  actor_id text,
  action text not null,
  target_type text,
  target_id text,
  result text not null,
  policy_decision jsonb,
  metadata jsonb not null default '{}',
  correlation_id text,
  created_at timestamptz not null
)

31.24 Secrets

secrets (
  id uuid primary key,
  workspace_id uuid references workspaces(id),
  project_id uuid references projects(id),
  name text not null,
  scope text not null,
  provider text not null,
  reference text not null,
  encrypted_value bytea,
  metadata jsonb not null default '{}',
  created_by uuid references users(id),
  created_at timestamptz not null,
  updated_at timestamptz not null
)

32. Backend API

32.1 Workspaces, Projects, Teams

GET /api/workspaces
POST /api/workspaces
GET /api/workspaces/{workspace_id}

GET /api/projects
POST /api/projects
GET /api/projects/{project_id}
PATCH /api/projects/{project_id}

GET /api/teams
POST /api/teams
GET /api/teams/{team_id}
PATCH /api/teams/{team_id}
POST /api/teams/{team_id}/members
DELETE /api/teams/{team_id}/members/{user_id}

32.2 Workflows

GET /api/workflows
POST /api/workflows
GET /api/workflows/{workflow_id}
PATCH /api/workflows/{workflow_id}
DELETE /api/workflows/{workflow_id}
POST /api/workflows/{workflow_id}/enable
POST /api/workflows/{workflow_id}/disable
POST /api/workflows/{workflow_id}/versions
GET /api/workflows/{workflow_id}/versions
POST /api/workflows/{workflow_id}/run
POST /api/workflows/{workflow_id}/validate

32.3 Workflow Runs

GET /api/runs
GET /api/runs/{run_id}
POST /api/runs/{run_id}/cancel
POST /api/runs/{run_id}/pause
POST /api/runs/{run_id}/resume
POST /api/runs/{run_id}/retry
POST /api/runs/{run_id}/retry-stage/{stage_run_id}
GET /api/runs/{run_id}/events
GET /api/runs/{run_id}/logs
GET /api/runs/{run_id}/artifacts
GET /api/runs/{run_id}/stream

32.4 Agents and Agent Teams

GET /api/agents
POST /api/agents
GET /api/agents/{agent_id}
PATCH /api/agents/{agent_id}
DELETE /api/agents/{agent_id}
POST /api/agents/{agent_id}/test
GET /api/agents/{agent_id}/runs

GET /api/agent-teams
POST /api/agent-teams
GET /api/agent-teams/{team_id}
PATCH /api/agent-teams/{team_id}
DELETE /api/agent-teams/{team_id}
POST /api/agent-teams/{team_id}/test

32.5 Models

GET /api/models
POST /api/models
GET /api/models/{model_id}
PATCH /api/models/{model_id}
DELETE /api/models/{model_id}
POST /api/models/{model_id}/test

32.6 Connectors

GET /api/connectors
POST /api/connectors
GET /api/connectors/{connector_id}
PATCH /api/connectors/{connector_id}
DELETE /api/connectors/{connector_id}
POST /api/connectors/{connector_id}/test
GET /api/connectors/{connector_id}/events
GET /api/connectors/{connector_id}/resources

32.7 Triggers and Monitors

GET /api/triggers
POST /api/triggers
GET /api/triggers/{trigger_id}
PATCH /api/triggers/{trigger_id}
DELETE /api/triggers/{trigger_id}
POST /api/triggers/{trigger_id}/enable
POST /api/triggers/{trigger_id}/disable

GET /api/monitors
POST /api/monitors
GET /api/monitors/{monitor_id}
PATCH /api/monitors/{monitor_id}
DELETE /api/monitors/{monitor_id}
POST /api/monitors/{monitor_id}/enable
POST /api/monitors/{monitor_id}/disable
POST /api/monitors/{monitor_id}/run-now

32.8 Approvals

GET /api/approvals
GET /api/approvals/{approval_id}
POST /api/approvals/{approval_id}/approve
POST /api/approvals/{approval_id}/reject
POST /api/approvals/{approval_id}/request-changes

32.9 Artifacts and Memory

GET /api/artifacts
GET /api/artifacts/{artifact_id}
GET /api/artifacts/{artifact_id}/download
GET /api/artifacts/{artifact_id}/preview

GET /api/memory/collections
POST /api/memory/collections
GET /api/memory/collections/{collection_id}
POST /api/memory/collections/{collection_id}/index
POST /api/memory/search
DELETE /api/memory/items/{memory_item_id}

32.10 Webhooks

POST /api/webhooks/{connector_type}/{connector_id}
POST /api/webhooks/generic/{trigger_id}

32.11 Policies

GET /api/policies
POST /api/policies
GET /api/policies/{policy_id}
PATCH /api/policies/{policy_id}
DELETE /api/policies/{policy_id}
POST /api/policies/evaluate

33. MVP Scope

33.1 MVP Must Prove

The MVP must prove:

AgentHub can run general workflows.
AgentHub can run workflows from external triggers.
AgentHub can orchestrate multiple runtimes.
AgentHub can support multi-user teams and projects.
AgentHub can use explicit vector memory.
AgentHub can complete the Gitea issue-to-PR workflow.
AgentHub can run a generic non-Git webhook workflow.

33.2 MVP Required Features

Platform

Docker Compose deployment
Authentik OIDC login
workspace support
team support
project support
role model
dashboard
workflow registry
YAML workflow editor
workflow validator
run timeline
live logs
artifact viewer
approval inbox
event log
audit log

Connectors

Gitea connector
generic webhook connector
HTTP connector
artifact-store connector

Triggers and Monitors

manual trigger
webhook trigger
Gitea label trigger
Gitea mention trigger
basic polling monitor

Runtimes

LLM prompt adapter
script adapter
mini-SWE-agent adapter
CrewAI adapter

Models

Kimi
OpenAI
OpenAI-compatible
Anthropic
Ollama

Security

internal encrypted secret store
native YAML policy engine
explicit tool grants
Docker sandbox
network disabled by default
redacted traces
approval gates
controlled merge only when configured

Storage

PostgreSQL
pgvector
Redis
MinIO

34. MVP Exclusions

Not required for MVP:

visual workflow builder
GitOps configuration
GitLab connector completeness
GitHub connector completeness
Kubernetes runners
Firecracker/gVisor
full event sourcing
full OPA/Rego
custom RBAC DSL
silent automatic memory indexing
automatic merge by default
agent-launched sub-workflows
SaaS multi-tenancy

35. Development Milestones

Milestone 1: Platform Skeleton

Deliverables:

monorepo with Turbo + pnpm
Docker Compose
Postgres
Redis
MinIO
FastAPI app
Celery worker
Next.js app
Authentik OIDC login
workspace/project/team schema
basic dashboard
Apache-2.0 license

Milestone 2: Core Workflow Engine

Deliverables:

workflow YAML schema
workflow validation
workflow versioning
manual workflow run
stage run records
event append discipline
Redis/Celery-backed execution
run timeline UI
terminal stage
condition stage
approval stage

Milestone 3: Kimi Model Gateway and Simple Agents

Deliverables:

model registry
Kimi provider
model gateway interface
LLM prompt runtime
agent registry
agent run logs
artifact creation
first vertical slice workflow

Milestone 4: Artifact and Approval Flow

Deliverables:

MinIO artifact store
artifact viewer
approval inbox
approval actions
approval events
approval audit logs
manual workflow → Kimi prompt → artifact → approval complete

Milestone 5: Generic Webhook Workflow

Deliverables:

connector registry
generic webhook connector
HTTP connector
webhook summarizer workflow
approval gate
HTTP callback action
audit logging for external writes

Milestone 6: Memory Foundation

Deliverables:

pgvector setup
memory collections
explicit indexing
memory search
memory permission scope
memory source references

Milestone 7: Gitea Connector

Deliverables:

Gitea token auth
repository registration
issue loading
comment loading
label trigger
mention trigger
post comment
branch creation support
pull request creation
CI/check status monitor where supported

Milestone 8: Runtime Adapters

Deliverables:

script adapter
Docker sandbox manager
mini-SWE-agent adapter
basic CrewAI adapter
runtime logs
runtime cancellation
runtime artifacts

Milestone 9: Gitea Issue-to-PR Workflow

Deliverables:

issue trigger
triage agent
spec generation team
spec approval
mini-SWE-agent implementation
branch push
draft pull request
CI wait
review stage
revision loop
controlled merge or mark-ready behavior

Milestone 10: Policy and Security Hardening

Deliverables:

YAML policy engine
tool grants
protected actions
protected file paths
network controls
secret scoping
log redaction
merge policy
cost limits
runtime limits
audit coverage

Milestone 11: Packaging and Documentation

Deliverables:

sample workflows
sample agents
sample policies
setup docs
Gitea demo project
generic webhook demo
development docs
operator docs
security notes
model provider docs
runtime adapter docs
connector SDK docs

36. Definition of Done for MVP

The MVP is done when:

AgentHub runs with Docker Compose.
Authentik OIDC login works.
Multiple users can exist.
Users can belong to teams.
Projects can be created and owned by users or teams.
A workflow can be authored in YAML.
A workflow run stores an immutable definition snapshot.
A workflow can be manually triggered.
A generic webhook can trigger a workflow.
A Gitea issue label can trigger a workflow.
A Gitea comment mention can trigger a workflow command.
A workflow can pause for approval.
A workflow can run a Kimi-backed LLM prompt agent.
A workflow can run a CrewAI team.
A workflow can run mini-SWE-agent in Docker.
A workflow can store artifacts in MinIO.
AgentHub can explicitly index selected data into pgvector.
The UI shows run timeline, logs, artifacts, approvals, and events.
AgentHub can generate a spec from a Gitea issue.
A maintainer can approve the spec.
AgentHub can run an implementation agent.
AgentHub can push a branch.
AgentHub can open a draft pull request.
AgentHub can monitor CI/check status where supported.
AgentHub can revise a PR based on authorized comments.
AgentHub can mark a PR ready or merge it only if configured, approved, and CI passes.
All external writes are audit logged.
Secrets are encrypted and masked.
Network access is disabled by default for agent sandboxes.
Tools are explicitly granted to agents or teams.
Hidden model reasoning is not stored.

37. Immediate Development Plan

37.1 Step 1: Repository Foundation

Create the monorepo:

agenthub/
  apps/web
  apps/api
  apps/worker
  packages/shared
  infra/docker-compose.yml

Add:

Apache-2.0 license
README.md
CONTRIBUTING.md
docs/development.md
.env.example

37.2 Step 2: Docker Compose

Add services:

web
api
worker
postgres
redis
minio

Optional development profile:

authentik
gitea
ollama

37.3 Step 3: Backend Foundation

Implement:

FastAPI app
SQLAlchemy setup
Alembic setup
health endpoint
database session handling
configuration loading
structured logging

37.4 Step 4: Authentik OIDC

Implement:

OIDC login
callback handling
session/JWT handling
user provisioning
workspace bootstrap
role assignment

37.5 Step 5: Workflow Foundation

Implement:

workflow schema
workflow validation
workflow versioning
manual run creation
workflow run snapshot
stage run table
event append function
Celery stage execution

37.6 Step 6: Kimi Model Gateway

Implement:

model provider registry
Kimi provider
chat completion interface
structured output helper
token/cost metadata placeholder
model invocation logs

37.7 Step 7: First Runtime

Implement:

llm_prompt runtime
agent definition
prompt rendering
model gateway invocation
normalized runtime result
artifact creation

37.8 Step 8: First Vertical Slice

Implement the workflow:

manual trigger
  ↓
Kimi prompt agent
  ↓
markdown artifact in MinIO
  ↓
approval gate
  ↓
completion

This is the first meaningful product checkpoint.

38. Final Baseline Decisions

1. General-purpose agent workflow platform.
2. Built first for small engineering teams.
3. Docker Compose first.
4. Custom lightweight workflow engine, designed to be swappable.
5. YAML-first workflows.
6. Database-first configuration, GitOps later.
7. Immutable workflow run snapshots.
8. CrewAI as runtime adapter, not platform core.
9. MVP runtimes: prompt, script, mini-SWE-agent, CrewAI.
10. Agents can recommend sub-workflows now; policy-approved sub-workflows later.
11. Native AgentHub hierarchy abstraction.
12. Models: Kimi first, then OpenAI, OpenAI-compatible, Anthropic, Ollama.
13. Global model registry with workflow/agent/stage overrides.
14. Model calls route through AgentHub where possible.
15. Internal encrypted secret store first.
16. Native YAML policy engine first.
17. Docker per run first.
18. Network disabled by default.
19. Explicit per-agent/team tool grants.
20. Gitea first, GitLab/GitHub/Forgejo later.
21. API token plus SSH/HTTPS Git hybrid auth.
22. Spec approval required by default.
23. Specs stored as artifacts and optionally committed to PR branch.
24. Merge configurable with approval and passing CI.
25. Authorized external comments can trigger commands.
26. Redacted prompts/traces; no hidden reasoning.
27. Vector DB from day one with explicit scoped indexing.
28. MinIO from day one.
29. Postgres-backed state machine plus append-only events; Redis only for queueing.
30. Apache-2.0 permissive open-source direction.
31. Monorepo uses Turbo + pnpm.
32. Backend uses FastAPI + SQLAlchemy + Alembic.
33. Worker uses Celery + Redis.
34. Authentication uses Authentik OIDC first.
35. First vertical slice is manual workflow → Kimi prompt → artifact → approval.

56 KiB Raw Blame History

AgentHub Specification v0.3

1. Product Summary

2. Product Identity

2.1 First Target Users

3. Product Principles

3.1 Platform Orchestration vs Agent Orchestration

AgentHub owns

Agent runtimes own

3.2 Runtime-Agnostic Architecture

3.3 Human Control

3.4 Explicit Context and Memory

4. Goals

4.1 Product Goals

4.2 Engineering Goals

5. Non-Goals for MVP

6. Implementation Stack

6.1 Final Implementation Decisions

6.2 Recommended App Structure

7. Deployment Model

7.1 MVP Docker Compose Deployment

7.2 Future Deployment

8. Authentication and Authorization

8.1 Authentication

8.2 Workspace Model

8.3 Projects

8.4 MVP Roles

admin

operator

maintainer

developer

viewer

9. Architecture Overview

10. Persistence and Event Model

10.1 Required Tables for Current State

10.2 Required Event Discipline

11. Workflow System

11.1 Workflow Engine

11.2 Workflow Authoring

11.3 Workflow Storage

11.4 Workflow Versioning

11.5 Supported MVP Stage Types

11.6 Agents Starting Sub-Workflows

12. First Vertical Slice Workflow

12.1 Goal

12.2 Acceptance Criteria

12.3 Example Workflow

13. Trigger System

13.1 Trigger Deduplication

13.2 Trigger Authorization

14. Monitor System

15. Connector System

15.1 Connector Strategy

15.2 MVP Connectors

15.3 Future Connectors

15.4 Git Provider Abstraction

15.5 Git Auth Strategy

16. Secondary Reference Workflow: Generic Webhook Summarizer

16.1 Workflow

16.2 Example Workflow

17. Gitea Issue-to-PR Reference Workflow

17.1 Provider Priority

17.2 Default Workflow

17.3 Workflow YAML

17.4 Spec Storage

17.5 Spec Bundle Layout

17.6 PR Revision Loop

18. Agent System

18.1 Agent Definition

18.2 Agent Roles

18.3 Agent Teams and Hierarchy

18.4 CrewAI Role

19. Runtime Adapter System

19.1 Runtime Adapter Interface

19.2 MVP Runtime Adapters

19.3 Runtime Result Contract

20. Model Gateway and Model Registry

20.1 Supported MVP Providers

20.2 Model Routing

20.3 Model Gateway Requirement

56 KiB

Raw Blame History