3935 lines
68 KiB
Markdown
3935 lines
68 KiB
Markdown
# Spec Definition: Self-Hosted Agent Hub and Orchestration Platform
|
|
|
|
Version: 0.1
|
|
Status: Draft
|
|
Primary Example Workflow: Git Issue to Spec to Pull Request
|
|
Working Name: AgentHub
|
|
|
|
---
|
|
|
|
# 1. Product Summary
|
|
|
|
AgentHub is a self-hosted, configurable platform for defining, managing, orchestrating, observing, and governing AI agents across arbitrary workflows.
|
|
|
|
The platform allows users to define external triggers, connect external systems, configure agents and models, compose workflows, monitor long-running runs, enforce policy gates, route tasks to different agent runtimes, and review all actions through a web interface.
|
|
|
|
The initial reference implementation is a Git repository workflow:
|
|
|
|
```text
|
|
GitHub / GitLab issue
|
|
↓
|
|
trigger or monitor condition
|
|
↓
|
|
agent workflow starts
|
|
↓
|
|
spec generation
|
|
↓
|
|
implementation agent
|
|
↓
|
|
pull request creation
|
|
↓
|
|
review and revision loop
|
|
↓
|
|
human-approved merge
|
|
```
|
|
|
|
However, this Git PR flow is only the first example. The core product is a general-purpose agent orchestration hub.
|
|
|
|
---
|
|
|
|
# 2. Product Vision
|
|
|
|
AgentHub should become the self-hosted control plane for AI agents.
|
|
|
|
It should allow a team to answer questions like:
|
|
|
|
* Which agents exist?
|
|
* Which models do they use?
|
|
* Which tools can they access?
|
|
* Which workflows can trigger them?
|
|
* What external systems can they monitor?
|
|
* What are they currently doing?
|
|
* What did they change?
|
|
* Which human approvals are required?
|
|
* Which policies blocked or allowed their actions?
|
|
* Which agent runtime performed best for a given task type?
|
|
|
|
The goal is not just to run agents, but to make agent execution **visible, configurable, repeatable, auditable, and safe**.
|
|
|
|
---
|
|
|
|
# 3. Core Design Principle
|
|
|
|
AgentHub separates two different kinds of orchestration.
|
|
|
|
## 3.1 Platform Orchestration
|
|
|
|
Platform orchestration is deterministic and owned by AgentHub.
|
|
|
|
It handles:
|
|
|
|
```text
|
|
external trigger received
|
|
↓
|
|
workflow selected
|
|
↓
|
|
policy checked
|
|
↓
|
|
stage started
|
|
↓
|
|
agent runtime invoked
|
|
↓
|
|
artifact collected
|
|
↓
|
|
approval requested
|
|
↓
|
|
next stage selected
|
|
↓
|
|
workflow completed
|
|
```
|
|
|
|
Platform orchestration should be reliable, inspectable, resumable, and auditable.
|
|
|
|
## 3.2 Agent Orchestration
|
|
|
|
Agent orchestration may be probabilistic and runtime-specific.
|
|
|
|
It handles:
|
|
|
|
```text
|
|
manager agent delegates task
|
|
↓
|
|
research agent gathers context
|
|
↓
|
|
planner agent proposes plan
|
|
↓
|
|
implementation agent makes changes
|
|
↓
|
|
review agent critiques output
|
|
↓
|
|
judge agent accepts or rejects result
|
|
```
|
|
|
|
Agent orchestration may be powered by:
|
|
|
|
* CrewAI
|
|
* LangGraph
|
|
* OpenHands
|
|
* mini-SWE-agent
|
|
* PR-Agent
|
|
* custom scripts
|
|
* custom Docker containers
|
|
* custom Python/TypeScript agents
|
|
* local model workers
|
|
|
|
AgentHub should not hard-code one agent framework as the platform. It should provide a runtime adapter interface.
|
|
|
|
---
|
|
|
|
# 4. Goals
|
|
|
|
## 4.1 Product Goals
|
|
|
|
AgentHub should allow users to:
|
|
|
|
1. Connect external systems.
|
|
2. Define triggers from external events.
|
|
3. Define monitors that poll or watch external conditions.
|
|
4. Define workflows with stages, branches, approvals, retries, and policies.
|
|
5. Define agents and agent teams.
|
|
6. Define agent hierarchy and delegation patterns.
|
|
7. Route different stages to different agent runtimes.
|
|
8. Route different agents to different models.
|
|
9. Run agents in controlled sandboxes.
|
|
10. Observe all active and historical runs.
|
|
11. Review logs, tool calls, outputs, artifacts, and costs.
|
|
12. Approve or reject workflow stages.
|
|
13. Pause, cancel, retry, or resume workflows.
|
|
14. Enforce security and permission policies.
|
|
15. Use the Git issue-to-PR workflow as the first production example.
|
|
|
|
## 4.2 Engineering Goals
|
|
|
|
AgentHub should be:
|
|
|
|
1. Self-hosted.
|
|
2. Runtime-agnostic.
|
|
3. Model-provider-agnostic.
|
|
4. Connector-agnostic.
|
|
5. Workflow-driven.
|
|
6. Observable.
|
|
7. Secure by default.
|
|
8. Extensible through adapters.
|
|
9. Suitable for Docker Compose deployment first.
|
|
10. Suitable for Kubernetes deployment later.
|
|
11. Designed for long-running asynchronous workflows.
|
|
12. Friendly to local models and air-gapped deployments.
|
|
|
|
---
|
|
|
|
# 5. Non-Goals
|
|
|
|
Initial versions should not attempt to:
|
|
|
|
1. Build a new LLM framework from scratch.
|
|
2. Replace all existing agent frameworks.
|
|
3. Provide a full project management system.
|
|
4. Guarantee correct autonomous decisions.
|
|
5. Automatically execute high-risk actions without approval.
|
|
6. Support every external connector from day one.
|
|
7. Support arbitrary multi-tenant SaaS from day one.
|
|
8. Provide full visual workflow editing in the first MVP.
|
|
9. Replace CI, code review, or deployment systems.
|
|
|
|
---
|
|
|
|
# 6. Product Scope
|
|
|
|
## 6.1 Core Platform
|
|
|
|
The platform core includes:
|
|
|
|
* User interface
|
|
* Backend API
|
|
* Workflow engine
|
|
* Trigger engine
|
|
* Monitor engine
|
|
* Agent registry
|
|
* Model registry
|
|
* Runtime adapter registry
|
|
* Tool registry
|
|
* Connector registry
|
|
* Policy engine
|
|
* Sandbox manager
|
|
* Job queue
|
|
* Event log
|
|
* Audit log
|
|
* Artifact storage
|
|
* Approval system
|
|
* Run monitoring
|
|
|
|
## 6.2 First Reference Workflow
|
|
|
|
The first complete workflow should be:
|
|
|
|
```text
|
|
Managed Git repository
|
|
↓
|
|
Issue labeled or mentioned
|
|
↓
|
|
Workflow starts
|
|
↓
|
|
Spec generation agent/team
|
|
↓
|
|
Optional approval
|
|
↓
|
|
Implementation agent
|
|
↓
|
|
Branch pushed
|
|
↓
|
|
Draft PR opened
|
|
↓
|
|
CI monitored
|
|
↓
|
|
Review agent/team
|
|
↓
|
|
Human review
|
|
↓
|
|
Revision agent if needed
|
|
↓
|
|
Ready for merge
|
|
```
|
|
|
|
---
|
|
|
|
# 7. Primary Users
|
|
|
|
## 7.1 Platform Admin
|
|
|
|
Responsible for:
|
|
|
|
* Instance configuration
|
|
* User access
|
|
* Model provider configuration
|
|
* Global policy configuration
|
|
* Connector setup
|
|
* Secret management
|
|
* Runtime adapter management
|
|
|
|
## 7.2 Workflow Designer
|
|
|
|
Responsible for:
|
|
|
|
* Creating workflows
|
|
* Defining triggers
|
|
* Defining monitors
|
|
* Creating approval gates
|
|
* Selecting agents
|
|
* Configuring model routing
|
|
* Defining retry and failure behavior
|
|
|
|
## 7.3 Agent Operator
|
|
|
|
Responsible for:
|
|
|
|
* Monitoring active runs
|
|
* Debugging failed runs
|
|
* Reviewing logs
|
|
* Tuning agent definitions
|
|
* Adjusting prompts
|
|
* Comparing agent performance
|
|
|
|
## 7.4 Domain Owner
|
|
|
|
Responsible for:
|
|
|
|
* Reviewing outputs
|
|
* Approving actions
|
|
* Providing feedback
|
|
* Deciding whether the workflow result is acceptable
|
|
|
|
For the Git workflow, this user is usually a repository maintainer.
|
|
|
|
## 7.5 Developer / Reviewer
|
|
|
|
Responsible for:
|
|
|
|
* Reviewing generated specs
|
|
* Reviewing generated pull requests
|
|
* Commenting on agent output
|
|
* Approving or requesting changes
|
|
|
|
---
|
|
|
|
# 8. Core Concepts
|
|
|
|
## 8.1 Connector
|
|
|
|
A connector integrates AgentHub with an external system.
|
|
|
|
Examples:
|
|
|
|
* GitHub
|
|
* GitLab
|
|
* Gitea
|
|
* Forgejo
|
|
* Jira
|
|
* Linear
|
|
* Slack
|
|
* Matrix
|
|
* Email
|
|
* HTTP webhook
|
|
* RSS feed
|
|
* S3-compatible object storage
|
|
* Kubernetes
|
|
* Internal APIs
|
|
* Databases
|
|
|
|
Connectors may support:
|
|
|
|
* Events
|
|
* Actions
|
|
* Polling
|
|
* Resource reading
|
|
* Resource writing
|
|
* Authentication
|
|
* Webhook verification
|
|
* Rate limiting
|
|
|
|
## 8.2 Trigger
|
|
|
|
A trigger starts a workflow run.
|
|
|
|
Examples:
|
|
|
|
```text
|
|
GitHub issue labeled "agent-ready"
|
|
GitHub comment mentions "@agenthub"
|
|
Slack slash command received
|
|
HTTP webhook received
|
|
Jira issue enters status "Ready for Agent"
|
|
Scheduled cron trigger fires
|
|
Manual UI trigger clicked
|
|
```
|
|
|
|
Triggers are event-driven.
|
|
|
|
## 8.3 Monitor
|
|
|
|
A monitor watches an external condition and starts or advances a workflow when the condition is met.
|
|
|
|
Examples:
|
|
|
|
```text
|
|
Check every 10 minutes for failed CI jobs
|
|
Watch open PRs with label "needs-agent-review"
|
|
Watch RSS feed for security advisories
|
|
Watch issue backlog for stale items
|
|
Watch deployment health endpoint
|
|
Watch queue length in an external system
|
|
```
|
|
|
|
Monitors are polling, subscription-based, or long-running observers.
|
|
|
|
## 8.4 Workflow
|
|
|
|
A workflow is a versioned definition of stages, transitions, policies, retries, approvals, and runtime calls.
|
|
|
|
A workflow can be triggered manually, by external event, by monitor, by schedule, or by another workflow.
|
|
|
|
## 8.5 Workflow Run
|
|
|
|
A workflow run is a concrete execution of a workflow definition.
|
|
|
|
It has:
|
|
|
|
* Input
|
|
* Current state
|
|
* Stage history
|
|
* Events
|
|
* Artifacts
|
|
* Approvals
|
|
* Logs
|
|
* Errors
|
|
* Final result
|
|
|
|
## 8.6 Stage
|
|
|
|
A stage is one step in a workflow.
|
|
|
|
Stage types:
|
|
|
|
* Agent stage
|
|
* Script stage
|
|
* Connector action stage
|
|
* Approval stage
|
|
* Wait stage
|
|
* Condition stage
|
|
* Parallel stage
|
|
* Human input stage
|
|
* Sub-workflow stage
|
|
* Notification stage
|
|
* Terminal stage
|
|
|
|
## 8.7 Agent
|
|
|
|
An agent is a configured unit capable of performing a task.
|
|
|
|
An agent definition includes:
|
|
|
|
* Name
|
|
* Role
|
|
* Runtime
|
|
* Model
|
|
* Tools
|
|
* Prompt templates
|
|
* Permissions
|
|
* Sandbox settings
|
|
* Memory/context settings
|
|
* Output schema
|
|
|
|
## 8.8 Agent Team
|
|
|
|
An agent team is a structured group of agents.
|
|
|
|
Team patterns:
|
|
|
|
* Sequential team
|
|
* Parallel team
|
|
* Hierarchical team
|
|
* Supervisor-worker team
|
|
* Debate-and-judge team
|
|
* Router-specialist team
|
|
* Review board
|
|
* Swarm-style team
|
|
|
|
## 8.9 Runtime Adapter
|
|
|
|
A runtime adapter invokes a specific agent execution backend.
|
|
|
|
Examples:
|
|
|
|
* CrewAI adapter
|
|
* mini-SWE-agent adapter
|
|
* OpenHands adapter
|
|
* LangGraph adapter
|
|
* PR-Agent adapter
|
|
* shell command adapter
|
|
* Docker container adapter
|
|
* HTTP agent adapter
|
|
* custom SDK adapter
|
|
|
|
## 8.10 Model
|
|
|
|
A model is a configured LLM or model endpoint.
|
|
|
|
Examples:
|
|
|
|
* OpenAI model
|
|
* Anthropic model
|
|
* local Ollama model
|
|
* vLLM-hosted model
|
|
* OpenAI-compatible API endpoint
|
|
* OpenRouter model
|
|
* internal model gateway
|
|
|
|
## 8.11 Tool
|
|
|
|
A tool is an operation an agent can use.
|
|
|
|
Examples:
|
|
|
|
* shell
|
|
* file read/write
|
|
* git
|
|
* browser
|
|
* HTTP client
|
|
* database query
|
|
* GitHub API
|
|
* Slack post
|
|
* Jira update
|
|
* code search
|
|
* vector search
|
|
|
|
## 8.12 Sandbox
|
|
|
|
A sandbox is an isolated execution environment for a run.
|
|
|
|
Examples:
|
|
|
|
* Docker container
|
|
* Kubernetes job
|
|
* Firecracker microVM
|
|
* gVisor sandbox
|
|
* restricted local process
|
|
|
|
## 8.13 Artifact
|
|
|
|
An artifact is any durable output produced by a workflow or agent run.
|
|
|
|
Examples:
|
|
|
|
* generated spec
|
|
* patch file
|
|
* pull request URL
|
|
* log bundle
|
|
* test report
|
|
* generated document
|
|
* JSON output
|
|
* screenshot
|
|
* transcript
|
|
* decision record
|
|
|
|
## 8.14 Policy
|
|
|
|
A policy controls what is allowed.
|
|
|
|
Policies may apply to:
|
|
|
|
* Users
|
|
* Connectors
|
|
* Workflows
|
|
* Stages
|
|
* Agents
|
|
* Tools
|
|
* Models
|
|
* Sandboxes
|
|
* External actions
|
|
* File paths
|
|
* Cost limits
|
|
* Runtime limits
|
|
* Approval requirements
|
|
|
|
## 8.15 Approval Gate
|
|
|
|
An approval gate pauses a workflow until a human or external policy approves or rejects the next action.
|
|
|
|
Examples:
|
|
|
|
* approve generated spec
|
|
* approve sending email
|
|
* approve PR creation
|
|
* approve production deployment
|
|
* approve merge
|
|
* approve secret access
|
|
* approve high-cost model usage
|
|
|
|
---
|
|
|
|
# 9. High-Level Architecture
|
|
|
|
```text
|
|
Web UI
|
|
↓
|
|
Backend API
|
|
↓
|
|
Workflow Engine
|
|
↓
|
|
Job Queue
|
|
↓
|
|
Worker Pool
|
|
↓
|
|
Runtime Adapters
|
|
├─ CrewAI Adapter
|
|
├─ mini-SWE-agent Adapter
|
|
├─ OpenHands Adapter
|
|
├─ LangGraph Adapter
|
|
├─ PR-Agent Adapter
|
|
├─ Script Adapter
|
|
└─ HTTP Adapter
|
|
|
|
Connectors
|
|
├─ GitHub
|
|
├─ GitLab
|
|
├─ Jira
|
|
├─ Slack
|
|
├─ Webhook
|
|
└─ Generic HTTP
|
|
|
|
Platform Services
|
|
├─ Policy Engine
|
|
├─ Secret Manager
|
|
├─ Sandbox Manager
|
|
├─ Model Gateway
|
|
├─ Artifact Store
|
|
├─ Event Store
|
|
├─ Audit Log
|
|
└─ Observability
|
|
```
|
|
|
|
---
|
|
|
|
# 10. Recommended Initial Technology Stack
|
|
|
|
## 10.1 MVP Stack
|
|
|
|
```yaml
|
|
frontend:
|
|
framework: Next.js
|
|
language: TypeScript
|
|
ui: Tailwind + shadcn/ui
|
|
data_fetching: TanStack Query
|
|
realtime: Server-Sent Events or WebSocket
|
|
editor: Monaco Editor
|
|
|
|
backend:
|
|
framework: FastAPI
|
|
language: Python
|
|
api_style: REST first
|
|
realtime: SSE first
|
|
validation: Pydantic
|
|
|
|
database:
|
|
primary: PostgreSQL
|
|
|
|
queue:
|
|
initial: Redis + RQ or Celery
|
|
later: Temporal, Hatchet, or durable workflow engine
|
|
|
|
object_storage:
|
|
initial: local filesystem or MinIO
|
|
production: S3-compatible storage
|
|
|
|
runner:
|
|
initial: Docker
|
|
later: Kubernetes Jobs, Firecracker, gVisor
|
|
|
|
auth:
|
|
initial: local admin user
|
|
later: OIDC, OAuth, SAML
|
|
|
|
deployment:
|
|
initial: Docker Compose
|
|
later: Kubernetes Helm chart
|
|
```
|
|
|
|
## 10.2 Reasoning
|
|
|
|
FastAPI is a good fit because many agent frameworks are Python-native. Next.js gives a strong UI foundation. Docker-based runners keep the MVP simple. PostgreSQL provides reliable state. Redis is sufficient for early background work.
|
|
|
|
---
|
|
|
|
# 11. Deployment Model
|
|
|
|
## 11.1 Local Development
|
|
|
|
```text
|
|
agenthub-web
|
|
agenthub-api
|
|
agenthub-worker
|
|
postgres
|
|
redis
|
|
minio
|
|
docker-socket-proxy
|
|
```
|
|
|
|
The Docker socket should not be directly exposed to agent containers. If Docker control is needed, use a restricted proxy or a separate runner service.
|
|
|
|
## 11.2 Single-Server Self-Hosted
|
|
|
|
A Docker Compose stack should be enough for an early production deployment.
|
|
|
|
Required services:
|
|
|
|
```text
|
|
web
|
|
api
|
|
worker
|
|
postgres
|
|
redis
|
|
minio
|
|
reverse-proxy
|
|
runner
|
|
```
|
|
|
|
## 11.3 Kubernetes
|
|
|
|
Future production deployments should support:
|
|
|
|
```text
|
|
web deployment
|
|
api deployment
|
|
worker deployment
|
|
runner job pods
|
|
postgres
|
|
redis
|
|
object storage
|
|
ingress
|
|
secret manager
|
|
network policies
|
|
observability stack
|
|
```
|
|
|
|
## 11.4 Air-Gapped Mode
|
|
|
|
Future air-gapped support should allow:
|
|
|
|
* Local Git provider
|
|
* Local model server
|
|
* Local package mirrors
|
|
* Internal artifact storage
|
|
* No external network requirement
|
|
* Local-only connector configuration
|
|
* Offline documentation cache
|
|
|
|
---
|
|
|
|
# 12. User Interface
|
|
|
|
## 12.1 Main Navigation
|
|
|
|
```text
|
|
Dashboard
|
|
Workflows
|
|
Runs
|
|
Agents
|
|
Agent Teams
|
|
Models
|
|
Connectors
|
|
Triggers
|
|
Monitors
|
|
Tools
|
|
Sandboxes
|
|
Approvals
|
|
Artifacts
|
|
Policies
|
|
Secrets
|
|
Audit Log
|
|
Settings
|
|
```
|
|
|
|
## 12.2 Dashboard
|
|
|
|
The dashboard should show:
|
|
|
|
* Active workflow runs
|
|
* Waiting approvals
|
|
* Failed runs
|
|
* Recently completed runs
|
|
* Agent runs by status
|
|
* Cost estimates
|
|
* Token usage
|
|
* External trigger activity
|
|
* Connector health
|
|
* Sandbox capacity
|
|
* Recent audit events
|
|
|
|
## 12.3 Workflow List
|
|
|
|
Shows:
|
|
|
|
* Workflow name
|
|
* Version
|
|
* Enabled status
|
|
* Trigger type
|
|
* Last run
|
|
* Success rate
|
|
* Average duration
|
|
* Owner
|
|
* Assigned connectors
|
|
* Actions
|
|
|
|
Actions:
|
|
|
|
* Create workflow
|
|
* Duplicate workflow
|
|
* Enable/disable workflow
|
|
* Run manually
|
|
* View runs
|
|
* Edit YAML
|
|
* View graph
|
|
|
|
## 12.4 Workflow Detail
|
|
|
|
Tabs:
|
|
|
|
```text
|
|
Overview
|
|
Definition
|
|
Visual Graph
|
|
Runs
|
|
Triggers
|
|
Monitors
|
|
Policies
|
|
Versions
|
|
Settings
|
|
```
|
|
|
|
The first version may rely on YAML editing. A visual graph editor can come later.
|
|
|
|
## 12.5 Run Detail
|
|
|
|
A run detail page should show:
|
|
|
|
* Workflow name and version
|
|
* Trigger source
|
|
* Input payload
|
|
* Current stage
|
|
* Stage timeline
|
|
* Active agent runs
|
|
* Logs
|
|
* Artifacts
|
|
* Approval gates
|
|
* Policy decisions
|
|
* Errors
|
|
* Final result
|
|
|
|
Required actions:
|
|
|
|
* Cancel run
|
|
* Retry failed stage
|
|
* Resume from stage
|
|
* Approve gate
|
|
* Reject gate
|
|
* Add human comment
|
|
* Download artifacts
|
|
|
|
## 12.6 Agent Registry UI
|
|
|
|
Shows:
|
|
|
|
* Agent name
|
|
* Role
|
|
* Runtime
|
|
* Default model
|
|
* Tools
|
|
* Permissions
|
|
* Success rate
|
|
* Recent runs
|
|
* Enabled status
|
|
|
|
Actions:
|
|
|
|
* Create agent
|
|
* Edit agent
|
|
* Test agent
|
|
* Disable agent
|
|
* Duplicate agent
|
|
* View run history
|
|
|
|
## 12.7 Agent Team UI
|
|
|
|
Shows:
|
|
|
|
* Team name
|
|
* Team pattern
|
|
* Members
|
|
* Supervisor or manager
|
|
* Runtime mapping
|
|
* Model routing
|
|
* Recent team runs
|
|
|
|
Team types:
|
|
|
|
```text
|
|
sequential
|
|
parallel
|
|
hierarchical
|
|
supervisor_worker
|
|
debate_judge
|
|
router_specialist
|
|
custom_runtime
|
|
```
|
|
|
|
## 12.8 Model Registry UI
|
|
|
|
Shows:
|
|
|
|
* Provider
|
|
* Model name
|
|
* Endpoint
|
|
* Context limit
|
|
* Cost settings
|
|
* Allowed agents
|
|
* Allowed workflows
|
|
* Health status
|
|
* Token usage
|
|
* Cost history
|
|
|
|
## 12.9 Connector UI
|
|
|
|
Shows:
|
|
|
|
* Connector type
|
|
* Authentication status
|
|
* Webhook status
|
|
* Resources discovered
|
|
* Last event received
|
|
* Last successful action
|
|
* Rate-limit state
|
|
* Error history
|
|
|
|
## 12.10 Approval Inbox
|
|
|
|
Shows all pending approvals:
|
|
|
|
* Workflow run
|
|
* Stage
|
|
* Requested action
|
|
* Risk summary
|
|
* Requesting agent
|
|
* Required role
|
|
* Deadline
|
|
* Approve/reject actions
|
|
|
|
---
|
|
|
|
# 13. Workflow System
|
|
|
|
## 13.1 Workflow Definition Format
|
|
|
|
Workflows should be stored as versioned YAML or JSON.
|
|
|
|
YAML is preferred for authoring.
|
|
|
|
Example:
|
|
|
|
```yaml
|
|
id: github-issue-to-pr
|
|
name: Git Issue to PR
|
|
version: 1
|
|
enabled: true
|
|
|
|
description: >
|
|
Turns a labeled GitHub issue into a spec, implementation branch, and draft PR.
|
|
|
|
triggers:
|
|
- id: issue-labeled
|
|
connector: github-main
|
|
event: issue.labeled
|
|
filter:
|
|
label: agent-ready
|
|
|
|
- id: issue-mentioned
|
|
connector: github-main
|
|
event: issue.commented
|
|
filter:
|
|
contains: "@agenthub"
|
|
|
|
inputs:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- repository
|
|
- issue_number
|
|
|
|
variables:
|
|
spec_required: true
|
|
create_draft_pr: true
|
|
|
|
stages:
|
|
- id: normalize
|
|
type: connector_action
|
|
action: github.load_issue_context
|
|
outputs:
|
|
issue_context: result
|
|
|
|
- id: triage
|
|
type: agent
|
|
agent: git-triage-agent
|
|
input:
|
|
issue: "{{ issue_context }}"
|
|
outputs:
|
|
triage: result
|
|
|
|
- id: generate_spec
|
|
type: agent_team
|
|
team: git-spec-team
|
|
input:
|
|
issue: "{{ issue_context }}"
|
|
triage: "{{ triage }}"
|
|
outputs:
|
|
spec_bundle: result
|
|
|
|
- id: approve_spec
|
|
type: approval
|
|
when: "{{ variables.spec_required == true }}"
|
|
title: "Approve generated spec"
|
|
required_roles:
|
|
- maintainer
|
|
input:
|
|
spec_bundle: "{{ spec_bundle }}"
|
|
|
|
- id: implement
|
|
type: agent
|
|
agent: mini-swe-implementation-agent
|
|
input:
|
|
issue: "{{ issue_context }}"
|
|
spec_bundle: "{{ spec_bundle }}"
|
|
outputs:
|
|
implementation_result: result
|
|
|
|
- id: open_pr
|
|
type: connector_action
|
|
connector: github-main
|
|
action: github.open_or_update_pull_request
|
|
input:
|
|
implementation: "{{ implementation_result }}"
|
|
draft: "{{ variables.create_draft_pr }}"
|
|
outputs:
|
|
pull_request: result
|
|
|
|
- id: wait_for_ci
|
|
type: wait_for_condition
|
|
connector: github-main
|
|
condition: github.pr_checks_completed
|
|
timeout_minutes: 60
|
|
input:
|
|
pull_request: "{{ pull_request }}"
|
|
outputs:
|
|
ci_result: result
|
|
|
|
- id: review
|
|
type: agent_team
|
|
team: pr-review-team
|
|
input:
|
|
pull_request: "{{ pull_request }}"
|
|
spec_bundle: "{{ spec_bundle }}"
|
|
ci_result: "{{ ci_result }}"
|
|
outputs:
|
|
review_result: result
|
|
|
|
- id: human_review
|
|
type: approval
|
|
title: "Approve PR readiness"
|
|
required_roles:
|
|
- maintainer
|
|
input:
|
|
pull_request: "{{ pull_request }}"
|
|
review_result: "{{ review_result }}"
|
|
|
|
- id: complete
|
|
type: terminal
|
|
status: success
|
|
|
|
failure:
|
|
default:
|
|
action: mark_failed
|
|
notify:
|
|
- workflow_owner
|
|
```
|
|
|
|
## 13.2 Stage Types
|
|
|
|
### agent
|
|
|
|
Runs a single configured agent.
|
|
|
|
### agent_team
|
|
|
|
Runs a configured team of agents. This may map to CrewAI, LangGraph, or a custom runtime.
|
|
|
|
### connector_action
|
|
|
|
Calls an external system.
|
|
|
|
Examples:
|
|
|
|
* create GitHub comment
|
|
* update Jira issue
|
|
* send Slack message
|
|
* create branch
|
|
* open pull request
|
|
* query database
|
|
|
|
### script
|
|
|
|
Runs a controlled script.
|
|
|
|
### approval
|
|
|
|
Pauses execution until a human approves or rejects.
|
|
|
|
### wait_for_event
|
|
|
|
Waits for a matching event.
|
|
|
|
### wait_for_condition
|
|
|
|
Polls or subscribes until a condition is true.
|
|
|
|
### condition
|
|
|
|
Branches based on an expression.
|
|
|
|
### parallel
|
|
|
|
Runs multiple stages concurrently.
|
|
|
|
### subworkflow
|
|
|
|
Calls another workflow.
|
|
|
|
### notification
|
|
|
|
Sends a notification.
|
|
|
|
### terminal
|
|
|
|
Ends workflow.
|
|
|
|
## 13.3 Workflow State Machine
|
|
|
|
Workflow runs should support these states:
|
|
|
|
```text
|
|
created
|
|
queued
|
|
running
|
|
waiting
|
|
waiting_for_approval
|
|
waiting_for_event
|
|
waiting_for_condition
|
|
paused
|
|
succeeded
|
|
failed
|
|
cancelled
|
|
timed_out
|
|
```
|
|
|
|
Stage runs should support:
|
|
|
|
```text
|
|
pending
|
|
queued
|
|
running
|
|
waiting
|
|
succeeded
|
|
failed
|
|
skipped
|
|
cancelled
|
|
timed_out
|
|
blocked_by_policy
|
|
```
|
|
|
|
## 13.4 Workflow Versioning
|
|
|
|
Every workflow edit creates a new version.
|
|
|
|
A workflow run must always reference the exact workflow version used.
|
|
|
|
Required fields:
|
|
|
|
```text
|
|
workflow_id
|
|
workflow_version
|
|
definition_snapshot
|
|
started_at
|
|
started_by
|
|
trigger_event_id
|
|
```
|
|
|
|
## 13.5 Retry Behavior
|
|
|
|
Workflow definitions should support:
|
|
|
|
```yaml
|
|
retry:
|
|
max_attempts: 2
|
|
backoff_seconds: 60
|
|
retry_on:
|
|
- model_error
|
|
- connector_timeout
|
|
- sandbox_error
|
|
```
|
|
|
|
## 13.6 Failure Behavior
|
|
|
|
A stage may define failure behavior:
|
|
|
|
```yaml
|
|
on_failure:
|
|
action: retry | continue | branch | fail | request_human_input
|
|
target_stage: revise_plan
|
|
```
|
|
|
|
## 13.7 Human Input
|
|
|
|
Some stages should allow a human to provide additional instructions.
|
|
|
|
Example:
|
|
|
|
```yaml
|
|
- id: clarify_requirements
|
|
type: human_input
|
|
prompt: "The agent needs clarification before proceeding."
|
|
required_roles:
|
|
- maintainer
|
|
```
|
|
|
|
---
|
|
|
|
# 14. Trigger System
|
|
|
|
## 14.1 Trigger Types
|
|
|
|
AgentHub should support:
|
|
|
|
```text
|
|
manual
|
|
webhook_event
|
|
connector_event
|
|
schedule
|
|
monitor_condition
|
|
api_call
|
|
workflow_event
|
|
```
|
|
|
|
## 14.2 Trigger Definition
|
|
|
|
Example:
|
|
|
|
```yaml
|
|
id: github-label-trigger
|
|
name: GitHub Issue Label Trigger
|
|
type: connector_event
|
|
connector: github-main
|
|
event: issue.labeled
|
|
enabled: true
|
|
filter:
|
|
repository: "org/repo"
|
|
label: "agent-ready"
|
|
workflow: github-issue-to-pr
|
|
```
|
|
|
|
## 14.3 Trigger Filtering
|
|
|
|
Filters should support:
|
|
|
|
* Exact match
|
|
* Contains
|
|
* Regex
|
|
* JSON path
|
|
* CEL-like expressions later
|
|
* Repository scoping
|
|
* Actor scoping
|
|
* Label scoping
|
|
* Event type scoping
|
|
|
|
Example:
|
|
|
|
```yaml
|
|
filter:
|
|
all:
|
|
- path: "$.issue.state"
|
|
equals: "open"
|
|
- path: "$.label.name"
|
|
equals: "agent-ready"
|
|
- path: "$.sender.login"
|
|
not_in:
|
|
- dependabot
|
|
```
|
|
|
|
## 14.4 Trigger Deduplication
|
|
|
|
Triggers must deduplicate events to avoid duplicate runs.
|
|
|
|
Deduplication key examples:
|
|
|
|
```text
|
|
connector_id:event_id
|
|
github:delivery_id
|
|
repository:issue:label:workflow
|
|
```
|
|
|
|
## 14.5 Trigger Authorization
|
|
|
|
A trigger must check:
|
|
|
|
* Connector is enabled
|
|
* Workflow is enabled
|
|
* Actor is authorized, if applicable
|
|
* Policy permits run creation
|
|
* Rate limits are not exceeded
|
|
* Duplicate run does not already exist
|
|
|
|
---
|
|
|
|
# 15. Monitor System
|
|
|
|
## 15.1 Monitor Purpose
|
|
|
|
A monitor observes external state and creates events or advances workflow state.
|
|
|
|
Unlike triggers, monitors may poll on an interval or maintain subscriptions.
|
|
|
|
## 15.2 Monitor Examples
|
|
|
|
```yaml
|
|
id: monitor-pr-ci
|
|
name: Monitor PR CI Status
|
|
type: connector_poll
|
|
connector: github-main
|
|
interval_seconds: 60
|
|
query:
|
|
repository: org/repo
|
|
pull_request_label: agent-generated
|
|
condition:
|
|
checks_completed: true
|
|
workflow_event:
|
|
type: github.pr_checks_completed
|
|
```
|
|
|
|
Other examples:
|
|
|
|
```text
|
|
Watch stale tickets
|
|
Watch external HTTP endpoint
|
|
Watch failed deployment
|
|
Watch unresolved PR comments
|
|
Watch security advisories
|
|
Watch mailbox for specific emails
|
|
Watch queue backlog
|
|
```
|
|
|
|
## 15.3 Monitor States
|
|
|
|
```text
|
|
enabled
|
|
disabled
|
|
healthy
|
|
degraded
|
|
failing
|
|
paused
|
|
```
|
|
|
|
## 15.4 Monitor Outputs
|
|
|
|
Monitors produce normalized internal events.
|
|
|
|
Example:
|
|
|
|
```json
|
|
{
|
|
"type": "monitor.condition_met",
|
|
"source": "github-pr-ci-monitor",
|
|
"resource": {
|
|
"repository": "org/repo",
|
|
"pull_request": 42
|
|
},
|
|
"payload": {
|
|
"checks_status": "success"
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
# 16. Agent System
|
|
|
|
## 16.1 Agent Definition
|
|
|
|
Example:
|
|
|
|
```yaml
|
|
id: git-triage-agent
|
|
name: Git Triage Agent
|
|
description: Classifies Git issues and decides whether they are suitable for automation.
|
|
type: single_agent
|
|
runtime: llm_prompt
|
|
enabled: true
|
|
|
|
model:
|
|
routing_policy: cheap-reasoning
|
|
fallback_policy: default-fallback
|
|
|
|
prompt:
|
|
system_template: git-triage-system
|
|
task_template: git-triage-task
|
|
|
|
tools:
|
|
- code_search.readonly
|
|
- github.readonly
|
|
|
|
permissions:
|
|
external_actions: false
|
|
filesystem_write: false
|
|
network_access: false
|
|
|
|
output_schema:
|
|
type: object
|
|
required:
|
|
- suitable
|
|
- complexity
|
|
- reason
|
|
properties:
|
|
suitable:
|
|
type: boolean
|
|
complexity:
|
|
type: string
|
|
enum:
|
|
- low
|
|
- medium
|
|
- high
|
|
reason:
|
|
type: string
|
|
```
|
|
|
|
## 16.2 Agent Types
|
|
|
|
```text
|
|
single_agent
|
|
agent_team
|
|
runtime_native_agent
|
|
script_agent
|
|
http_agent
|
|
human_agent
|
|
```
|
|
|
|
## 16.3 Agent Role Categories
|
|
|
|
```text
|
|
triage
|
|
planner
|
|
spec_writer
|
|
researcher
|
|
coder
|
|
reviewer
|
|
tester
|
|
security_reviewer
|
|
documentation_writer
|
|
operator
|
|
manager
|
|
judge
|
|
router
|
|
```
|
|
|
|
## 16.4 Agent Output
|
|
|
|
Every agent run should return structured output.
|
|
|
|
Required fields:
|
|
|
|
```yaml
|
|
status: success | failed | needs_input | blocked
|
|
summary: string
|
|
outputs: object
|
|
artifacts: []
|
|
recommendations: []
|
|
errors: []
|
|
```
|
|
|
|
## 16.5 Agent Run States
|
|
|
|
```text
|
|
created
|
|
queued
|
|
preparing
|
|
running
|
|
streaming
|
|
succeeded
|
|
failed
|
|
needs_input
|
|
blocked_by_policy
|
|
cancelled
|
|
timed_out
|
|
```
|
|
|
|
---
|
|
|
|
# 17. Agent Team and Hierarchy System
|
|
|
|
## 17.1 Team Definition
|
|
|
|
Example:
|
|
|
|
```yaml
|
|
id: git-spec-team
|
|
name: Git Spec Team
|
|
type: hierarchical
|
|
runtime: crewai
|
|
|
|
manager:
|
|
agent: engineering-manager-agent
|
|
model: strong-reasoning
|
|
|
|
members:
|
|
- agent: product-spec-agent
|
|
role: requirements
|
|
model: strong-writing
|
|
- agent: architecture-agent
|
|
role: architecture
|
|
model: strong-reasoning
|
|
- agent: test-planner-agent
|
|
role: testing
|
|
model: code-reasoning
|
|
- agent: security-review-agent
|
|
role: risk
|
|
model: security-reasoning
|
|
|
|
process:
|
|
type: hierarchical
|
|
max_rounds: 5
|
|
|
|
outputs:
|
|
schema: spec_bundle
|
|
```
|
|
|
|
## 17.2 Supported Team Patterns
|
|
|
|
### Sequential
|
|
|
|
Agents run in order.
|
|
|
|
```text
|
|
researcher → planner → writer → reviewer
|
|
```
|
|
|
|
### Parallel
|
|
|
|
Agents run independently and results are combined.
|
|
|
|
```text
|
|
security reviewer
|
|
architecture reviewer
|
|
test reviewer
|
|
↓
|
|
aggregator
|
|
```
|
|
|
|
### Hierarchical
|
|
|
|
A manager delegates tasks to workers.
|
|
|
|
```text
|
|
manager
|
|
├─ planner
|
|
├─ researcher
|
|
├─ coder
|
|
└─ reviewer
|
|
```
|
|
|
|
### Debate and Judge
|
|
|
|
Multiple agents propose or critique, then a judge decides.
|
|
|
|
```text
|
|
agent A proposal
|
|
agent B critique
|
|
agent C alternative
|
|
↓
|
|
judge
|
|
```
|
|
|
|
### Router Specialist
|
|
|
|
A router picks the best specialist.
|
|
|
|
```text
|
|
router
|
|
├─ docs agent
|
|
├─ code agent
|
|
├─ test agent
|
|
└─ security agent
|
|
```
|
|
|
|
### Supervisor Worker
|
|
|
|
A supervisor monitors one or more long-running workers.
|
|
|
|
```text
|
|
supervisor
|
|
└─ implementation worker
|
|
```
|
|
|
|
## 17.3 Team Runtime Mapping
|
|
|
|
AgentHub should define team hierarchy independently from runtime.
|
|
|
|
Then adapters map it to concrete runtimes.
|
|
|
|
Example mappings:
|
|
|
|
```text
|
|
AgentHub hierarchical team → CrewAI hierarchical process
|
|
AgentHub graph team → LangGraph
|
|
AgentHub coding worker → mini-SWE-agent
|
|
AgentHub review board → CrewAI or custom parallel runner
|
|
```
|
|
|
|
## 17.4 Manager Agent
|
|
|
|
A manager agent may:
|
|
|
|
* Decompose tasks
|
|
* Assign subtasks
|
|
* Review outputs
|
|
* Request revisions
|
|
* Stop execution
|
|
* Escalate to human
|
|
* Select models
|
|
* Select tools
|
|
* Produce final output
|
|
|
|
Manager actions must still be constrained by platform policy.
|
|
|
|
## 17.5 Model Routing Within Teams
|
|
|
|
Each team member may use a different model.
|
|
|
|
Example:
|
|
|
|
```yaml
|
|
members:
|
|
- agent: router
|
|
model: cheap-fast
|
|
- agent: planner
|
|
model: strong-reasoning
|
|
- agent: coder
|
|
model: code-specialist
|
|
- agent: reviewer
|
|
model: strong-reasoning
|
|
```
|
|
|
|
---
|
|
|
|
# 18. Runtime Adapter System
|
|
|
|
## 18.1 Adapter Purpose
|
|
|
|
Runtime adapters allow AgentHub to invoke different execution systems through a common interface.
|
|
|
|
## 18.2 Adapter Interface
|
|
|
|
TypeScript-style interface:
|
|
|
|
```typescript
|
|
interface RuntimeAdapter {
|
|
id: string;
|
|
name: string;
|
|
|
|
validateDefinition(definition: RuntimeDefinition): Promise<ValidationResult>;
|
|
|
|
prepare(input: RuntimeRunInput): Promise<PreparedRun>;
|
|
|
|
start(input: RuntimeRunInput): Promise<RuntimeRunHandle>;
|
|
|
|
streamEvents(runId: string): AsyncIterable<RuntimeEvent>;
|
|
|
|
cancel(runId: string): Promise<void>;
|
|
|
|
collectResult(runId: string): Promise<RuntimeRunResult>;
|
|
|
|
cleanup(runId: string): Promise<void>;
|
|
}
|
|
```
|
|
|
|
## 18.3 RuntimeRunInput
|
|
|
|
```yaml
|
|
run_id: string
|
|
workflow_run_id: string
|
|
stage_run_id: string
|
|
runtime: string
|
|
agent_or_team_definition: object
|
|
input: object
|
|
context:
|
|
variables: object
|
|
artifacts: []
|
|
secrets: []
|
|
connector_refs: []
|
|
policy: object
|
|
limits:
|
|
timeout_seconds: 3600
|
|
max_cost_usd: 10
|
|
max_tokens: 100000
|
|
sandbox:
|
|
type: docker
|
|
image: agenthub/runner:latest
|
|
```
|
|
|
|
## 18.4 RuntimeRunResult
|
|
|
|
```yaml
|
|
status: success | failed | cancelled | timed_out | needs_input
|
|
summary: string
|
|
outputs: object
|
|
artifacts:
|
|
- id: string
|
|
type: string
|
|
uri: string
|
|
events: []
|
|
cost:
|
|
input_tokens: number
|
|
output_tokens: number
|
|
estimated_usd: number
|
|
errors:
|
|
- code: string
|
|
message: string
|
|
```
|
|
|
|
## 18.5 Initial Adapters
|
|
|
|
### llm_prompt adapter
|
|
|
|
A simple single-prompt agent runner.
|
|
|
|
Use for:
|
|
|
|
* classification
|
|
* summarization
|
|
* spec generation MVP
|
|
* lightweight decisions
|
|
|
|
### script adapter
|
|
|
|
Runs a configured command in a sandbox.
|
|
|
|
Use for:
|
|
|
|
* simple deterministic tasks
|
|
* local scripts
|
|
* custom tools
|
|
* testing adapter interface
|
|
|
|
### docker adapter
|
|
|
|
Runs arbitrary containerized agent.
|
|
|
|
Use for:
|
|
|
|
* custom agents
|
|
* isolated workloads
|
|
* non-Python systems
|
|
|
|
### CrewAI adapter
|
|
|
|
Runs a CrewAI crew or flow.
|
|
|
|
Use for:
|
|
|
|
* hierarchical teams
|
|
* planning teams
|
|
* review teams
|
|
* multi-agent debate
|
|
|
|
### mini-SWE-agent adapter
|
|
|
|
Runs mini-SWE-agent against a repository workspace.
|
|
|
|
Use for:
|
|
|
|
* issue-to-code implementation
|
|
* bug fixing
|
|
* test fixing
|
|
* small feature implementation
|
|
|
|
### PR-Agent adapter
|
|
|
|
Runs PR review automation.
|
|
|
|
Use for:
|
|
|
|
* PR summaries
|
|
* PR review suggestions
|
|
* code review support
|
|
|
|
---
|
|
|
|
# 19. CrewAI Adapter
|
|
|
|
## 19.1 Purpose
|
|
|
|
The CrewAI adapter allows AgentHub to run CrewAI-based crews and flows as workflow stages.
|
|
|
|
CrewAI should be a supported runtime, not the platform core.
|
|
|
|
## 19.2 Supported Use Cases
|
|
|
|
CrewAI is useful for:
|
|
|
|
* hierarchical planning
|
|
* requirements analysis
|
|
* spec generation
|
|
* review boards
|
|
* risk analysis
|
|
* research tasks
|
|
* multi-perspective critique
|
|
* manager-worker task decomposition
|
|
|
|
CrewAI is less ideal as the only platform-level orchestrator because AgentHub must own:
|
|
|
|
* triggers
|
|
* monitors
|
|
* approvals
|
|
* audit logs
|
|
* cross-runtime workflows
|
|
* connector governance
|
|
* sandbox governance
|
|
* workflow versioning
|
|
* long-running run visibility
|
|
|
|
## 19.3 CrewAI Stage Example
|
|
|
|
```yaml
|
|
- id: generate_spec
|
|
type: agent_team
|
|
runtime: crewai
|
|
team: git-spec-team
|
|
input:
|
|
issue_context: "{{ issue_context }}"
|
|
repository_context: "{{ repository_context }}"
|
|
outputs:
|
|
spec_bundle: result
|
|
```
|
|
|
|
## 19.4 CrewAI Team Definition Example
|
|
|
|
```yaml
|
|
id: git-spec-team
|
|
runtime: crewai
|
|
|
|
crew:
|
|
process: hierarchical
|
|
manager_agent: engineering-manager
|
|
max_iterations: 10
|
|
|
|
agents:
|
|
engineering-manager:
|
|
role: Engineering Manager
|
|
goal: Coordinate the team and produce a final implementation-ready spec.
|
|
model: strong-reasoning
|
|
|
|
product-analyst:
|
|
role: Product Analyst
|
|
goal: Extract requirements, non-goals, acceptance criteria, and open questions.
|
|
model: strong-writing
|
|
|
|
architect:
|
|
role: Software Architect
|
|
goal: Identify code architecture impact, integration points, and risks.
|
|
model: strong-reasoning
|
|
|
|
test-planner:
|
|
role: Test Planner
|
|
goal: Define test strategy and validation steps.
|
|
model: code-reasoning
|
|
|
|
tasks:
|
|
- id: analyze_issue
|
|
agent: product-analyst
|
|
description: Analyze issue and conversation.
|
|
- id: assess_architecture
|
|
agent: architect
|
|
description: Assess implementation implications.
|
|
- id: create_test_plan
|
|
agent: test-planner
|
|
description: Create test plan.
|
|
- id: finalize_spec
|
|
agent: engineering-manager
|
|
description: Produce final spec bundle.
|
|
```
|
|
|
|
## 19.5 CrewAI Outputs
|
|
|
|
CrewAI stages must produce structured outputs.
|
|
|
|
Example:
|
|
|
|
```yaml
|
|
spec_bundle:
|
|
problem: string
|
|
goals: []
|
|
non_goals: []
|
|
requirements: []
|
|
acceptance_criteria: []
|
|
implementation_plan: []
|
|
test_plan: []
|
|
risks: []
|
|
open_questions: []
|
|
```
|
|
|
|
---
|
|
|
|
# 20. Model Registry and Routing
|
|
|
|
## 20.1 Model Provider Definition
|
|
|
|
```yaml
|
|
id: openai-main
|
|
type: openai
|
|
name: OpenAI Main
|
|
base_url: null
|
|
api_key_secret: openai_api_key
|
|
enabled: true
|
|
```
|
|
|
|
OpenAI-compatible local endpoint:
|
|
|
|
```yaml
|
|
id: local-vllm
|
|
type: openai_compatible
|
|
name: Local vLLM
|
|
base_url: http://vllm:8000/v1
|
|
api_key_secret: null
|
|
enabled: true
|
|
```
|
|
|
|
Ollama:
|
|
|
|
```yaml
|
|
id: ollama-local
|
|
type: ollama
|
|
name: Local Ollama
|
|
base_url: http://ollama:11434
|
|
enabled: true
|
|
```
|
|
|
|
## 20.2 Model Definition
|
|
|
|
```yaml
|
|
id: strong-reasoning
|
|
provider: openai-main
|
|
model_name: gpt-5.1
|
|
context_window: 200000
|
|
input_cost_per_1m_tokens: 0
|
|
output_cost_per_1m_tokens: 0
|
|
enabled: true
|
|
|
|
capabilities:
|
|
- reasoning
|
|
- tool_calling
|
|
- structured_output
|
|
|
|
limits:
|
|
max_tokens_per_run: 100000
|
|
max_cost_per_run_usd: 10
|
|
```
|
|
|
|
## 20.3 Model Routing Policy
|
|
|
|
```yaml
|
|
id: default-model-routing
|
|
rules:
|
|
- match:
|
|
task_type: triage
|
|
model: cheap-fast
|
|
|
|
- match:
|
|
task_type: implementation
|
|
model: code-specialist
|
|
|
|
- match:
|
|
risk: high
|
|
model: strong-reasoning
|
|
|
|
- match:
|
|
requires_structured_output: true
|
|
model: structured-output-model
|
|
|
|
fallback:
|
|
model: strong-reasoning
|
|
```
|
|
|
|
## 20.4 Model Selection Inputs
|
|
|
|
Model routing may use:
|
|
|
|
* Agent role
|
|
* Task type
|
|
* Risk level
|
|
* Repository sensitivity
|
|
* Expected cost
|
|
* Required context window
|
|
* Required tool support
|
|
* Required structured output
|
|
* User preference
|
|
* Workflow policy
|
|
|
|
---
|
|
|
|
# 21. Tool Registry
|
|
|
|
## 21.1 Tool Definition
|
|
|
|
```yaml
|
|
id: github.create_comment
|
|
name: Create GitHub Comment
|
|
connector: github-main
|
|
type: connector_action
|
|
description: Posts a comment to a GitHub issue or pull request.
|
|
|
|
input_schema:
|
|
type: object
|
|
required:
|
|
- repository
|
|
- issue_number
|
|
- body
|
|
|
|
permissions:
|
|
required:
|
|
- github:issues:write
|
|
|
|
risk:
|
|
level: medium
|
|
requires_approval: false
|
|
```
|
|
|
|
## 21.2 Tool Categories
|
|
|
|
```text
|
|
filesystem
|
|
shell
|
|
git
|
|
http
|
|
browser
|
|
database
|
|
connector_action
|
|
vector_search
|
|
code_search
|
|
notification
|
|
artifact
|
|
human_input
|
|
```
|
|
|
|
## 21.3 Tool Permissions
|
|
|
|
Tools must be explicitly granted to agents or teams.
|
|
|
|
Example:
|
|
|
|
```yaml
|
|
agent: git-triage-agent
|
|
tools:
|
|
- github.read_issue
|
|
- github.list_comments
|
|
- code_search.readonly
|
|
```
|
|
|
|
Implementation agent:
|
|
|
|
```yaml
|
|
agent: mini-swe-implementation-agent
|
|
tools:
|
|
- filesystem.read
|
|
- filesystem.write
|
|
- shell.run
|
|
- git.commit
|
|
- git.push
|
|
```
|
|
|
|
## 21.4 Tool Risk Levels
|
|
|
|
```text
|
|
low
|
|
medium
|
|
high
|
|
critical
|
|
```
|
|
|
|
Examples:
|
|
|
|
```text
|
|
read issue: low
|
|
post comment: medium
|
|
write file: medium
|
|
push branch: high
|
|
merge PR: critical
|
|
access secret: critical
|
|
deploy production: critical
|
|
```
|
|
|
|
---
|
|
|
|
# 22. Connector System
|
|
|
|
## 22.1 Connector Interface
|
|
|
|
```typescript
|
|
interface Connector {
|
|
id: string;
|
|
type: string;
|
|
|
|
testConnection(): Promise<ConnectorHealth>;
|
|
|
|
listResources(input: object): Promise<Resource[]>;
|
|
|
|
handleWebhook(request: WebhookRequest): Promise<NormalizedEvent[]>;
|
|
|
|
poll?(monitorDefinition: MonitorDefinition): Promise<NormalizedEvent[]>;
|
|
|
|
execute(action: string, input: object): Promise<ConnectorActionResult>;
|
|
}
|
|
```
|
|
|
|
## 22.2 Normalized Event
|
|
|
|
```json
|
|
{
|
|
"id": "evt_123",
|
|
"type": "github.issue.labeled",
|
|
"connector_id": "github-main",
|
|
"external_id": "delivery-id",
|
|
"actor": {
|
|
"type": "user",
|
|
"id": "alice"
|
|
},
|
|
"resource": {
|
|
"type": "github_issue",
|
|
"id": "org/repo#123"
|
|
},
|
|
"payload": {},
|
|
"received_at": "2026-05-29T12:00:00Z"
|
|
}
|
|
```
|
|
|
|
## 22.3 Initial Connectors
|
|
|
|
### GitHub Connector
|
|
|
|
Required for MVP.
|
|
|
|
Actions:
|
|
|
|
* list repositories
|
|
* read issue
|
|
* list issue comments
|
|
* post issue comment
|
|
* create branch
|
|
* push commit or support git credential generation
|
|
* open pull request
|
|
* update pull request
|
|
* read PR
|
|
* list review comments
|
|
* read CI/check status
|
|
* add/remove labels
|
|
|
|
Events:
|
|
|
|
* issue opened
|
|
* issue edited
|
|
* issue labeled
|
|
* issue commented
|
|
* pull request opened
|
|
* pull request synchronized
|
|
* pull request review submitted
|
|
* check suite completed
|
|
|
|
### Generic Webhook Connector
|
|
|
|
Required for generality.
|
|
|
|
Allows arbitrary systems to trigger workflows.
|
|
|
|
### HTTP Connector
|
|
|
|
Allows workflows to call external APIs.
|
|
|
|
### Slack or Matrix Connector
|
|
|
|
Useful after MVP for notifications and commands.
|
|
|
|
---
|
|
|
|
# 23. Policy Engine
|
|
|
|
## 23.1 Policy Purpose
|
|
|
|
The policy engine decides whether an action is allowed, denied, or requires approval.
|
|
|
|
Policies protect against:
|
|
|
|
* unintended external writes
|
|
* secret leakage
|
|
* unsafe file modifications
|
|
* excessive cost
|
|
* excessive runtime
|
|
* unauthorized trigger usage
|
|
* dangerous tools
|
|
* high-risk model behavior
|
|
* automatic merging
|
|
* production-impacting actions
|
|
|
|
## 23.2 Policy Decision
|
|
|
|
```yaml
|
|
decision: allow | deny | require_approval
|
|
reason: string
|
|
matched_rules:
|
|
- rule_id: string
|
|
risk_level: low | medium | high | critical
|
|
required_approvals:
|
|
- role: maintainer
|
|
```
|
|
|
|
## 23.3 Policy Evaluation Points
|
|
|
|
Evaluate policy before:
|
|
|
|
* Starting workflow
|
|
* Starting stage
|
|
* Invoking agent
|
|
* Selecting model
|
|
* Granting tool
|
|
* Accessing secret
|
|
* Writing file
|
|
* Running shell command
|
|
* Calling external action
|
|
* Posting external comment
|
|
* Opening PR
|
|
* Merging PR
|
|
* Sending notification
|
|
* Deploying
|
|
* Retrying with elevated permissions
|
|
|
|
## 23.4 Example Policy
|
|
|
|
```yaml
|
|
id: default-secure-policy
|
|
name: Default Secure Policy
|
|
|
|
rules:
|
|
- id: deny-secret-read
|
|
effect: deny
|
|
action: filesystem.read
|
|
paths:
|
|
- ".env"
|
|
- "**/*.pem"
|
|
- "**/*.key"
|
|
|
|
- id: block-ci-edits
|
|
effect: require_approval
|
|
action: filesystem.write
|
|
paths:
|
|
- ".github/workflows/**"
|
|
|
|
- id: block-agent-merge
|
|
effect: deny
|
|
action: github.pr.merge
|
|
|
|
- id: require-approval-for-external-message
|
|
effect: require_approval
|
|
action:
|
|
- slack.post_message
|
|
- email.send
|
|
condition:
|
|
risk_level: high
|
|
|
|
- id: max-cost-per-run
|
|
effect: deny
|
|
action: model.invoke
|
|
condition:
|
|
estimated_cost_usd_gt: 10
|
|
```
|
|
|
|
---
|
|
|
|
# 24. Approval System
|
|
|
|
## 24.1 Approval Types
|
|
|
|
```text
|
|
stage_approval
|
|
action_approval
|
|
policy_approval
|
|
spec_approval
|
|
merge_approval
|
|
secret_access_approval
|
|
cost_approval
|
|
human_input_request
|
|
```
|
|
|
|
## 24.2 Approval States
|
|
|
|
```text
|
|
requested
|
|
approved
|
|
rejected
|
|
expired
|
|
cancelled
|
|
superseded
|
|
```
|
|
|
|
## 24.3 Approval Request
|
|
|
|
```yaml
|
|
id: approval_123
|
|
workflow_run_id: run_123
|
|
stage_run_id: stage_456
|
|
type: spec_approval
|
|
title: Approve generated specification
|
|
description: The spec team generated a plan for issue #123.
|
|
risk_level: medium
|
|
requested_by: system
|
|
required_roles:
|
|
- maintainer
|
|
context:
|
|
artifact_ids:
|
|
- artifact_spec_123
|
|
expires_at: null
|
|
```
|
|
|
|
## 24.4 Approval UI Requirements
|
|
|
|
The approval screen should show:
|
|
|
|
* Requested action
|
|
* Why approval is needed
|
|
* Agent summary
|
|
* Risk level
|
|
* Relevant artifacts
|
|
* Policy rules matched
|
|
* Proposed external side effects
|
|
* Approve button
|
|
* Reject button
|
|
* Request changes button
|
|
* Comment field
|
|
|
|
---
|
|
|
|
# 25. Sandbox and Execution Security
|
|
|
|
## 25.1 Sandbox Requirements
|
|
|
|
Every agent run that executes code or tools should run in a sandbox.
|
|
|
|
Minimum requirements:
|
|
|
|
* Isolated filesystem
|
|
* CPU limit
|
|
* memory limit
|
|
* disk limit
|
|
* timeout
|
|
* no privileged container
|
|
* no host Docker socket
|
|
* controlled environment variables
|
|
* network disabled by default for high-risk workflows
|
|
* logs captured and redacted
|
|
* artifacts extracted safely
|
|
|
|
## 25.2 Sandbox Definition
|
|
|
|
```yaml
|
|
id: default-docker-sandbox
|
|
type: docker
|
|
image: agenthub/runner:latest
|
|
|
|
limits:
|
|
cpu: "4"
|
|
memory: "8Gi"
|
|
disk: "20Gi"
|
|
timeout_seconds: 3600
|
|
|
|
network:
|
|
enabled: false
|
|
allowlist: []
|
|
|
|
mounts:
|
|
workspace:
|
|
mode: read_write
|
|
|
|
security:
|
|
privileged: false
|
|
read_only_root: true
|
|
drop_capabilities: true
|
|
```
|
|
|
|
## 25.3 Secrets in Sandboxes
|
|
|
|
Secrets must be:
|
|
|
|
* opt-in
|
|
* scoped to workflow/stage/agent
|
|
* masked in logs
|
|
* injected only when needed
|
|
* unavailable to untrusted prompts by default
|
|
* never written into artifacts
|
|
* never exposed in external comments
|
|
|
|
---
|
|
|
|
# 26. Memory and Context
|
|
|
|
## 26.1 Context Types
|
|
|
|
AgentHub should distinguish:
|
|
|
|
```text
|
|
run context
|
|
workflow context
|
|
resource context
|
|
connector context
|
|
repository context
|
|
long-term memory
|
|
retrieved knowledge
|
|
human-provided context
|
|
```
|
|
|
|
## 26.2 Context Bundle
|
|
|
|
Each agent run receives a context bundle.
|
|
|
|
```yaml
|
|
context_bundle:
|
|
workflow:
|
|
id: string
|
|
run_id: string
|
|
stage_id: string
|
|
|
|
inputs: {}
|
|
|
|
previous_outputs: {}
|
|
|
|
artifacts: []
|
|
|
|
resource_context: {}
|
|
|
|
instructions:
|
|
system: string
|
|
task: string
|
|
|
|
constraints:
|
|
policies: []
|
|
allowed_tools: []
|
|
limits: {}
|
|
```
|
|
|
|
## 26.3 Memory Policy
|
|
|
|
Long-term memory should not be automatic in MVP.
|
|
|
|
Future memory should be:
|
|
|
|
* explicit
|
|
* inspectable
|
|
* erasable
|
|
* scoped
|
|
* permissioned
|
|
* source-cited
|
|
* freshness-aware
|
|
|
|
---
|
|
|
|
# 27. Artifact System
|
|
|
|
## 27.1 Artifact Types
|
|
|
|
```text
|
|
markdown
|
|
json
|
|
yaml
|
|
text
|
|
patch
|
|
diff
|
|
log
|
|
test_report
|
|
html
|
|
image
|
|
screenshot
|
|
pull_request
|
|
external_link
|
|
decision_record
|
|
model_trace
|
|
```
|
|
|
|
## 27.2 Artifact Metadata
|
|
|
|
```yaml
|
|
id: artifact_123
|
|
workflow_run_id: run_123
|
|
stage_run_id: stage_456
|
|
type: markdown
|
|
name: spec.md
|
|
uri: s3://agenthub/artifacts/spec.md
|
|
content_type: text/markdown
|
|
created_by: git-spec-team
|
|
created_at: timestamp
|
|
hash: string
|
|
```
|
|
|
|
## 27.3 Artifact Requirements
|
|
|
|
Artifacts should be:
|
|
|
|
* versioned where needed
|
|
* downloadable
|
|
* previewable in UI
|
|
* referenced by later stages
|
|
* available to approval screens
|
|
* immutable once finalized
|
|
* linked to audit events
|
|
|
|
---
|
|
|
|
# 28. Event and Audit System
|
|
|
|
## 28.1 Internal Events
|
|
|
|
AgentHub should append internal events for all important state changes.
|
|
|
|
Examples:
|
|
|
|
```text
|
|
workflow.created
|
|
workflow.started
|
|
workflow.stage.started
|
|
workflow.stage.completed
|
|
agent.run.started
|
|
agent.run.completed
|
|
approval.requested
|
|
approval.approved
|
|
policy.denied
|
|
connector.action.executed
|
|
artifact.created
|
|
sandbox.started
|
|
sandbox.stopped
|
|
```
|
|
|
|
## 28.2 Audit Events
|
|
|
|
Audit events are security-relevant and should be immutable.
|
|
|
|
Examples:
|
|
|
|
```text
|
|
user.login
|
|
connector.created
|
|
secret.created
|
|
policy.updated
|
|
workflow.enabled
|
|
agent.permissions.changed
|
|
external.comment.posted
|
|
pull_request.opened
|
|
approval.granted
|
|
merge.executed
|
|
```
|
|
|
|
## 28.3 Audit Log Requirements
|
|
|
|
Audit logs should include:
|
|
|
|
* actor
|
|
* action
|
|
* target
|
|
* result
|
|
* timestamp
|
|
* IP or service identity where applicable
|
|
* metadata
|
|
* policy decision
|
|
* correlation ID
|
|
|
|
---
|
|
|
|
# 29. Observability
|
|
|
|
## 29.1 Logs
|
|
|
|
Required logs:
|
|
|
|
* API logs
|
|
* workflow engine logs
|
|
* worker logs
|
|
* runtime adapter logs
|
|
* sandbox logs
|
|
* connector logs
|
|
* model invocation logs
|
|
* policy decision logs
|
|
* audit logs
|
|
|
|
## 29.2 Metrics
|
|
|
|
Suggested metrics:
|
|
|
|
```text
|
|
workflow_runs_total
|
|
workflow_runs_active
|
|
workflow_runs_failed_total
|
|
stage_runs_total
|
|
agent_runs_total
|
|
agent_runs_failed_total
|
|
agent_run_duration_seconds
|
|
model_input_tokens_total
|
|
model_output_tokens_total
|
|
model_cost_usd_total
|
|
connector_events_total
|
|
connector_action_errors_total
|
|
policy_denials_total
|
|
approvals_pending
|
|
sandbox_active_total
|
|
```
|
|
|
|
## 29.3 Tracing
|
|
|
|
Every workflow run should have a correlation ID.
|
|
|
|
The correlation ID should be propagated through:
|
|
|
|
* trigger processing
|
|
* workflow engine
|
|
* stage execution
|
|
* runtime adapter
|
|
* connector calls
|
|
* sandbox
|
|
* logs
|
|
* artifacts
|
|
|
|
---
|
|
|
|
# 30. Data Model
|
|
|
|
## 30.1 Users
|
|
|
|
```sql
|
|
users (
|
|
id uuid primary key,
|
|
email text unique not null,
|
|
name text,
|
|
role text not null,
|
|
created_at timestamptz not null,
|
|
updated_at timestamptz not null
|
|
)
|
|
```
|
|
|
|
## 30.2 Connectors
|
|
|
|
```sql
|
|
connectors (
|
|
id uuid primary key,
|
|
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
|
|
)
|
|
```
|
|
|
|
## 30.3 Triggers
|
|
|
|
```sql
|
|
triggers (
|
|
id uuid primary key,
|
|
name text not null,
|
|
type text not null,
|
|
enabled boolean not null default true,
|
|
connector_id uuid references connectors(id),
|
|
workflow_id uuid references workflows(id),
|
|
definition jsonb not null,
|
|
created_at timestamptz not null,
|
|
updated_at timestamptz not null
|
|
)
|
|
```
|
|
|
|
## 30.4 Monitors
|
|
|
|
```sql
|
|
monitors (
|
|
id uuid primary key,
|
|
name text not null,
|
|
type text not null,
|
|
enabled boolean not null default true,
|
|
connector_id uuid references connectors(id),
|
|
workflow_id uuid references workflows(id),
|
|
definition jsonb not null,
|
|
last_run_at timestamptz,
|
|
health_status text not null default 'unknown',
|
|
created_at timestamptz not null,
|
|
updated_at timestamptz not null
|
|
)
|
|
```
|
|
|
|
## 30.5 Workflows
|
|
|
|
```sql
|
|
workflows (
|
|
id uuid primary key,
|
|
name text not null,
|
|
slug text unique 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
|
|
)
|
|
```
|
|
|
|
## 30.6 Workflow Versions
|
|
|
|
```sql
|
|
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)
|
|
)
|
|
```
|
|
|
|
## 30.7 Workflow Runs
|
|
|
|
```sql
|
|
workflow_runs (
|
|
id uuid primary key,
|
|
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 '{}',
|
|
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
|
|
)
|
|
```
|
|
|
|
## 30.8 Stage Runs
|
|
|
|
```sql
|
|
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
|
|
)
|
|
```
|
|
|
|
## 30.9 Agents
|
|
|
|
```sql
|
|
agents (
|
|
id uuid primary key,
|
|
name text not null,
|
|
slug text unique 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
|
|
)
|
|
```
|
|
|
|
## 30.10 Agent Teams
|
|
|
|
```sql
|
|
agent_teams (
|
|
id uuid primary key,
|
|
name text not null,
|
|
slug text unique 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
|
|
)
|
|
```
|
|
|
|
## 30.11 Agent Runs
|
|
|
|
```sql
|
|
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
|
|
)
|
|
```
|
|
|
|
## 30.12 Models
|
|
|
|
```sql
|
|
models (
|
|
id uuid primary key,
|
|
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
|
|
)
|
|
```
|
|
|
|
## 30.13 Tools
|
|
|
|
```sql
|
|
tools (
|
|
id uuid primary key,
|
|
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
|
|
)
|
|
```
|
|
|
|
## 30.14 Policies
|
|
|
|
```sql
|
|
policies (
|
|
id uuid primary key,
|
|
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
|
|
)
|
|
```
|
|
|
|
## 30.15 Approvals
|
|
|
|
```sql
|
|
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
|
|
)
|
|
```
|
|
|
|
## 30.16 Artifacts
|
|
|
|
```sql
|
|
artifacts (
|
|
id uuid primary key,
|
|
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
|
|
)
|
|
```
|
|
|
|
## 30.17 Events
|
|
|
|
```sql
|
|
events (
|
|
id uuid primary key,
|
|
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
|
|
)
|
|
```
|
|
|
|
## 30.18 Audit Logs
|
|
|
|
```sql
|
|
audit_logs (
|
|
id uuid primary key,
|
|
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
|
|
)
|
|
```
|
|
|
|
## 30.19 Secrets
|
|
|
|
```sql
|
|
secrets (
|
|
id uuid primary key,
|
|
name text not null,
|
|
scope text not null,
|
|
provider text not null,
|
|
reference text not null,
|
|
metadata jsonb not null default '{}',
|
|
created_by uuid references users(id),
|
|
created_at timestamptz not null,
|
|
updated_at timestamptz not null
|
|
)
|
|
```
|
|
|
|
---
|
|
|
|
# 31. Backend API
|
|
|
|
## 31.1 Workflows
|
|
|
|
```http
|
|
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
|
|
```
|
|
|
|
## 31.2 Workflow Runs
|
|
|
|
```http
|
|
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
|
|
```
|
|
|
|
## 31.3 Agents
|
|
|
|
```http
|
|
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
|
|
```
|
|
|
|
## 31.4 Agent Teams
|
|
|
|
```http
|
|
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
|
|
```
|
|
|
|
## 31.5 Models
|
|
|
|
```http
|
|
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
|
|
```
|
|
|
|
## 31.6 Connectors
|
|
|
|
```http
|
|
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
|
|
```
|
|
|
|
## 31.7 Triggers
|
|
|
|
```http
|
|
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
|
|
```
|
|
|
|
## 31.8 Monitors
|
|
|
|
```http
|
|
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
|
|
```
|
|
|
|
## 31.9 Approvals
|
|
|
|
```http
|
|
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
|
|
```
|
|
|
|
## 31.10 Artifacts
|
|
|
|
```http
|
|
GET /api/artifacts
|
|
GET /api/artifacts/{artifact_id}
|
|
GET /api/artifacts/{artifact_id}/download
|
|
GET /api/artifacts/{artifact_id}/preview
|
|
```
|
|
|
|
## 31.11 Webhooks
|
|
|
|
```http
|
|
POST /api/webhooks/{connector_type}/{connector_id}
|
|
POST /api/webhooks/generic/{trigger_id}
|
|
```
|
|
|
|
## 31.12 Policies
|
|
|
|
```http
|
|
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
|
|
```
|
|
|
|
---
|
|
|
|
# 32. Git Issue-to-PR Reference Workflow
|
|
|
|
## 32.1 Purpose
|
|
|
|
This workflow proves AgentHub can orchestrate a real, useful, multi-stage agent process against an external system.
|
|
|
|
## 32.2 Managed Git Repository
|
|
|
|
A Git repository is represented as a connector resource.
|
|
|
|
Repository config:
|
|
|
|
```yaml
|
|
repository:
|
|
provider: github
|
|
connector: github-main
|
|
full_name: org/repo
|
|
default_branch: main
|
|
|
|
automation:
|
|
enabled: true
|
|
trigger_labels:
|
|
- agent-ready
|
|
trigger_mentions:
|
|
- "@agenthub"
|
|
|
|
branching:
|
|
branch_prefix: agent/
|
|
branch_template: "agent/issue-{issue_number}-{slug}"
|
|
|
|
pull_requests:
|
|
create_draft: true
|
|
labels:
|
|
- agent-generated
|
|
reviewers: []
|
|
|
|
specs:
|
|
enabled: true
|
|
require_approval: true
|
|
path_template: ".agenthub/specs/issue-{issue_number}/"
|
|
|
|
implementation:
|
|
agent: mini-swe-implementation-agent
|
|
sandbox: default-docker-sandbox
|
|
test_command: auto
|
|
|
|
merge:
|
|
allow_agent_merge: false
|
|
require_human_approval: true
|
|
require_ci_success: true
|
|
```
|
|
|
|
## 32.3 Spec Bundle
|
|
|
|
The Git workflow should create a spec bundle.
|
|
|
|
```text
|
|
.agenthub/specs/issue-123/
|
|
metadata.yaml
|
|
conversation.md
|
|
spec.md
|
|
plan.md
|
|
tasks.md
|
|
test-plan.md
|
|
decisions.md
|
|
implementation-log.md
|
|
```
|
|
|
|
## 32.4 Workflow Stages
|
|
|
|
```text
|
|
load_issue_context
|
|
triage_issue
|
|
generate_spec
|
|
approve_spec
|
|
prepare_workspace
|
|
run_implementation_agent
|
|
collect_diff
|
|
run_tests
|
|
push_branch
|
|
open_draft_pr
|
|
wait_for_ci
|
|
review_pr
|
|
await_human_review
|
|
revise_if_needed
|
|
complete
|
|
```
|
|
|
|
## 32.5 Revision Loop
|
|
|
|
When a PR comment or review requests changes:
|
|
|
|
```text
|
|
PR comment received
|
|
↓
|
|
event normalized
|
|
↓
|
|
workflow run resumed or new revision run created
|
|
↓
|
|
comments summarized
|
|
↓
|
|
implementation agent updates branch
|
|
↓
|
|
tests run
|
|
↓
|
|
PR updated
|
|
↓
|
|
status comment posted
|
|
```
|
|
|
|
## 32.6 Implementation Agent
|
|
|
|
The first implementation agent should use mini-SWE-agent.
|
|
|
|
Responsibilities:
|
|
|
|
* Clone repository
|
|
* Check out branch
|
|
* Read spec bundle
|
|
* Read issue context
|
|
* Modify files
|
|
* Run tests
|
|
* Commit changes
|
|
* Push branch
|
|
* Return summary
|
|
|
|
## 32.7 Review Agent
|
|
|
|
The first review agent can be either:
|
|
|
|
* simple LLM prompt adapter
|
|
* CrewAI review team
|
|
* PR-Agent adapter
|
|
|
|
Review dimensions:
|
|
|
|
* spec alignment
|
|
* test coverage
|
|
* code quality
|
|
* security concerns
|
|
* migration risk
|
|
* CI result interpretation
|
|
|
|
---
|
|
|
|
# 33. Prompt and Template System
|
|
|
|
## 33.1 Template Types
|
|
|
|
```text
|
|
trigger_summary
|
|
triage
|
|
spec_generation
|
|
implementation
|
|
review
|
|
revision
|
|
failure_summary
|
|
approval_request
|
|
external_comment
|
|
notification
|
|
```
|
|
|
|
## 33.2 Template Variables
|
|
|
|
```text
|
|
{{workflow}}
|
|
{{workflow_run}}
|
|
{{stage}}
|
|
{{input}}
|
|
{{previous_outputs}}
|
|
{{event}}
|
|
{{connector_resource}}
|
|
{{issue}}
|
|
{{comments}}
|
|
{{pull_request}}
|
|
{{ci_result}}
|
|
{{spec_bundle}}
|
|
{{policy_context}}
|
|
{{human_feedback}}
|
|
```
|
|
|
|
## 33.3 Template Versioning
|
|
|
|
Prompt templates should be versioned.
|
|
|
|
Agent runs should record:
|
|
|
|
* template ID
|
|
* template version
|
|
* rendered prompt hash
|
|
* model used
|
|
* runtime used
|
|
|
|
Do not store full prompts if the instance is configured to avoid sensitive storage. Store hashes and redacted versions.
|
|
|
|
---
|
|
|
|
# 34. Security Model
|
|
|
|
## 34.1 Threats
|
|
|
|
AgentHub must assume:
|
|
|
|
* external input may contain prompt injection
|
|
* repository content may contain malicious instructions
|
|
* issue comments may try to exfiltrate secrets
|
|
* agents may make incorrect decisions
|
|
* tools may be misused
|
|
* model output may be unsafe
|
|
* external APIs may fail or behave unexpectedly
|
|
|
|
## 34.2 Security Principles
|
|
|
|
1. Deny dangerous permissions by default.
|
|
2. Make all external writes explicit.
|
|
3. Require approval for high-risk actions.
|
|
4. Isolate code execution.
|
|
5. Never expose secrets unnecessarily.
|
|
6. Log all sensitive actions.
|
|
7. Treat model output as untrusted until validated.
|
|
8. Keep platform orchestration deterministic.
|
|
9. Keep agent runtime permissions scoped.
|
|
10. Allow repository or connector-specific policy overrides.
|
|
|
|
## 34.3 Prompt Injection Mitigations
|
|
|
|
* Separate system instructions from untrusted content.
|
|
* Label untrusted content clearly.
|
|
* Apply policy after model output.
|
|
* Block tool calls not granted to agent.
|
|
* Require approvals for sensitive actions.
|
|
* Protect secrets from model-visible context.
|
|
* Redact logs.
|
|
* Use output schemas for high-impact decisions.
|
|
* Avoid letting agents modify their own policies.
|
|
|
|
---
|
|
|
|
# 35. MVP Definition
|
|
|
|
## 35.1 MVP Goal
|
|
|
|
Build the smallest useful AgentHub that proves:
|
|
|
|
1. Workflows can be defined.
|
|
2. External events can trigger workflows.
|
|
3. Agents can run through runtime adapters.
|
|
4. The UI can monitor workflow runs.
|
|
5. A real Git issue can become a draft PR.
|
|
|
|
## 35.2 MVP Features
|
|
|
|
Required:
|
|
|
|
* Local admin login
|
|
* Connector registry
|
|
* GitHub connector
|
|
* Generic webhook connector
|
|
* Workflow definition via YAML
|
|
* Workflow run engine
|
|
* Stage execution
|
|
* Job queue
|
|
* Agent registry
|
|
* Model registry
|
|
* Simple LLM prompt adapter
|
|
* CrewAI adapter, basic
|
|
* mini-SWE-agent adapter, basic
|
|
* Docker sandbox runner
|
|
* Artifact store
|
|
* Event log
|
|
* Audit log
|
|
* Approval gate
|
|
* Live run logs
|
|
* Git issue-to-PR reference workflow
|
|
* No automatic merge
|
|
|
|
## 35.3 MVP Exclusions
|
|
|
|
Not required for MVP:
|
|
|
|
* Visual workflow builder
|
|
* Full RBAC
|
|
* Multi-tenant organizations
|
|
* GitLab connector
|
|
* Slack connector
|
|
* Marketplace
|
|
* Long-term memory
|
|
* Vector search
|
|
* Production deployment automation
|
|
* Automatic merge
|
|
* Kubernetes runner
|
|
* Firecracker sandbox
|
|
* Advanced cost analytics
|
|
|
|
---
|
|
|
|
# 36. Development Milestones
|
|
|
|
## Milestone 1: Platform Skeleton
|
|
|
|
Deliverables:
|
|
|
|
* Monorepo
|
|
* Docker Compose
|
|
* PostgreSQL
|
|
* Redis
|
|
* MinIO or local artifact storage
|
|
* Backend API shell
|
|
* Frontend shell
|
|
* Local admin auth
|
|
* Basic dashboard
|
|
|
|
## Milestone 2: Core Data Model
|
|
|
|
Deliverables:
|
|
|
|
* Database migrations
|
|
* CRUD for workflows
|
|
* CRUD for agents
|
|
* CRUD for models
|
|
* CRUD for connectors
|
|
* CRUD for triggers
|
|
* CRUD for approvals
|
|
* Event log
|
|
* Audit log
|
|
|
|
## Milestone 3: Workflow Engine v1
|
|
|
|
Deliverables:
|
|
|
|
* YAML workflow parser
|
|
* Workflow validation
|
|
* Workflow run creation
|
|
* Stage execution
|
|
* Sequential stage support
|
|
* Condition stage support
|
|
* Approval stage support
|
|
* Retry support
|
|
* Failure handling
|
|
* Run timeline UI
|
|
|
|
## Milestone 4: Runtime Adapter Framework
|
|
|
|
Deliverables:
|
|
|
|
* Runtime adapter interface
|
|
* Simple LLM prompt adapter
|
|
* Script adapter
|
|
* Docker adapter
|
|
* Runtime logs
|
|
* Runtime artifacts
|
|
* Cancellation support
|
|
|
|
## Milestone 5: Connector Framework
|
|
|
|
Deliverables:
|
|
|
|
* Connector interface
|
|
* Generic webhook connector
|
|
* GitHub connector
|
|
* Webhook verification
|
|
* Event normalization
|
|
* Trigger filtering
|
|
* Connector action execution
|
|
|
|
## Milestone 6: GitHub Reference Workflow Part 1
|
|
|
|
Deliverables:
|
|
|
|
* GitHub App setup
|
|
* Repository registration
|
|
* Issue event ingestion
|
|
* Issue context loading
|
|
* Label and mention trigger
|
|
* Triage agent
|
|
* Spec generation stage
|
|
* Spec artifact viewer
|
|
* Spec approval gate
|
|
|
|
## Milestone 7: mini-SWE-agent Adapter
|
|
|
|
Deliverables:
|
|
|
|
* Workspace preparation
|
|
* Repository clone
|
|
* Branch creation
|
|
* Prompt/context bundle creation
|
|
* mini-SWE-agent invocation
|
|
* Log streaming
|
|
* Diff collection
|
|
* Test command execution
|
|
* Commit creation
|
|
* Branch push
|
|
|
|
## Milestone 8: Pull Request Flow
|
|
|
|
Deliverables:
|
|
|
|
* Draft PR creation
|
|
* PR status tracking
|
|
* CI monitor
|
|
* PR review agent
|
|
* Human review gate
|
|
* Revision trigger from PR comments
|
|
* PR update loop
|
|
|
|
## Milestone 9: CrewAI Adapter
|
|
|
|
Deliverables:
|
|
|
|
* CrewAI runtime configuration
|
|
* Hierarchical team support
|
|
* Sequential team support
|
|
* Structured output collection
|
|
* Crew logs and artifacts
|
|
* Use CrewAI for spec team or review team
|
|
|
|
## Milestone 10: Policy and Security Hardening
|
|
|
|
Deliverables:
|
|
|
|
* Policy engine v1
|
|
* Protected path checks
|
|
* Tool permission checks
|
|
* Secret scoping
|
|
* Log redaction
|
|
* Sandbox limits
|
|
* Cost limits
|
|
* Audit log coverage
|
|
|
|
---
|
|
|
|
# 37. Suggested Monorepo Structure
|
|
|
|
```text
|
|
agenthub/
|
|
apps/
|
|
web/
|
|
api/
|
|
worker/
|
|
|
|
packages/
|
|
shared/
|
|
workflow-engine/
|
|
policy-engine/
|
|
connector-sdk/
|
|
runtime-sdk/
|
|
model-gateway/
|
|
artifact-store/
|
|
sandbox-manager/
|
|
|
|
connectors/
|
|
github/
|
|
generic-webhook/
|
|
http/
|
|
|
|
runtimes/
|
|
llm-prompt/
|
|
script/
|
|
docker/
|
|
crewai/
|
|
mini-swe-agent/
|
|
pr-agent/
|
|
|
|
workflows/
|
|
examples/
|
|
github-issue-to-pr.yaml
|
|
webhook-summarizer.yaml
|
|
|
|
agents/
|
|
examples/
|
|
git-triage-agent.yaml
|
|
git-spec-team.yaml
|
|
mini-swe-implementation-agent.yaml
|
|
pr-review-team.yaml
|
|
|
|
infra/
|
|
docker-compose.yml
|
|
k8s/
|
|
helm/
|
|
|
|
docs/
|
|
product-spec.md
|
|
architecture.md
|
|
security.md
|
|
workflow-format.md
|
|
connector-sdk.md
|
|
runtime-sdk.md
|
|
github-reference-workflow.md
|
|
|
|
tests/
|
|
integration/
|
|
fixtures/
|
|
```
|
|
|
|
---
|
|
|
|
# 38. First Vertical Slice
|
|
|
|
The first vertical slice should avoid overbuilding.
|
|
|
|
Goal:
|
|
|
|
```text
|
|
manual workflow run
|
|
↓
|
|
simple prompt agent
|
|
↓
|
|
approval gate
|
|
↓
|
|
GitHub issue context
|
|
↓
|
|
spec artifact
|
|
```
|
|
|
|
Then expand to:
|
|
|
|
```text
|
|
GitHub label trigger
|
|
↓
|
|
spec generation
|
|
↓
|
|
approval
|
|
↓
|
|
mini-SWE-agent
|
|
↓
|
|
draft PR
|
|
```
|
|
|
|
## 38.1 First Slice Acceptance Criteria
|
|
|
|
The first prototype is done when:
|
|
|
|
1. A user can start the stack with Docker Compose.
|
|
2. A user can log in locally.
|
|
3. A user can create a model definition.
|
|
4. A user can create an agent definition.
|
|
5. A user can create a workflow YAML.
|
|
6. A user can manually run the workflow.
|
|
7. The workflow runs one agent stage.
|
|
8. The agent produces a markdown artifact.
|
|
9. The UI shows the run timeline.
|
|
10. The UI shows logs.
|
|
11. The UI shows the artifact.
|
|
12. The workflow can pause for approval.
|
|
13. The user can approve and complete the workflow.
|
|
|
|
## 38.2 Second Slice Acceptance Criteria
|
|
|
|
The second prototype is done when:
|
|
|
|
1. A GitHub connector can be configured.
|
|
2. AgentHub receives GitHub webhooks.
|
|
3. A label trigger starts a workflow.
|
|
4. The workflow loads issue context.
|
|
5. The spec team creates a spec artifact.
|
|
6. A maintainer approves the spec.
|
|
7. The mini-SWE-agent adapter runs in Docker.
|
|
8. A branch is pushed.
|
|
9. A draft PR is opened.
|
|
10. Logs and artifacts are visible in the UI.
|
|
|
|
---
|
|
|
|
# 39. Example Workflow: Generic Webhook Summarizer
|
|
|
|
This example proves the platform is not Git-specific.
|
|
|
|
```yaml
|
|
id: webhook-summarizer
|
|
name: Webhook Summarizer
|
|
version: 1
|
|
enabled: true
|
|
|
|
triggers:
|
|
- id: generic-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 posting"
|
|
required_roles:
|
|
- admin
|
|
input:
|
|
summary: "{{ summary }}"
|
|
|
|
- id: post_result
|
|
type: connector_action
|
|
connector: http
|
|
action: http.post
|
|
input:
|
|
url: "{{ event.payload.callback_url }}"
|
|
body:
|
|
summary: "{{ summary }}"
|
|
|
|
- id: complete
|
|
type: terminal
|
|
status: success
|
|
```
|
|
|
|
---
|
|
|
|
# 40. Example Workflow: Git Issue to PR
|
|
|
|
```yaml
|
|
id: github-issue-to-pr
|
|
name: GitHub Issue to Pull Request
|
|
version: 1
|
|
enabled: true
|
|
|
|
triggers:
|
|
- id: label-agent-ready
|
|
type: connector_event
|
|
connector: github-main
|
|
event: github.issue.labeled
|
|
filter:
|
|
all:
|
|
- path: "$.label.name"
|
|
equals: "agent-ready"
|
|
- path: "$.issue.state"
|
|
equals: "open"
|
|
|
|
stages:
|
|
- id: load_issue
|
|
type: connector_action
|
|
connector: github-main
|
|
action: github.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: git-triage-agent
|
|
input:
|
|
issue_context: "{{ issue_context }}"
|
|
outputs:
|
|
triage: result
|
|
|
|
- id: maybe_stop
|
|
type: condition
|
|
expression: "{{ triage.suitable == true }}"
|
|
on_true: generate_spec
|
|
on_false: comment_not_suitable
|
|
|
|
- id: comment_not_suitable
|
|
type: connector_action
|
|
connector: github-main
|
|
action: github.create_issue_comment
|
|
input:
|
|
repository: "{{ issue_context.repository }}"
|
|
issue_number: "{{ issue_context.number }}"
|
|
body: "AgentHub triaged this issue as not suitable for automation: {{ triage.reason }}"
|
|
next: complete_not_suitable
|
|
|
|
- id: complete_not_suitable
|
|
type: terminal
|
|
status: success
|
|
|
|
- id: generate_spec
|
|
type: agent_team
|
|
team: git-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: github-main
|
|
action: github.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: github-main
|
|
condition: github.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: complete
|
|
type: terminal
|
|
status: success
|
|
```
|
|
|
|
---
|
|
|
|
# 41. Definition of Done for MVP
|
|
|
|
The MVP is complete when:
|
|
|
|
1. AgentHub runs locally through Docker Compose.
|
|
2. A user can log in.
|
|
3. A user can configure at least one model provider.
|
|
4. A user can configure at least one GitHub connector.
|
|
5. A user can define a workflow in YAML.
|
|
6. A user can manually run a workflow.
|
|
7. A GitHub webhook can trigger a workflow.
|
|
8. A workflow can run a single-agent stage.
|
|
9. A workflow can run a CrewAI team stage.
|
|
10. A workflow can run a mini-SWE-agent implementation stage.
|
|
11. A workflow can pause for human approval.
|
|
12. A workflow can produce artifacts.
|
|
13. The UI shows run state, logs, artifacts, and approvals.
|
|
14. The Git workflow can turn a labeled issue into a draft PR.
|
|
15. The system records audit events for external writes.
|
|
16. The system does not merge PRs automatically.
|
|
|
|
---
|
|
|
|
# 42. Open Questions
|
|
|
|
1. Should the initial workflow engine be custom, or should the project start on Temporal/Hatchet immediately?
|
|
2. Should workflow definitions be YAML-only initially, or should the UI generate YAML?
|
|
3. Should CrewAI support be included in the first MVP or the second milestone?
|
|
4. Should agent definitions live only in the database, or also as versioned files in Git?
|
|
5. Should workflow definitions be importable from Git repositories?
|
|
6. Should model routing be global first, or workflow-local first?
|
|
7. Should local models be a first-class MVP requirement?
|
|
8. Should secrets use an internal encrypted store or external secret managers only?
|
|
9. Should each agent run get its own Docker image or share a base image?
|
|
10. Should the GitHub connector use GitHub App authentication only, or also personal access tokens for local development?
|
|
11. Should workflow runs be immutable once started?
|
|
12. Should human comments be accepted from external systems or only from the AgentHub UI?
|
|
13. Should agents be able to start sub-workflows?
|
|
14. Should policies be written in YAML first, or use a policy engine like OPA later?
|
|
15. Should long-term memory be delayed until after the Git reference workflow is stable?
|
|
|
|
---
|
|
|
|
# 43. Recommended Initial Decisions
|
|
|
|
For fastest progress:
|
|
|
|
```yaml
|
|
workflow_engine: custom_sequential_state_machine_first
|
|
workflow_definition: yaml
|
|
frontend: nextjs
|
|
backend: fastapi
|
|
database: postgres
|
|
queue: redis_rq_or_celery
|
|
artifact_storage: local_filesystem_then_minio
|
|
sandbox: docker
|
|
first_connector: github
|
|
second_connector: generic_webhook
|
|
first_runtime: llm_prompt
|
|
second_runtime: mini_swe_agent
|
|
third_runtime: crewai
|
|
merge_policy: human_only
|
|
auth: local_admin_first
|
|
```
|
|
|
|
---
|
|
|
|
# 44. Product Philosophy
|
|
|
|
AgentHub should be built around these principles:
|
|
|
|
1. The platform owns control.
|
|
2. Agents own task execution.
|
|
3. Humans own approval.
|
|
4. Policies own boundaries.
|
|
5. Workflows own process.
|
|
6. Connectors own external integration.
|
|
7. Runtimes are replaceable.
|
|
8. Models are replaceable.
|
|
9. Artifacts are first-class.
|
|
10. Every important action is observable and auditable.
|
|
|
|
---
|
|
|
|
# 45. Immediate Next Development Steps
|
|
|
|
1. Create the monorepo.
|
|
2. Add Docker Compose for web, api, worker, Postgres, Redis, and MinIO.
|
|
3. Implement the database schema for workflows, workflow runs, stage runs, agents, models, connectors, artifacts, events, and approvals.
|
|
4. Implement YAML workflow validation.
|
|
5. Implement manual workflow execution.
|
|
6. Implement the simple LLM prompt runtime.
|
|
7. Implement run timeline and logs in the UI.
|
|
8. Implement approval gates.
|
|
9. Implement the generic webhook connector.
|
|
10. Implement the GitHub connector.
|
|
11. Implement the GitHub issue-to-spec workflow.
|
|
12. Implement the mini-SWE-agent adapter.
|
|
13. Implement draft PR creation.
|
|
14. Add CrewAI as an agent team runtime.
|
|
15. Harden policies and sandboxing before enabling broader workflows.
|
|
|
|
---
|