{"id":50597463,"url":"https://github.com/waqasraza123/agent-runway","last_synced_at":"2026-06-05T15:30:38.898Z","repository":{"id":343908607,"uuid":"1179500207","full_name":"waqasraza123/agent-runway","owner":"waqasraza123","description":"AI workflow automation engine for auditable business processes.","archived":false,"fork":false,"pushed_at":"2026-05-06T17:30:55.000Z","size":369,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-06T18:16:01.400Z","etag":null,"topics":["agent-orchestration","anthropic","langchain","multi-agent","openapi","research-platform","workflow-orchestration"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/waqasraza123.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-12T04:53:10.000Z","updated_at":"2026-05-06T17:31:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/waqasraza123/agent-runway","commit_stats":null,"previous_names":["waqasraza123/multi-agent-workflow-orchestrator","waqasraza123/agent-runway"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/waqasraza123/agent-runway","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/waqasraza123%2Fagent-runway","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/waqasraza123%2Fagent-runway/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/waqasraza123%2Fagent-runway/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/waqasraza123%2Fagent-runway/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/waqasraza123","download_url":"https://codeload.github.com/waqasraza123/agent-runway/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/waqasraza123%2Fagent-runway/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33949038,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-05T02:00:06.157Z","response_time":120,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-orchestration","anthropic","langchain","multi-agent","openapi","research-platform","workflow-orchestration"],"created_at":"2026-06-05T15:30:37.815Z","updated_at":"2026-06-05T15:30:38.884Z","avatar_url":"https://github.com/waqasraza123.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Agent Runway\n\nAgent Runway is a backend-first execution platform for auditable AI workflows. It turns a business goal into a tracked run, creates a plan, advances execution through deterministic or provider-backed agent turns, records tool calls and evidence, verifies completion, and produces a final output.\n\nIt is designed for teams that need AI workflow automation with traceability instead of one-off chat responses.\n\n## What It Does\n\n- Creates and tracks workflow runs from a user goal.\n- Generates deterministic task plans for repeatable execution.\n- Advances work through deterministic or LLM-backed turns.\n- Executes registered tools and records structured tool-call artifacts.\n- Stores events, turns, approvals, verifications, outputs, and LLM call records.\n- Supports human approval checkpoints.\n- Produces verification reports before final output synthesis.\n- Exposes the workflow through a FastAPI API and a lightweight browser console.\n\n## Product Use Cases\n\nAgent Runway is useful for workflow automation that needs a durable audit trail:\n\n- technical planning and delivery breakdowns\n- vendor or proposal analysis\n- research workflows with evidence capture\n- operational checklists with approval gates\n- AI-assisted decision support where each step must be inspectable\n\n## Execution Flow\n\n1. Create a run from a business goal.\n2. Generate the run plan.\n3. Advance turns until planned tasks are completed.\n4. Record tool calls, evidence, events, and LLM call artifacts.\n5. Request and resolve approvals when needed.\n6. Verify the run.\n7. Finalize the output.\n\n## API Highlights\n\nKey workflow endpoints:\n\n- `POST /runs`\n- `GET /runs`\n- `GET /runs/{run_id}`\n- `GET /runs/{run_id}/state`\n- `POST /runs/{run_id}/plan`\n- `POST /runs/{run_id}/turns/advance`\n- `GET /runs/{run_id}/turns`\n- `GET /runs/{run_id}/events`\n- `GET /runs/{run_id}/tool-calls`\n- `GET /runs/{run_id}/llm-calls`\n- `GET /runs/{run_id}/approvals`\n- `POST /runs/{run_id}/approvals`\n- `POST /runs/{run_id}/approvals/{approval_id}/decide`\n- `POST /runs/{run_id}/verify`\n- `POST /runs/{run_id}/finalize`\n- `GET /runs/{run_id}/outputs/latest`\n\nFastAPI also exposes interactive API docs at `/docs` when the service is running.\n\n## Run Locally\n\nInstall dependencies:\n\n```bash\nuv sync --group dev\n```\n\nRun the API and browser console:\n\n```bash\nuv run uvicorn multi_agent_platform.main:app --reload\n```\n\nOpen:\n\n```text\nhttp://127.0.0.1:8000\n```\n\nRun the quality gate:\n\n```bash\nmake check\n```\n\nRun the release smoke checks:\n\n```bash\nmake release-check\n```\n\n## Hybrid Go And Python Backend\n\nAgent Runway is moving toward a hybrid backend:\n\n- Go control plane in `apps/api-go`\n- Python agent worker in `services/agent_worker`\n- shared contracts in `packages/contracts`\n- local hybrid runtime in `infra/docker`\n\nIn this model, Go owns the public API, database access, orchestration, and run state transitions. Python owns LLM/provider execution and returns structured turn outcomes over a private internal HTTP API.\n\nThe Go control plane currently owns:\n\n- `POST /runs`\n- `GET /runs`\n- `GET /runs/{run_id}`\n- `GET /runs/{run_id}/state`\n- `POST /runs/{run_id}/plan`\n- `GET /runs/{run_id}/plans/latest`\n- `POST /runs/{run_id}/turns/advance`\n- `POST /runs/{run_id}/verify`\n- `GET /runs/{run_id}/verifications/latest`\n- `POST /runs/{run_id}/finalize`\n- `GET /runs/{run_id}/outputs/latest`\n- `GET /runs/{run_id}/approvals`\n- `POST /runs/{run_id}/approvals`\n- `POST /runs/{run_id}/approvals/{approval_id}/decide`\n- `GET /runs/{run_id}/events`\n- `GET /runs/{run_id}/turns`\n- `GET /runs/{run_id}/tool-calls`\n- `GET /runs/{run_id}/llm-calls`\n- `GET /health`\n- `GET /ready`\n\nThe remaining workflow endpoints continue to use the Python FastAPI app as the reference implementation until they are ported. In `PLANNING_BACKEND=llm` mode, Go calls the private Python worker for plan generation, validates the returned tasks, and persists the plan itself. In `EXECUTION_BACKEND=llm` mode, Go calls the private Python worker for turn execution and then persists the resulting state, turn, tool-call, evidence, event, and LLM-call records itself. Go also owns approval checkpoints, verifies completed runs, enforces the finalization gate, writes final outputs, and records lifecycle events. If the worker is unavailable, Go can fall back to deterministic planning or execution according to the configured fallback policy.\n\nThe Go control plane supports opt-in RBAC with bearer or `X-API-Key` tokens. `GET /health` and `GET /ready` remain public for platform probes; workflow endpoints require viewer, operator, or admin access when `AUTH_MODE` is enabled. Authenticated tokens resolve to durable user and tenant records, and Go enforces tenant ownership on run lists, reads, and mutations.\n\nThe Go control plane also emits structured request logs, persists `X-Request-ID` plus `traceparent` on run events, propagates both headers to the Python worker, and can export OTLP/HTTP server spans to an OpenTelemetry collector.\n\nRun the Python worker locally:\n\n```bash\nmake agent-worker-dev\n```\n\nRun the Go control plane locally:\n\n```bash\nmake api-go-dev\n```\n\nUse deterministic turn execution by default:\n\n```bash\nEXECUTION_BACKEND=deterministic\n```\n\nUse worker-backed LLM execution:\n\n```bash\nEXECUTION_BACKEND=llm\nLLM_PROVIDER_NAME=fake\nLLM_MODEL_NAME=fake-model\nAGENT_WORKER_URL=http://127.0.0.1:8090\n```\n\nRun both services with Postgres:\n\n```bash\nmake hybrid-up\n```\n\nExport the current FastAPI OpenAPI contract:\n\n```bash\nmake export-openapi\n```\n\nThe Go toolchain is required for `make api-go-dev`. After installing Go, run this once from `apps/api-go` to resolve module checksums:\n\n```bash\ngo mod tidy\n```\n\n## Configuration\n\nStorage backends:\n\n```bash\nSTORAGE_BACKEND=memory\nSTORAGE_BACKEND=sql\n```\n\nDefault SQL database:\n\n```bash\nDATABASE_URL=sqlite:///./.workdir/multi_agent_platform.db\n```\n\nRun migrations before using SQL storage:\n\n```bash\nmake migrate\n```\n\nFor PostgreSQL, install the same app with a PostgreSQL URL:\n\n```bash\nSTORAGE_BACKEND=sql\nDATABASE_URL=postgresql+psycopg://user:password@host:5432/database\nmake migrate\n```\n\nExecution backends:\n\n```bash\nEXECUTION_BACKEND=deterministic\nEXECUTION_BACKEND=llm\nEXECUTION_FALLBACK_ENABLED=true\n```\n\nLLM provider settings:\n\n```bash\nLLM_PROVIDER_NAME=fake\nLLM_PROVIDER_NAME=openai\nLLM_MODEL_NAME=fake-model\nLLM_API_BASE_URL=https://api.openai.com/v1\nLLM_API_KEY=...\n```\n\n`LLM_API_KEY` is required when `LLM_PROVIDER_NAME=openai`.\n\nPlanning backends:\n\n```bash\nPLANNING_BACKEND=deterministic\nPLANNING_BACKEND=llm\nPLANNING_PROVIDER_NAME=fake\nPLANNING_PROVIDER_NAME=openai\nPLANNING_MODEL_NAME=fake-model\nPLANNING_MAX_RETRIES=0\nPLANNING_FALLBACK_ENABLED=true\nTENANT_PROVIDER_POLICIES_JSON='[{\"tenant_id\":\"tenant_acme\",\"execution\":{\"provider_name\":\"openai\",\"model_name\":\"gpt-4.1\"},\"monthly_budget_usd\":250,\"per_run_budget_usd\":10,\"budget_mode\":\"block\"}]'\n```\n\n`TENANT_PROVIDER_POLICIES_JSON` is optional. When set, it overrides planning/execution provider routes by durable `tenant_id` and enables monthly or per-run budget checks from the provider usage ledger.\n\nGo API auth:\n\n```bash\nAUTH_MODE=disabled\nAUTH_MODE=bearer\nAUTH_MODE=api_key\nAUTH_MODE=jwt\nAUTH_VIEWER_TOKENS=\u003ccomma-separated-read-tokens\u003e\nAUTH_OPERATOR_TOKENS=\u003ccomma-separated-write-tokens\u003e\nAUTH_ADMIN_TOKENS=\u003ccomma-separated-admin-tokens\u003e\nAUTH_DEFAULT_TENANT_ID=tenant_default\nAUTH_TOKEN_PRINCIPALS_JSON='[{\"token\":\"operator-token\",\"tenant_id\":\"tenant_acme\",\"user_id\":\"user_alice\",\"subject\":\"user:alice@example.com\"}]'\nAUTH_JWT_ISSUER=https://issuer.example.com\nAUTH_JWT_AUDIENCE=agent-runway-api\nAUTH_JWKS_URL=https://issuer.example.com/.well-known/jwks.json\n```\n\nUse `AUTH_MODE=bearer`, `AUTH_MODE=api_key`, or `AUTH_MODE=jwt` outside local development. Clients can authenticate with `Authorization: Bearer \u003ctoken\u003e` or `X-API-Key: \u003ctoken\u003e` for static modes, and `Authorization: Bearer \u003cjwt\u003e` for JWT mode.\n\n`AUTH_TOKEN_PRINCIPALS_JSON` is optional but recommended in deployed environments so each token maps to a stable tenant/user identity. The token must still be present in one of the role token lists.\n\nJWT mode supports HS256 shared secrets and RS256 validation from either a PEM public key or a JWKS URL. JWT claims map to durable user, tenant, and role records before workflow handlers run.\n\nGo API observability:\n\n```bash\nOTEL_SERVICE_NAME=agent-runway-api-go\nOTEL_RESOURCE_ENVIRONMENT=production\nOTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318\nOTEL_EXPORTER_OTLP_HEADERS=\nOTEL_EXPORTER_OTLP_TIMEOUT_SECONDS=2\nOTEL_EXPORTER_OTLP_QUEUE_SIZE=256\n```\n\nSet `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` instead of `OTEL_EXPORTER_OTLP_ENDPOINT` when your collector exposes a custom traces path.\n\n## Deploy On Render\n\nUse Render as a Python web service.\n\n1. Push this repository to GitHub, GitLab, or Bitbucket.\n2. In Render, create a new **Web Service** from the repository.\n3. Set the runtime to **Python 3**.\n4. Set the build command:\n\n```bash\nuv sync --frozen --no-dev\n```\n\n5. Set the start command:\n\n```bash\nuv run uvicorn multi_agent_platform.main:app --host 0.0.0.0 --port $PORT\n```\n\n6. Add environment variables:\n\n```bash\nPYTHON_VERSION=3.12.11\nSTORAGE_BACKEND=memory\nEXECUTION_BACKEND=deterministic\nLLM_PROVIDER_NAME=fake\nLLM_MODEL_NAME=fake-model\n```\n\n7. Deploy the service.\n8. After deploy, open the Render URL. The browser console loads at `/`, and the API docs load at `/docs`.\n\nFor an LLM-backed demo, change the execution variables:\n\n```bash\nEXECUTION_BACKEND=llm\nLLM_PROVIDER_NAME=openai\nLLM_MODEL_NAME=\u003cyour-model-name\u003e\nLLM_API_BASE_URL=https://api.openai.com/v1\nLLM_API_KEY=\u003cyour-api-key\u003e\n```\n\nStorage note: use `STORAGE_BACKEND=memory` for the fastest Render demo. Use PostgreSQL for durable Render data.\n\nFor durable Render data, create a Render PostgreSQL database and set:\n\n```bash\nSTORAGE_BACKEND=sql\nDATABASE_URL=\u003cyour-render-postgres-url\u003e\n```\n\nThen run migrations as a Render pre-deploy command or one-off shell command:\n\n```bash\nuv run alembic upgrade head\n```\n\nDo not use the default SQLite URL for production Render data.\n\n## Smoke Flows\n\nRun the built-in smoke flows locally:\n\n```bash\nmake smoke-memory\nmake smoke-sql\nmake smoke-llm-fake\n```\n\n## Repository Structure\n\n- `apps/api-go` contains the Go control-plane service.\n- `services/agent_worker` contains the private Python LLM/agent worker.\n- `packages/contracts` contains shared API and worker-boundary contracts.\n- `infra/docker` contains local hybrid runtime wiring.\n- `src/multi_agent_platform/api` exposes the FastAPI app and routes.\n- `src/multi_agent_platform/application` coordinates workflow services.\n- `src/multi_agent_platform/contracts` defines request, response, and domain models.\n- `src/multi_agent_platform/orchestration` owns run state transitions.\n- `src/multi_agent_platform/planning` generates deterministic plans.\n- `src/multi_agent_platform/agents` contains deterministic and provider-backed execution.\n- `src/multi_agent_platform/tools` contains deterministic tool execution.\n- `src/multi_agent_platform/storage` contains memory and SQL repositories.\n- `src/multi_agent_platform/web` contains the lightweight browser console.\n- `tests/unit` and `tests/integration` cover the implemented platform spine.\n\n## Current Production Notes\n\nAgent Runway is backend-MVP ready for demos, architecture walkthroughs, portfolio presentation, and further hardening.\n\nThe next production upgrades are worker-side spans, token revocation metadata, audit actor IDs, and a fuller operator console.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwaqasraza123%2Fagent-runway","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwaqasraza123%2Fagent-runway","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwaqasraza123%2Fagent-runway/lists"}