From 665f43080bb003986219bfb33691aea0da037c57 Mon Sep 17 00:00:00 2001 From: Rockford Lhotka Date: Thu, 23 Apr 2026 14:56:01 -0500 Subject: [PATCH] Add GitHub Pages site for foragent.dev; refresh README for alpha status - /docs/index.md landing page: purpose, scenarios, quick start, resource links, contributing - /docs/_config.yml Jekyll config (cayman theme, excludes archive/framework-feedback/README) - /docs/CNAME pins custom domain to foragent.dev - README: drop "not yet functional" warning (v0.2 has shipped), expand capabilities list, add docker-compose quick start, link to foragent.dev and docs/ Co-Authored-By: Claude Opus 4.7 (1M context) --- README.md | 82 +++++++++++++++++++++---- docs/CNAME | 1 + docs/_config.yml | 21 +++++++ docs/index.md | 151 +++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 243 insertions(+), 12 deletions(-) create mode 100644 docs/CNAME create mode 100644 docs/_config.yml create mode 100644 docs/index.md diff --git a/README.md b/README.md index 9f2c14c..a978478 100644 --- a/README.md +++ b/README.md @@ -1,28 +1,46 @@ # Foragent -> ⚠️ **Early development — APIs will change without notice.** +> ⚠️ **Alpha quality — APIs will change without notice.** v0.2 has shipped +> end-to-end but the project is still pre-1.0 and is not yet publishing +> NuGet or Docker artifacts. **Foragent** is an A2A-native browser agent for .NET. It exposes browser -automation capabilities (navigate, extract, fill forms, post to sites, -monitor pages) over the [Agent2Agent (A2A) protocol](https://google.github.io/A2A/). Other agents -delegate browser work to Foragent rather than reasoning about DOM selectors -or session management themselves. +automation capabilities over the +[Agent2Agent (A2A) protocol](https://google.github.io/A2A/) so other +agents can delegate browser work rather than reasoning about DOM +selectors, login flows, or session management themselves. Foragent is built on the [RockBot framework](https://github.com/MarimerLLC/rockbot) and uses [Microsoft.Playwright](https://playwright.dev/dotnet/) for browser automation. +Project site: [foragent.dev](https://foragent.dev) + ## Build status ![CI](https://github.com/MarimerLLC/foragent/actions/workflows/ci.yml/badge.svg) ## What Foragent does -- Accepts browser tasks from other agents via A2A -- Executes tasks using a real browser (Playwright) with LLM-assisted selector - resolution (Microsoft.Extensions.AI) -- Returns structured results over A2A -- Manages browser contexts per task; keeps credentials inside the process +- Accepts browser tasks from other agents via A2A (RabbitMQ or HTTP) +- Executes tasks in a real browser (Chromium via Playwright) with + LLM-in-the-loop planning over ref-annotated aria snapshots +- Manages one shared browser per process with a fresh `BrowserContext` + per task for isolation +- Keeps credentials inside the Foragent process — callers reference + them by id, never by value +- Learns from successful tasks: persists reusable site skills and + form schemas, consolidated by a daily dream pass + +Advertised capabilities today: + +- `browser-task` — LLM-planned multi-step browser work under a host + allowlist +- `learn-form-schema` — scan a form and persist a typed schema +- `execute-form-batch` — submit a batch of rows against a learned + schema + +See [docs/capabilities.md](docs/capabilities.md) for the full contract. ## What Foragent is not @@ -32,8 +50,48 @@ automation. ## Getting started -> ⚠️ The agent is not yet functional. See `docs/architecture.md` for the -> planned design and `docs/capabilities.md` for planned capabilities. +The fastest path is the end-to-end dev harness at the repo root: + +```bash +docker compose up --build +``` + +That brings up RabbitMQ, Foragent (HTTP A2A on `http://localhost:5210`), +and a RockBot agent seeded to know about Foragent as an A2A peer. The +agent-card is published at +`http://localhost:5210/.well-known/agent-card.json`; the authenticated +JSON-RPC endpoint is `POST http://localhost:5210/` with header +`X-Api-Key: rockbot-calls-foragent`. A curl-based smoke test is at the +top of `docker-compose.yml`. + +For local builds without Docker: + +```bash +dotnet restore +dotnet build --configuration Release +dotnet test --configuration Release +``` + +Target framework is **.NET 10**. Foragent requires an LLM — configure +`ForagentLlm:Endpoint`, `ModelId`, and `ApiKey` (see +[docs/architecture.md](docs/architecture.md) for the full configuration +surface). + +## Documentation + +- [Specification](docs/foragent-specification.md) — the governing + design document (v0.2) +- [Architecture](docs/architecture.md) — how the pieces fit together +- [Capabilities](docs/capabilities.md) — what Foragent exposes over A2A +- [Credentials](docs/credentials.md) — how credentials are modeled and + resolved + +## Contributing + +External code contributions are not yet open — see +[CONTRIBUTING.md](CONTRIBUTING.md). Bug reports and capability +suggestions via [issues](https://github.com/MarimerLLC/foragent/issues) +are welcome. ## License diff --git a/docs/CNAME b/docs/CNAME new file mode 100644 index 0000000..d4387ae --- /dev/null +++ b/docs/CNAME @@ -0,0 +1 @@ +foragent.dev diff --git a/docs/_config.yml b/docs/_config.yml new file mode 100644 index 0000000..436751d --- /dev/null +++ b/docs/_config.yml @@ -0,0 +1,21 @@ +title: Foragent +description: An A2A-native browser agent for .NET +url: https://foragent.dev + +theme: jekyll-theme-cayman + +# GitHub repository metadata (used by the theme for the header links) +repository: MarimerLLC/foragent +show_downloads: false + +# Don't publish these in the rendered site +exclude: + - archive/ + - framework-feedback.md + - README.md + +# Markdown + syntax highlighting +markdown: kramdown +kramdown: + input: GFM + syntax_highlighter: rouge diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..6ebd4d4 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,151 @@ +--- +layout: default +title: Foragent +description: An A2A-native browser agent for .NET +--- + +# Foragent + +**An A2A-native browser agent for .NET.** Other agents delegate browser +work to Foragent rather than reasoning about DOM selectors, login flows, +or session management themselves. + +Foragent is built on the [RockBot framework](https://github.com/MarimerLLC/rockbot) +and uses [Microsoft.Playwright](https://playwright.dev/dotnet/) for browser +automation. It speaks the +[Agent2Agent (A2A) protocol](https://google.github.io/A2A/) over RabbitMQ +and HTTP. + +> ⚠️ **Early development.** APIs change without notice. External +> contributions are not yet open — see [Contributing](#contributing) below. + +--- + +## Why Foragent exists + +Agents that need to "just use a website" — read a page, fill a form, +post an update — usually end up re-inventing a brittle mix of HTTP +scraping, selector heuristics, and credential handling. Foragent +centralizes that work behind a small A2A surface so the rest of your +agent fleet can stay focused on their own jobs. + +The design principles are laid out in the +[specification]({{ '/foragent-specification' | relative_url }}): + +- **Task-level capabilities, not action-level.** Callers ask for + *"post this update to bsky"*, not *"click the button with aria-label X"*. +- **One shared browser, one fresh context per task.** Isolation comes + from the context boundary, not from spinning up new browsers. +- **Credentials stay inside the process.** Callers reference them by + id; Foragent resolves them locally and never returns their values. +- **Multi-tenant from day one.** Tenant identity comes from the A2A + caller, not from request payloads. +- **Learning substrate.** Successful tasks write reusable skills that + prime future planning; a daily dream loop consolidates them. + +--- + +## Usage scenarios + +Foragent is aimed at other agents, not end users. Typical callers: + +- **Social posting.** A personal assistant agent asks Foragent to + publish an update to a site it has credentials for. +- **Site monitoring.** A research or ops agent asks Foragent to check + a page and report back structured results. +- **Form submission at scale.** A workflow agent hands Foragent a + learned form schema plus a batch of rows; Foragent submits each one + and streams per-row progress. +- **One-off browser tasks.** A generalist agent describes an intent + in natural language; Foragent's planner drives the browser + step-by-step under a strict host allowlist. + +The current advertised capabilities are: + +| Capability | What it does | +|---|---| +| `browser-task` | LLM-planned, multi-step browser work against an allowlist of hosts | +| `learn-form-schema` | Scan a form and persist a typed schema for later reuse | +| `execute-form-batch` | Submit a batch of rows against a learned (or inline) form schema | + +See [capabilities]({{ '/capabilities' | relative_url }}) for the full +contract, inputs, and examples. + +--- + +## Getting started + +The fastest path is the end-to-end dev harness at the repo root: + +```bash +git clone https://github.com/MarimerLLC/foragent.git +cd foragent +docker compose up --build +``` + +That brings up RabbitMQ, Foragent (HTTP A2A on `http://localhost:5210`), +and a RockBot agent seeded to know about Foragent as an A2A peer. The +agent-card is published at +`http://localhost:5210/.well-known/agent-card.json`; the authenticated +JSON-RPC endpoint is `POST http://localhost:5210/` with header +`X-Api-Key: rockbot-calls-foragent`. A curl-based smoke test is at the +top of `docker-compose.yml`. + +For local builds without Docker: + +```bash +dotnet restore +dotnet build --configuration Release +dotnet test --configuration Release +``` + +Target framework is **.NET 10**. Foragent requires an LLM — configure +`ForagentLlm:Endpoint`, `ModelId`, and `ApiKey` (see +[architecture]({{ '/architecture' | relative_url }}) for the full +configuration surface). + +--- + +## Resources + +**In this repo:** + +- [Specification]({{ '/foragent-specification' | relative_url }}) — the + governing design document (v0.2) +- [Architecture]({{ '/architecture' | relative_url }}) — how the pieces + fit together +- [Capabilities]({{ '/capabilities' | relative_url }}) — what Foragent + exposes over A2A +- [Credentials]({{ '/credentials' | relative_url }}) — how credentials + are modeled and resolved +- [Framework feedback]({{ '/framework-feedback' | relative_url }}) — + observations pushed back to the RockBot framework + +**On GitHub:** + +- [Source on GitHub](https://github.com/MarimerLLC/foragent) +- [Issues](https://github.com/MarimerLLC/foragent/issues) — bug reports + and feature suggestions are welcome +- [RockBot framework](https://github.com/MarimerLLC/rockbot) — the + agent framework Foragent is built on + +--- + +## Contributing + +Foragent is in early development and is **not yet accepting external +code contributions** — see +[CONTRIBUTING.md](https://github.com/MarimerLLC/foragent/blob/main/CONTRIBUTING.md). + +In the meantime, the most useful things outside contributors can do are: + +- Open an [issue](https://github.com/MarimerLLC/foragent/issues) to + report a bug or suggest a capability +- Read the [specification]({{ '/foragent-specification' | relative_url }}) + and push back on anything that looks wrong + +--- + +## License + +MIT — see [LICENSE](https://github.com/MarimerLLC/foragent/blob/main/LICENSE).