@framers/agentos 0.1.97 → 0.1.99

package/README.md

@@ -24,8 +24,9 @@
 
 - [Overview](#overview)
 - [Quick Start](#quick-start)
-  - [High-Level API](#high-level-api)
-  - [Low-Level Runtime API](#low-level-runtime-api)
+  - [Multi-Agent Teams with agency()](#multi-agent-teams-with-agency)
+  - [Single-Agent and Low-Level Helpers](#single-agent-and-low-level-helpers)
+  - [Advanced: AgentGraph and Full Runtime](#advanced-agentgraph-and-full-runtime)
 - [System Architecture](#system-architecture)
   - [Architecture Diagram](#architecture-diagram)
   - [Request Lifecycle](#request-lifecycle)
@@ -149,18 +150,55 @@ npm install @framers/agentos
 
 **Start here:**
 
-- Use [`generateText()` / `streamText()` / `generateImage()` / `agent()`](./docs/HIGH_LEVEL_API.md) when you want the fastest path from prompt to working code.
-- Use [`AgentOS`](#low-level-runtime-api) when you need extensions, workflows, personas, HITL, or full runtime control.
-- Browse the live docs entrypoints at [docs.agentos.sh/getting-started/high-level-api](https://docs.agentos.sh/getting-started/high-level-api) and [docs.agentos.sh/api](https://docs.agentos.sh/api).
+- Use [`agency()`](./docs/AGENCY_API.md) to coordinate a team of agents with a single call.
+- Use [`generateText()` / `streamText()` / `generateImage()` / `agent()`](./docs/HIGH_LEVEL_API.md) for the fastest path from prompt to working code.
+- Use [`AgentOS`](#advanced-agentgraph-and-full-runtime) when you need extensions, workflows, personas, or full runtime lifecycle control.
+- Browse the live docs at [docs.agentos.sh/getting-started/high-level-api](https://docs.agentos.sh/getting-started/high-level-api) and [docs.agentos.sh/api](https://docs.agentos.sh/api).
 
-### High-Level API
+### Multi-Agent Teams with `agency()`
 
-Use the streamlined APIs when you want AI SDK-style text generation, image generation, or stateful sessions without wiring the full AgentOS runtime.
+`agency()` is the recommended starting point for any task that benefits from
+multiple specialised agents.  Three lines to go from prompt to a coordinated
+research-and-writing pipeline:
+
+```typescript
+import { agency } from '@framers/agentos';
+
+const team = agency({
+  agents: {
+    researcher: { instructions: 'Find relevant facts.' },
+    writer:     { instructions: 'Write a clear, concise summary.' },
+  },
+  strategy: 'sequential',
+});
+
+const result = await team.generate('Summarise recent advances in fusion energy.');
+console.log(result.text);
+```
+
+Set `OPENAI_API_KEY` (or another provider's key) and the agency auto-detects the
+provider.  All five strategies are available out of the box:
+
+| Strategy | What it does |
+|---|---|
+| `sequential` | Agents run in order; each receives the previous output as context |
+| `parallel` | All agents run concurrently; results are merged by a synthesis step |
+| `debate` | Agents argue and refine a shared answer over multiple rounds |
+| `review-loop` | One agent drafts, another reviews and requests revisions |
+| `hierarchical` | A coordinator dispatches sub-tasks to specialist agents at runtime |
+
+Add guardrails, HITL, resource controls, and observability in the same config
+object — see [`docs/AGENCY_API.md`](./docs/AGENCY_API.md) for the full reference.
+
+### Single-Agent and Low-Level Helpers
+
+Use the streamlined helpers when you want AI SDK-style text generation, image
+generation, or a single stateful session without a multi-agent team.
 
 ```typescript
 import { agent, generateImage, generateText, streamText } from '@framers/agentos';
 
-// Provider-first: set provider, AgentOS picks the best default model automatically.
+// Provider-first: AgentOS picks the best default model automatically.
 // Requires OPENAI_API_KEY (or the matching env var) to be set.
 const quick = await generateText({
   provider: 'openai',
@@ -219,8 +257,7 @@ With `enabled: true`, AgentOS writes to the shared home ledger at `~/.framers/us
 
 Built-in image providers: `openai`, `openrouter`, `stability`, and `replicate`.
 
-Use `providerOptions` when you need provider-native controls without leaving the
-high-level API:
+Use `providerOptions` when you need provider-native controls without leaving the high-level API:
 
 ```typescript
 const poster = await generateImage({
@@ -239,9 +276,11 @@ const poster = await generateImage({
 
 Runnable examples: [`examples/high-level-api.mjs`](./examples/high-level-api.mjs), [`examples/generate-image.mjs`](./examples/generate-image.mjs)
 
-Use `AgentOS` directly when you need personas, chunk-level streaming events, extensions, workflows, multi-agent orchestration, or full runtime lifecycle control.
+### Advanced: AgentGraph and Full Runtime
 
-### Low-Level Runtime API
+Use `AgentGraph` or the full `AgentOS` runtime when you need programmatic graph
+construction with custom edge callbacks, extensions, workflow DSL, personas,
+chunk-level streaming events, or full runtime lifecycle control.
 
 ```typescript
 import { AgentOS, AgentOSResponseChunkType } from '@framers/agentos';
@@ -261,6 +300,10 @@ for await (const chunk of agent.processRequest({
 }
 ```
 
+See [`docs/AGENT_GRAPH.md`](./docs/AGENT_GRAPH.md) for the `AgentGraph` programmatic
+graph builder and [`docs/WORKFLOW_DSL.md`](./docs/WORKFLOW_DSL.md) for the workflow
+DSL.
+
 ---
 
 ## System Architecture
@@ -1857,10 +1900,12 @@ Wildcard exports support paths up to 4 levels deep:
 
 ## Internal Documentation
 
-The `docs/` directory contains 25 detailed specification documents:
+The `docs/` directory contains specification and reference documents:
 
 | Document | Description |
 |----------|-------------|
+| [`AGENCY_API.md`](docs/AGENCY_API.md) | `agency()` reference: all 5 strategies, HITL, guardrails, RAG, voice, nested agencies, full-featured example |
+| [`HIGH_LEVEL_API.md`](docs/HIGH_LEVEL_API.md) | `generateText()`, `streamText()`, `generateImage()`, single `agent()` |
 | [`ARCHITECTURE.md`](docs/ARCHITECTURE.md) | Complete system architecture with data flow diagrams |
 | [`SAFETY_PRIMITIVES.md`](docs/SAFETY_PRIMITIVES.md) | Circuit breaker, cost guard, stuck detection, dedup API reference |
 | [`PLANNING_ENGINE.md`](docs/PLANNING_ENGINE.md) | ReAct reasoning, multi-step task planning specification |

package/dist/api/agency.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @file agency.ts
+ * Multi-agent agency factory for the AgentOS high-level API.
+ *
+ * `agency()` accepts an {@link AgencyOptions} configuration, compiles the
+ * requested orchestration strategy, wires resource controls, and returns a
+ * single {@link Agent}-compatible interface that coordinates all sub-agents.
+ *
+ * The returned instance exposes `generate`, `stream`, `session`, `usage`, and
+ * `close` — identical surface to a single `agent()` instance — so callers can
+ * swap between them transparently.
+ *
+ * @example
+ * ```ts
+ * import { agency, hitl } from '@framers/agentos';
+ *
+ * const myAgency = agency({
+ *   model: 'openai:gpt-4o',
+ *   strategy: 'sequential',
+ *   agents: {
+ *     researcher: { instructions: 'Find relevant information.' },
+ *     writer:     { instructions: 'Write a clear summary.' },
+ *   },
+ *   controls: { maxTotalTokens: 50_000, onLimitReached: 'warn' },
+ *   hitl: { approvals: { beforeTool: ['delete'] }, handler: hitl.autoApprove() },
+ * });
+ *
+ * const result = await myAgency.generate('Summarise recent AI research.');
+ * console.log(result.text);
+ * ```
+ */
+import type { AgencyOptions, Agent } from './types.js';
+/**
+ * Creates a multi-agent agency that coordinates a named roster of sub-agents
+ * using the specified orchestration strategy.
+ *
+ * The agency validates configuration immediately and throws an
+ * {@link AgencyConfigError} on any structural problem so issues surface at
+ * wiring time rather than the first call.
+ *
+ * @param opts - Full agency configuration including the `agents` roster, optional
+ *   `strategy`, `controls`, `hitl`, and `observability` settings.
+ * @returns An {@link Agent} instance whose `generate` / `stream` / `session` methods
+ *   invoke the compiled strategy over the configured sub-agents.
+ * @throws {AgencyConfigError} When the configuration is structurally invalid
+ *   (e.g. no agents defined, emergent enabled without hierarchical strategy,
+ *   HITL approvals configured without a handler, parallel/debate without a
+ *   synthesis model).
+ */
+export declare function agency(opts: AgencyOptions): Agent;
+//# sourceMappingURL=agency.d.ts.map

package/dist/api/agency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agency.d.ts","sourceRoot":"","sources":["../../src/api/agency.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAGH,OAAO,KAAK,EACV,aAAa,EACb,KAAK,EAON,MAAM,YAAY,CAAC;AAOpB;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,aAAa,GAAG,KAAK,CA0PjD"}