docs(agency): add graph strategy docs, README, and example

- AGENCY_API.md: new ### graph section with dependsOn, auto-detection,
  topo sort tiers, concurrent execution, cycle detection, full example
- README.md: add graph row to strategy table + 9-line code example
- examples/agency-graph.mjs: runnable 4-agent research team DAG with
  both generate() and streaming examples

Author: jddunn

README.md

@@ -186,6 +186,22 @@ provider.  All five strategies are available out of the box:
 | `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 |
+| `graph` | Explicit dependency DAG via `dependsOn`; tiers run concurrently |
+
+**Graph strategy** — declare dependencies between agents and let the orchestrator
+handle topological ordering and concurrent execution:
+
+```typescript
+const team = agency({
+  agents: {
+    researcher:  { instructions: 'Research the topic.' },
+    writer:      { instructions: 'Write an article.',       dependsOn: ['researcher'] },
+    illustrator: { instructions: 'Describe illustrations.', dependsOn: ['researcher'] },
+    reviewer:    { instructions: 'Review everything.',      dependsOn: ['writer', 'illustrator'] },
+  },
+  strategy: 'graph', // auto-detected when any agent has dependsOn
+});
+```
 
 Add guardrails, HITL, resource controls, observability, `listen()` for voice
 transport, `connect()` for channel adapters, RAG context injection, and real

docs/AGENCY_API.md

@@ -186,6 +186,86 @@ const team = agency({
 const { text } = await team.generate('Explain and demonstrate the quicksort algorithm.');
 ```
 
+### graph
+
+Agents declare explicit dependencies via `dependsOn`.  The orchestrator
+topologically sorts agents into tiers and runs each tier concurrently.  Every
+agent receives the original user prompt plus the concatenated plain-text outputs
+of its direct dependencies.
+
+**Auto-detection:** when _any_ agent in the roster has a `dependsOn` array, the
+strategy is automatically set to `'graph'` — you don't need to specify it
+explicitly (though doing so is fine).
+
+**Cycle detection:** the orchestrator validates the dependency DAG at
+construction time and throws if it contains a cycle.
+
+**Context passing:** each agent's prompt is assembled as:
+
+```
+<original user prompt>
+
+--- Output from <dependencyName> ---
+<plain text output>
+```
+
+There is no expression language (no `$steps.<name>` references).  Each agent
+simply receives plain text from its predecessors.
+
+#### Agent config — `dependsOn`
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `dependsOn` | `string[]` | `[]` | Names of agents in the same agency that must complete before this agent runs.  Agents with no `dependsOn` are roots and execute first. |
+
+#### Full example — research team
+
+```typescript
+const team = agency({
+  model: 'openai:gpt-4o',
+  agents: {
+    // Tier 0 — no dependencies, runs first
+    researcher: {
+      instructions: 'Research the topic thoroughly. Provide facts, statistics, and sources.',
+    },
+
+    // Tier 1 — both depend on researcher, run concurrently
+    writer: {
+      instructions: 'Write a polished article based on the research provided.',
+      dependsOn: ['researcher'],
+    },
+    illustrator: {
+      instructions: 'Describe 3 illustrations that would complement the article.',
+      dependsOn: ['researcher'],
+    },
+
+    // Tier 2 — depends on both writer and illustrator, runs last
+    reviewer: {
+      instructions: 'Review the article and illustrations for consistency and accuracy.',
+      dependsOn: ['writer', 'illustrator'],
+    },
+  },
+  strategy: 'graph', // optional — auto-detected from dependsOn
+});
+
+const { text, agentCalls } = await team.generate('Write about the James Webb Space Telescope.');
+console.log(text);
+console.log(agentCalls.map(c => `${c.agent} (${c.durationMs}ms)`));
+// researcher (2100ms)
+// writer (1800ms)        — ran concurrently with illustrator
+// illustrator (1200ms)   — ran concurrently with writer
+// reviewer (1500ms)
+```
+
+#### Streaming
+
+```typescript
+const stream = team.stream('Write about the James Webb Space Telescope.');
+for await (const chunk of stream.textStream) {
+  process.stdout.write(chunk);
+}
+```
+
 ---
 
 ## Adaptive Mode

examples/agency-graph.mjs

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+// Example: agency() with graph strategy — explicit agent dependencies
+//
+// The graph strategy topologically sorts agents into tiers based on their
+// `dependsOn` declarations and executes each tier concurrently.  Every agent
+// receives the original prompt plus the plain-text outputs of its dependencies.
+//
+// DAG for this example:
+//
+//   researcher (tier 0)
+//       |
+//   +---+---+
+//   |       |
+//  writer  illustrator  (tier 1 — concurrent)
+//   |       |
+//   +---+---+
+//       |
+//    reviewer (tier 2)
+//
+// Usage:
+//   export OPENAI_API_KEY="sk-..."
+//   node examples/agency-graph.mjs
+
+import { agency } from '../dist/index.js';
+
+const provider = process.env.AGENTOS_PROVIDER || 'openai';
+
+async function main() {
+  const team = agency({
+    provider,
+    agents: {
+      // Tier 0 — no dependencies, runs first
+      researcher: {
+        instructions:
+          'You are a meticulous researcher. Given a topic, gather key facts, ' +
+          'statistics, and credible sources. Output a structured research brief.',
+      },
+
+      // Tier 1 — both depend on researcher, run concurrently
+      writer: {
+        instructions:
+          'You are a skilled technical writer. Using the research brief provided, ' +
+          'write a clear, engaging article of roughly 300 words.',
+        dependsOn: ['researcher'],
+      },
+      illustrator: {
+        instructions:
+          'You are a visual designer. Using the research brief provided, describe ' +
+          '3 illustrations that would complement the article. For each, give a ' +
+          'title and a one-sentence description.',
+        dependsOn: ['researcher'],
+      },
+
+      // Tier 2 — depends on both writer and illustrator, runs last
+      reviewer: {
+        instructions:
+          'You are a senior editor. Review the article and the illustration ' +
+          'descriptions for factual accuracy, consistency, and completeness. ' +
+          'Output a final verdict with any suggested corrections.',
+        dependsOn: ['writer', 'illustrator'],
+      },
+    },
+    strategy: 'graph', // optional — auto-detected when any agent has dependsOn
+  });
+
+  // --- Non-streaming run ------------------------------------------------
+  console.log('=== agency() graph strategy — generate() ===\n');
+
+  const result = await team.generate(
+    'Explain the significance of the James Webb Space Telescope.',
+  );
+
+  console.log(result.text);
+  console.log('\n--- Agent calls ---');
+  for (const call of result.agentCalls) {
+    console.log(`  ${call.agent} — ${call.durationMs}ms`);
+  }
+  console.log(`\nTotal tokens: ${result.usage.totalTokens}`);
+
+  // --- Streaming run ----------------------------------------------------
+  console.log('\n=== agency() graph strategy — stream() ===\n');
+
+  const stream = team.stream(
+    'Summarise recent breakthroughs in quantum computing.',
+  );
+
+  for await (const chunk of stream.textStream) {
+    process.stdout.write(chunk);
+  }
+  process.stdout.write('\n');
+
+  await team.close();
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exitCode = 1;
+});