@graph-compose/client 1.0.0 → 1.0.3

package/README.md

@@ -1,646 +1,1119 @@
 # @graph-compose/client
 
-Welcome! 👋 This is the Graph Compose client SDK, designed to help you build, validate, and execute workflow graphs using a fluent, type-safe builder pattern in TypeScript.
-
-This package works hand-in-hand with `@graph-compose/core`, which defines the underlying structure and validation schemas for workflows. You'll use `@graph-compose/client` to programmatically construct these workflow graphs, starting with basic HTTP operations and dependencies.
-
+A fluent TypeScript client for building declarative, Temporal-orchestrated workflows. Compose HTTP-based microservices or multi-agent AI systems with a simple, type-safe API.
 
 ## Features
 
-*   🏗️ **Fluent Builder API:** Easily define nodes (like `http` requests) and their configurations using method chaining.
-*   🔗 **Dependency Management:** Explicitly define dependencies between nodes.
-*   ✅ **Built-in Validation:** Leverages `@graph-compose/core` schemas to validate your graph definition locally.
-*   🚀 **Workflow Execution:** Provides methods to run your defined workflows asynchronously (`execute`, recommended) or synchronously (`executeSync`).
-*   🔒 **Type Safety:** Full TypeScript support for confidence in your workflow definitions.
-*   🔄 **Expression Support:** Utilize `{{ }}` expressions within node configurations (e.g., URLs, headers), powered by `@graph-compose/core`.
-*   *(Support for Agents and Tools is also available - see advanced documentation)*
-*   ⏱️ **Timeouts & Retries:** Configure detailed retry policies and timeouts (`startToClose`, `scheduleToClose`) for nodes and tools.
-*   ⚙️ **Workflow Configuration:** Set global workflow settings like execution timeouts (`withWorkflowConfig`).
-*   🔀 **Conditional Execution:** Define complex branching logic for HTTP nodes (`withConditions`).
-*   🛡️ **Schema Validation:** Apply Zod-based input/output validation schemas to HTTP nodes (`withValidation`).
-
-## API Reference & Documentation
-
-> **Note:** This document focuses specifically on the `@graph-compose/client` SDK for building workflows programmatically. For broader platform documentation, conceptual guides, API schemas, and examples, please visit the main Graph Compose site: [graphcompose.io](https://graphcompose.io).
-
-*   **Guides & Overviews:** For conceptual guides, integration examples, and broader platform documentation, visit the main Graph Compose documentation site: [graphcompose.io/docs](https://graphcompose.io/docs).
-*   **Workflow API Schemas:** For the definitive source of truth on the backend Workflow API request/response schemas (based on Zod/OpenAPI), see: [graphcompose.io/workflows](https://graphcompose.io/workflows).
-
-## Table of Contents
-
-- [Features](#features)
-- [API Reference & Documentation](#api-reference--documentation)
-- [Installation](#installation)
-- [Quick Start: Building a Simple HTTP Workflow](#quick-start-building-a-simple-http-workflow)
-- [Method Summary](#method-summary)
-- [Core Concepts](#core-concepts)
-- [Defining Node Types](#defining-node-types)
-- [Defining Tool Types (for Agents)](#defining-tool-types-for-agents)
-- [Workflow Configuration](#workflow-configuration)
-- [Validation](#validation)
-- [Execution](#execution)
-- [Getting the Workflow Definition](#getting-the-workflow-definition)
-- [Interacting with Existing Workflows (API)](#interacting-with-existing-workflows-api)
-- [Full Example: Putting it Together](#full-example-putting-it-together)
-- [Contributing](#contributing)
-- [License](#license)
+- 🔗 **HTTP Workflow Orchestration** - Chain HTTP services with dependency management
+- 🤖 **Multi-Agent AI Workflows** - Build ADK (Agent Development Kit) hierarchies with LLMs, tools, and orchestrators
+- 🎯 **Type-Safe Builder Pattern** - Fluent API with full TypeScript support
+- ✨ **JSONata Templating** - Dynamic parameter resolution with `{{ }}` expressions
+- 🔄 **Automatic Retry & Error Handling** - Configure retry policies and error boundaries
+- ✅ **Built-in Validation** - Zod-based schema validation for workflows
+- 🧪 **Temporal Integration** - Native support for Temporal workflow execution
 
 ## Installation
 
 ```bash
 npm install @graph-compose/client @graph-compose/core
 # or
+pnpm add @graph-compose/client @graph-compose/core
+# or
 yarn add @graph-compose/client @graph-compose/core
 ```
-*(Note: `@graph-compose/core` is a required peer dependency.)*
 
-## Quick Start: Building a Simple HTTP Workflow
+## Authentication
 
-```typescript
-import { GraphCompose } from '@graph-compose/client';
-import { z } from 'zod'; // Often used with core schemas
+The client requires an API token to execute workflows against the GraphCompose API:
 
-// Initialize the client (token is required)
-// Reads from process.env.GRAPH_COMPOSE_TOKEN if not provided
-const graph = new GraphCompose({
-  token: process.env.GRAPH_COMPOSE_TOKEN || 'your-api-token',
+```typescript
+// Option 1: Pass token in constructor
+const workflow = new GraphCompose({ 
+  token: 'your-api-token' 
 });
 
-// Define a simple workflow with three dependent HTTP steps
-try {
-  // Node 1: Fetch initial user data
-  graph.node('fetch_user')
-    .get('https://api.example.com/users/{{ context.userId }}')
-    .withHeaders({ 'X-Request-ID': '{{ $uuid() }}' })
-    .withStartToCloseTimeout('5s')
-    .end(); // <-- Required: Finalize the 'fetch_user' node definition
-
-  // Node 2: Fetch user's orders, depending on the first node
-  graph.node('fetch_orders')
-    .withDependencies(['fetch_user']) // This node runs after 'fetch_user' completes
-    .get('https://api.example.com/orders?userId={{ results.fetch_user.id }}')
-    .end(); // <-- Required: Finalize the 'fetch_orders' node definition
-
-  // Node 3: Post-process orders
-  graph.node('process_orders')
-    .withDependencies(['fetch_orders']) // Depends on 'fetch_orders'
-    .post('https://api.example.com/process')
-    .withBody({
-      orderData: '{{ results.fetch_orders }}',
-      processingTimestamp: '{{ $now() }}'
-    })
-    .end(); // <-- Required: Finalize the 'process_orders' node definition
+// Option 2: Set environment variable
+// GRAPH_COMPOSE_TOKEN=your-api-token
+const workflow = new GraphCompose();
+```
 
-  // (Optional) Explicitly validate the workflow definition locally
-  // Requires all nodes/tools to be finalized with .end()
-  const validation = graph.validate();
-  if (!validation.isValid) {
-    console.error("Workflow validation failed:", validation.errors);
-    throw new Error("Invalid workflow definition");
-  } else {
-    console.log("Local validation successful!");
-  }
+**API Endpoint:** `https://api.graphcompose.io/api/v1`
 
-  // Execute the workflow
-  // Requires all nodes/tools to be finalized with .end()
-  console.log('Executing workflow...');
-  const apiResponse = await graph.execute({
-    context: { // Initial data for the workflow run
-      userId: 'user-789'
-    },
-    // webhookUrl: 'https://my-service.com/updates' // Optional webhook
-  });
+Get your API token from the [GraphCompose Dashboard](https://app.graphcompose.io)
 
-  if (apiResponse.success && apiResponse.data) {
-    console.log('Workflow execution started successfully:', apiResponse.data);
-    // Access workflowId via apiResponse.data.workflowId
-  } else {
-    console.error(`Workflow execution failed: ${apiResponse.message}`);
-  }
+## Quick Start
 
-} catch (error) {
-  console.error('Error building or executing workflow:', error);
-  // Handle potential ZodErrors during build if schemas are used directly
-  if (error instanceof z.ZodError) {
-     console.error("Detailed Zod Errors:", error.errors);
+### End-to-End Example
+
+```typescript
+import { GraphCompose } from '@graph-compose/client';
+
+// 1. Build your workflow
+const workflow = new GraphCompose({ 
+  token: process.env.GRAPH_COMPOSE_TOKEN 
+})
+  .http('fetchData')
+    .get('https://api.example.com/data')
+    .end()
+  .http('processData')
+    .post('https://api.example.com/process')
+    .withBody({ data: '{{results.fetchData}}' })
+    .dependsOn(['fetchData'])
+    .end();
+
+// 2. Validate it
+const validation = workflow.validate();
+if (!validation.isValid) {
+  throw new Error('Invalid workflow');
+}
+
+// 3. Execute it
+const result = await workflow.execute({
+  context: { userId: '123' }
+});
+
+// 4. Poll for completion and get results
+if (result.success && result.data) {
+  const workflowId = result.data.workflowId;
+  
+  // Poll until complete
+  let status = 'RUNNING';
+  while (status === 'RUNNING') {
+    await new Promise(resolve => setTimeout(resolve, 1000));
+    const statusResult = await workflow.getWorkflowStatus(workflowId);
+    if (statusResult.success && statusResult.data) {
+      status = statusResult.data.status;
+    }
+  }
+  
+  // Get final results
+  const finalResult = await workflow.getWorkflowStatus(workflowId);
+  if (finalResult.success && finalResult.data?.status === 'COMPLETED') {
+    console.log('Results:', finalResult.data.execution_state);
   }
 }
 ```
 
+### Traditional HTTP Workflow
 
-## Method Summary
-
-This section provides a quick overview of the primary methods available on the `GraphCompose` instance, grouped by purpose.
+Build a workflow that chains multiple HTTP services:
 
-### Initialization
+```typescript
+import { GraphCompose } from '@graph-compose/client';
 
-| Method                      | Purpose                                                |
-| :-------------------------- | :----------------------------------------------------- |
-| `new GraphCompose(options?)` | Creates a new workflow builder instance. Requires API token. |
+const workflow = new GraphCompose({ 
+  token: 'your-api-token' 
+})
+  .http('fetchUser')
+    .get('https://api.example.com/users/{{userId}}')
+    .withHeaders({
+      'Authorization': 'Bearer {{$secret("api_token")}}'
+    })
+    .end()
+  .http('enrichProfile')
+    .post('https://api.example.com/enrich')
+    .withBody({
+      userId: '{{results.fetchUser.id}}',
+      email: '{{results.fetchUser.email}}'
+    })
+    .dependsOn(['fetchUser'])
+    .end()
+  .build();
+```
 
-### Component Definition
+### ADK Multi-Agent Workflow
 
-These methods start the definition of a new workflow component and return a **builder instance**. You **must** call `.end()` on the builder to finalize the component.
+Build an AI agent workflow with tools and orchestration:
 
-| Method                              | Purpose                                           |
-| :---------------------------------- | :------------------------------------------------ |
-| `node(id)`                          | Starts defining a standard HTTP node.             |
-| `agent(id)`                         | Starts defining an Agent node, which orchestrates calls to your custom HTTP endpoint. |
-| `errorBoundary(id, protectedNodes)` | Starts defining an Error Boundary node.           |
-| `tool(id)`                          | Starts defining a Tool (HTTP or Graph based).     |
+```typescript
+import { 
+  GraphCompose,
+  AdkWorkflowBuilder,
+  createLlmAgent,
+  createHttpTool
+} from '@graph-compose/client';
+
+// Define the agent workflow
+const agentWorkflow = new AdkWorkflowBuilder()
+  .agent(createLlmAgent({
+    id: 'assistant',
+    httpConfig: {
+      url: 'https://api.example.com/llm',
+      method: 'POST'
+    },
+    tools: ['searchTool'],
+    outputKey: 'assistant_response'
+  }))
+  .httpTool(createHttpTool({
+    id: 'searchTool',
+    httpConfig: {
+      url: 'https://api.example.com/search',
+      method: 'POST',
+      body: {
+        query: '{{state.user_query}}'
+      }
+    }
+  }))
+  .setRootAgent('assistant')
+  .build();
+
+// Create the workflow node
+const workflow = new GraphCompose()
+  .adk('aiAgent')
+    .withWorkflow(agentWorkflow)
+    .withInitialPrompt('Hello! How can I help you today?')
+    .withMaxCycles(10)
+    .end()
+  .build();
+```
 
-### Node/Tool Configuration (on Builder)
+## HTTP Workflow Builder
 
-These are examples of methods called on the **builder instance** returned by the definition methods above to configure the specific component.
+### Basic HTTP Methods
 
-| Method                        | Purpose                                                                      |
-| :---------------------------- | :--------------------------------------------------------------------------- |
-| `.get(url)`, `.post(url)`, etc. | Sets the HTTP method and URL (HTTP Nodes/Tools).                             |
-| `.withHeaders(headers)`       | Adds HTTP headers (HTTP Nodes/Tools).                                        |
-| `.withBody(body)`             | Sets the request body (HTTP Nodes/Tools).                                    |
-| `.withDependencies(ids)`      | Specifies prerequisite nodes (HTTP & Agent Nodes).                           |
-| `.withRetries(policy)`        | Configures automatic retry behavior (HTTP Nodes/Tools).                      |
-| `.withTools(ids)`             | (Agent builder) Declares tools available for the agent's logic to call.         |
-| `.addTool(tool)`              | (Agent builder) Adds a single tool available for the agent's logic to call. |
-| `.withMaxIterations(n)`       | (Agent builder) Sets the maximum number of agent iterations.                 |
-| `.graph(callback)`            | (Tool builder) Defines a sub-graph for a Graph tool.                         |
-| `.description(text)`          | (Tool builder) Sets the description used by agents to select the tool.       |
-| `.withConditions(conds)`      | (Node builder) Adds conditional execution logic (HTTP Nodes only).           |
-| `.withValidation(schema)`     | (Node builder) Adds input/output schema validation (HTTP Nodes only).        |
-| `.withStartToCloseTimeout(d)` | Sets max time for one execution attempt (HTTP Nodes/Tools).                  |
-| `.withScheduleToCloseTimeout(d)`| Sets max time from schedule to completion (incl. queue) (HTTP Nodes/Tools). |
+```typescript
+const builder = new GraphCompose();
+
+// GET request
+builder.http('getUser')
+  .get('https://api.example.com/users/123')
+  .end();
+
+// POST request
+builder.http('createUser')
+  .post('https://api.example.com/users')
+  .withBody({ name: 'John', email: 'john@example.com' })
+  .end();
+
+// PUT, PATCH, DELETE
+builder.http('updateUser').put('...').end();
+builder.http('patchUser').patch('...').end();
+builder.http('deleteUser').delete('...').end();
+```
 
-### Finalization (on Builder)
+### Headers and Authentication
 
-This method is called on the **builder instance** to finalize the component's definition.
+```typescript
+builder.http('secureRequest')
+  .post('https://api.example.com/data')
+  .withHeaders({
+    'Authorization': 'Bearer {{$secret("api_token")}}',
+    'X-Request-ID': '{{context.requestId}}',
+    'Content-Type': 'application/json'
+  })
+  .end();
+```
 
-| Method   | Purpose                                                               |
-| :------- | :-------------------------------------------------------------------- |
-| `.end()` | Finalizes the current node/tool definition and adds it to the graph. | 
+### Dynamic Body and Parameters
 
-### Workflow Configuration
+```typescript
+builder.http('processOrder')
+  .post('https://api.example.com/orders')
+  .withBody({
+    orderId: '{{results.createOrder.id}}',
+    userId: '{{context.userId}}',
+    items: '{{results.fetchCart.items}}',
+    total: '{{results.calculateTotal.amount}}'
+  })
+  .withParams({
+    async: 'true',
+    priority: '{{context.priority}}'
+  })
+  .end();
+```
 
-These methods configure the overall workflow. They must be called when no node or tool builder is active.
+### Dependencies and Ordering
 
-| Method                       | Purpose                                           |
-| :--------------------------- | :------------------------------------------------ |
-| `withContext(context)`       | Sets global context data accessible to all nodes. |
-| `withWebhookUrl(url)`        | Sets a webhook URL for workflow event updates.    |
-| `withWorkflowConfig(config)` | Sets global workflow settings (e.g., timeouts).   |
+```typescript
+// Sequential execution
+builder
+  .http('step1').get('...').end()
+  .http('step2').post('...').dependsOn(['step1']).end()
+  .http('step3').post('...').dependsOn(['step2']).end();
+
+// Parallel execution (no dependencies)
+builder
+  .http('fetchUserData').get('...').end()
+  .http('fetchOrderData').get('...').end()
+  .http('fetchPreferences').get('...').end();
+
+// Fan-out then fan-in
+builder
+  .http('fetchData1').get('...').end()
+  .http('fetchData2').get('...').end()
+  .http('aggregate')
+    .post('...')
+    .dependsOn(['fetchData1', 'fetchData2'])
+    .end();
+```
 
-### Validation
+### Activity Configuration
 
-These methods validate the workflow definition. They must be called when no node or tool builder is active.
+Configure Temporal activity behavior:
 
-| Method          | Purpose                                                  |
-| :-------------- | :------------------------------------------------------- |
-| `validate()`    | Performs local, client-side validation of the structure. |
-| `validateApi()` | Sends the definition to the API for server-side validation. |
+```typescript
+builder.http('reliableCall')
+  .post('https://api.example.com/process')
+  .withStartToCloseTimeout('30s')
+  .withScheduleToCloseTimeout('5m')
+  .withRetries({
+    maximumAttempts: 5,
+    initialInterval: '1s',
+    backoffCoefficient: 2.0,
+    maximumInterval: '30s'
+  })
+  .end();
+```
 
-### Execution
+### Error Boundaries
 
-These methods execute the workflow. They must be called when no node or tool builder is active.
+Wrap nodes with error handling:
 
-| Method                 | Purpose                                                               |
-| :--------------------- | :-------------------------------------------------------------------- |
-| `execute(options?)`    | Executes the workflow asynchronously, returning immediately.        |
-| `executeSync(options?)`| Executes the workflow synchronously, waiting for completion.        |
+```typescript
+builder
+  .http('riskyOperation')
+    .post('https://api.example.com/risky')
+    .end()
+  .errorBoundary('handleError')
+    .protects(['riskyOperation'])
+    .onError(
+      builder => builder
+        .http('fallback')
+          .post('https://api.example.com/fallback')
+          .end()
+    )
+    .end();
+```
 
-### Retrieving Definition
+### Conditional Branching
 
-These methods retrieve the built workflow definition. They must be called when no node or tool builder is active.
+```typescript
+builder
+  .http('checkStatus')
+    .get('https://api.example.com/status')
+    .end()
+  .http('handleSuccess')
+    .post('...')
+    .runWhen({
+      condition: '{{results.checkStatus.state = "completed"}}'
+    })
+    .dependsOn(['checkStatus'])
+    .end()
+  .http('handleFailure')
+    .post('...')
+    .runWhen({
+      condition: '{{results.checkStatus.state = "failed"}}'
+    })
+    .dependsOn(['checkStatus'])
+    .end();
+```
 
-| Method          | Purpose                                                                   |
-| :-------------- | :------------------------------------------------------------------------ |
-| `getWorkflow()` | Returns the complete workflow definition object.                            |
-| `toJSON()`      | Alias for `getWorkflow()`; standard method for `JSON.stringify()`.          |
+## ADK Agent Workflows
 
-### API Interaction
+### Agent Types
 
-These methods interact with existing workflow instances via the API.
+#### LLM Agent
+The primary agent that interacts with language models:
 
-| Method                                | Purpose                                              |
-| :------------------------------------ | :--------------------------------------------------- |
-| `getWorkflowStatus(workflowId)`       | Retrieves the current status and details of a workflow. |
-| `terminateWorkflow(workflowId, opts?)`| Requests termination of a running workflow.         |
+```typescript
+import { createLlmAgent } from '@graph-compose/client';
+
+createLlmAgent({
+  id: 'assistant',
+  httpConfig: {
+    url: 'https://api.example.com/llm',
+    method: 'POST'
+  },
+  tools: ['searchTool', 'calculatorTool'],
+  outputKey: 'assistant_response',
+  activityConfig: {
+    startToCloseTimeout: '30s',
+    retryPolicy: {
+      maximumAttempts: 3
+    }
+  }
+})
+```
 
-## Core Concepts
+#### Sequential Agent
+Executes sub-agents in order:
 
-### The `GraphCompose` Builder
+```typescript
+import { createSequentialAgent, createSubAgentReference } from '@graph-compose/client';
+
+createSequentialAgent({
+  id: 'pipeline',
+  httpConfig: {
+    url: 'https://api.example.com/orchestrate',
+    method: 'POST'
+  },
+  subAgents: [
+    createSubAgentReference('extractor'),
+    createSubAgentReference('transformer'),
+    createSubAgentReference('loader')
+  ]
+})
+```
 
-This is the main class you'll instantiate. It holds the state of the workflow being built.
+#### Parallel Agent
+Executes sub-agents concurrently:
 
 ```typescript
-import { GraphCompose } from '@graph-compose/client';
+import { createParallelAgent } from '@graph-compose/client';
+
+createParallelAgent({
+  id: 'fanOut',
+  httpConfig: {
+    url: 'https://api.example.com/orchestrate',
+    method: 'POST'
+  },
+  subAgents: [
+    createSubAgentReference('analyzer1'),
+    createSubAgentReference('analyzer2'),
+    createSubAgentReference('analyzer3')
+  ]
+  // Note: ParallelAgent does not support outputKey
+  // Individual sub-agents should have their own outputKeys
+})
+```
 
-// Reads from process.env.GRAPH_COMPOSE_TOKEN if not provided
-const graph = new GraphCompose({
-  token: process.env.GRAPH_COMPOSE_TOKEN || 'your-api-token',
-});
+#### Loop Agent
+Repeats sub-agents with iteration limits:
+
+```typescript
+import { createLoopAgent } from '@graph-compose/client';
+
+createLoopAgent({
+  id: 'retryLoop',
+  httpConfig: {
+    url: 'https://api.example.com/orchestrate',
+    method: 'POST'
+  },
+  subAgents: [
+    createSubAgentReference('worker')
+  ],
+  maxAgentLoopIterations: 5,
+  loopExitCondition: '{{state.task_completed = true}}',
+  outputKey: 'loop_result'
+})
 ```
 
-### Defining Nodes and Tools - The `.end()` Method
+### Tools
 
-You define the components of your workflow (nodes and tools) by chaining methods starting with `graph.node('node_id')`, `graph.agent('agent_id')`, `graph.errorBoundary('boundary_id', [...])`, or `graph.tool('tool_id')`.
+#### HTTP Tool
+Execute external HTTP services:
 
-*   **Configuration:** Chain methods like `.get()`, `.post()`, `.withHeaders()`, `.withBody()`, `.withRetries()`, `.withDependencies()`, etc., to configure the node or tool.
-*   **Finalization:** **Crucially, you MUST call `.end()`** after configuring each node or tool. This finalizes its definition, adds it to the graph, and returns control to the main `GraphCompose` instance. Attempting to start defining a new component or perform graph-level operations (like `validate` or `execute`) before calling `.end()` on the *current* component builder will result in an error.
+```typescript
+import { createHttpTool } from '@graph-compose/client';
+
+createHttpTool({
+  id: 'searchTool',
+  httpConfig: {
+    url: 'https://api.example.com/search',
+    method: 'POST',
+    body: {
+      query: '{{state.user_query}}',
+      filters: '{{state.filters}}'
+    },
+    headers: {
+      'Authorization': 'Bearer {{$secret("search_api_key")}}'
+    }
+  },
+  outputKey: 'search_results'
+})
+```
+
+#### Agent Tool
+Delegate to another agent (specialist pattern):
 
 ```typescript
-// Correct usage with .end()
-graph
-  .node('fetch_data') // Start defining node 'fetch_data'
-    .get('https://api.example.com/data')
-    .withStartToCloseTimeout('10s')
-    .end(); // Finalize 'fetch_data' and return to the main graph builder
+import { createAgentTool } from '@graph-compose/client';
+
+createAgentTool({
+  id: 'specialistTool',
+  targetAgentId: 'specialist',
+  skipSummarization: false,
+  outputKey: 'specialist_result'
+})
+```
 
-graph
-  .node('process_data') // Start defining node 'process_data'
-    .withDependencies(['fetch_data']) // Depends on 'fetch_data'
-    .post('https://api.example.com/process')
-    .withBody({ input: '{{ results.fetch_data }}' })
-    .end(); // Finalize 'process_data'
+### Complete ADK Example
 
-// Now it's safe to perform graph-level operations like validate or execute
-// const validation = graph.validate();
-// const result = await graph.execute();
+```typescript
+import {
+  GraphCompose,
+  AdkWorkflowBuilder,
+  createLlmAgent,
+  createSequentialAgent,
+  createHttpTool,
+  createAgentTool,
+  createSubAgentReference
+} from '@graph-compose/client';
+
+// Build the agent hierarchy
+const workflow = new AdkWorkflowBuilder()
+  // Main coordinator agent
+  .agent(createLlmAgent({
+    id: 'coordinator',
+    httpConfig: {
+      url: 'https://api.example.com/llm',
+      method: 'POST'
+    },
+    tools: ['researchTool', 'analysisTool'],
+    outputKey: 'coordinator_response'
+  }))
+  
+  // Research specialist
+  .agent(createLlmAgent({
+    id: 'researcher',
+    httpConfig: {
+      url: 'https://api.example.com/llm',
+      method: 'POST'
+    },
+    tools: ['searchTool'],
+    outputKey: 'research_results'
+  }))
+  
+  // Analysis specialist
+  .agent(createLlmAgent({
+    id: 'analyst',
+    httpConfig: {
+      url: 'https://api.example.com/llm',
+      method: 'POST'
+    },
+    outputKey: 'analysis_results'
+  }))
+  
+  // HTTP search tool
+  .httpTool(createHttpTool({
+    id: 'searchTool',
+    httpConfig: {
+      url: 'https://api.example.com/search',
+      method: 'POST'
+    },
+    outputKey: 'search_data'
+  }))
+  
+  // Agent tools for delegation
+  .agentTool(createAgentTool({
+    id: 'researchTool',
+    targetAgentId: 'researcher',
+    skipSummarization: false
+  }))
+  
+  .agentTool(createAgentTool({
+    id: 'analysisTool',
+    targetAgentId: 'analyst',
+    skipSummarization: false
+  }))
+  
+  // Set the entry point
+  .setRootAgent('coordinator')
+  
+  // Configure workflow-level settings
+  .withMaxCycles(20)
+  
+  .build();
+
+// Create the workflow
+const graph = new GraphCompose()
+  .adk('aiWorkflow')
+    .withWorkflow(workflow)
+    .withInitialPrompt('Research and analyze recent AI trends')
+    .withState({
+      user_id: 'user_123',
+      context: 'technology'
+    })
+    .end()
+  .build();
 ```
 
-## Defining Node Types
+## Advanced Patterns
 
-Nodes represent the primary steps or actions within your workflow. Remember to always finish defining a node with `.end()`.
+### Agent Handoff Pattern
 
-### HTTP Nodes
+Nested sub-agents for dynamic routing:
 
-These are the most basic type, used for making HTTP requests.
+```typescript
+createLlmAgent({
+  id: 'router',
+  httpConfig: { url: '...', method: 'POST' },
+  subAgents: [
+    // Nested agents for handoff
+    createLlmAgent({
+      id: 'sales_specialist',
+      httpConfig: { url: '...', method: 'POST' }
+    }),
+    createLlmAgent({
+      id: 'support_specialist',
+      httpConfig: { url: '...', method: 'POST' }
+    })
+  ]
+})
+```
+
+### Human-in-the-Loop (HITL)
+
+Agents can request human approval:
 
 ```typescript
-graph.node("fetch_user_data")
-  .description("Retrieves user details based on context ID.") // Optional description
-  .get("https://api.example.com/users/{{context.userId}}")
-  .withHeaders({ "Authorization": "Bearer YOUR_SERVICE_TOKEN" })
-  .withStartToCloseTimeout('5s') // Example timeout
-  .end(); // Required!
+// Your agent HTTP service returns:
+{
+  "content": [{"type": "text", "text": "Requesting approval..."}],
+  "hitl_request": {
+    "type": "approval",
+    "message": "Should I proceed with this action?",
+    "options": ["approve", "reject", "modify"]
+  }
+}
 ```
 
-### Agent Nodes
+### State Management
 
-Agent nodes orchestrate iterative calls to a user-defined HTTP endpoint. This endpoint implements the agent's logic (which might involve AI models) to process inputs, make decisions, and determine which Tools (other workflow nodes) to use.
+Access shared state across agents:
 
 ```typescript
-graph.agent("process_user_request")
-  .description("Handles user queries using available tools.") // Optional
-  .withMaxIterations(5) // Limit the number of tool calls/LLM turns
-  .withTools(["search_web", "summarize_content"]) // Reference tool IDs (defined separately)
-  .post("https://ai.example.com/process") // The endpoint hosting the agent logic
-  .withBody({ query: "{{context.userInput}}" })
-  .withDependencies(["fetch_user_data"]) // Can depend on other nodes
-  .end(); // Required!
+// Initialize state
+.withState({
+  user_preferences: { theme: 'dark' },
+  session_data: { authenticated: true }
+})
+
+// Access in agent HTTP configs
+.withBody({
+  user_theme: '{{state.user_preferences.theme}}',
+  auth_status: '{{state.session_data.authenticated}}'
+})
+
+// Agents save to state via outputKey
+.agent(createLlmAgent({
+  id: 'processor',
+  outputKey: 'processed_data', // Saved to state.processed_data
+  // ...
+}))
 ```
 
-### Error Boundary Nodes
+### Exit Flow Control
 
-These nodes execute *only* if one of the nodes they monitor fails. They are used for error handling and cleanup.
+Agents can terminate the workflow early:
 
 ```typescript
-graph.errorBoundary("api_error_handler", ["fetch_user_data", "process_user_request"]) // List of node IDs to monitor
-  .description("Logs errors from API calls.") // Optional
-  .post("https://my-service.com/log-error")
-  .withBody({
-    failedNodeId: '{{ error.nodeId }}',
-    errorMessage: '{{ error.message }}',
-    timestamp: '{{ $now() }}'
-   })
-  .end(); // Required!
+// Your agent HTTP service returns:
+{
+  "content": [{"type": "text", "text": "Task completed!"}],
+  "exit_flow": true  // Stops workflow execution
+}
 ```
 
-## Defining Tool Types (for Agents)
+## JSONata Templating
 
-Tools are functions or services that Agent Nodes can call to perform specific actions. Remember to always finish defining a tool with `.end()`.
+All string fields support JSONata expressions with `{{ }}` delimiters:
 
-### HTTP Tools
+### Accessing Results
 
-These are simple tools that make an HTTP request when called by an agent.
+```typescript
+'{{results.fetchUser.id}}'           // Node result
+'{{results.fetchUser.profile.name}}' // Nested property
+```
+
+### Accessing Context
 
 ```typescript
-graph.tool("search_web")
-  .description("Searches the web for a given query.") // Crucial for the agent to understand the tool
-  .post("https://api.search-provider.com/search")
-  .withBody({ query: "{{input.query}}" }) // 'input' contains agent-provided parameters
-  .withScheduleToCloseTimeout('15s') // Example timeout
-  .end(); // Required!
+'{{context.userId}}'       // Workflow context
+'{{context.tenantId}}'     // Any context value
+```
 
-graph.tool("summarize_content")
-  .description("Summarizes a provided block of text.")
-  .post("https://ai.example.com/summarize")
-  .withBody({ text: "{{input.text_to_summarize}}" })
-  .end(); // Required!
+### Accessing State (ADK)
+
+```typescript
+'{{state.user_query}}'              // Session state
+'{{state.preferences.language}}'    // Nested state
 ```
 
-### Graph Tools
+### Secrets
 
-These allow encapsulating a *sub-graph* as a tool. This sub-graph can contain multiple HTTP nodes.
+```typescript
+'{{$secret("api_key")}}'            // Secret reference
+'Bearer {{$secret("auth_token")}}'  // In strings
+```
+
+### JSONata Operators
 
 ```typescript
-graph.tool('data_processor')
-  .description('Validates and transforms input data using a multi-step process.')
-  .graph((subGraph) => { // Define the sub-graph structure
-    subGraph
-      .node('validate') // Nodes within the tool's sub-graph
-        .post('https://api.example.com/validate')
-        .withBody('{{ context.example_context }}') 
-        .end(); // End sub-graph node
-    subGraph
-      .node('transform')
-        .withDependencies(['validate']) // Dependencies within the sub-graph
-        .post('https://api.example.com/transform')
-        .withBody('{{ results.validate }}') // Results refer to nodes within the sub-graph
-        .end(); // End sub-graph node
-  }) // End of sub-graph definition
-  .end(); // <-- Required: Finalize the tool itself
+// Conditionals
+'{{results.status.code = 200 ? "success" : "failure"}}'
+
+// Arithmetic
+'{{results.price.amount * 1.1}}'
+
+// String operations
+'{{$uppercase(results.user.name)}}'
+'{{$substring(results.text, 0, 100)}}'
+
+// Array operations
+'{{$count(results.items)}}'
+'{{results.items[0].id}}'
 ```
 
-**Graph Tool Validation Rules:**
-- Graph tools can only contain HTTP nodes.
-- Graph tools must have at least one node defined (and ended).
-- Each graph tool runs as an isolated sub-workflow when invoked by an agent.
+## Validation
 
-### Assigning Tools to Agents
+### Automatic Validation
 
-You declare which Tools (defined elsewhere in the workflow) are available for your agent logic to request by referencing their IDs when defining the agent node.
+The builder performs comprehensive validation:
 
 ```typescript
-graph.agent('assistant')
-  .withMaxIterations(5)
-  .withTools(['search_web', 'data_processor']) // Reference the tools by their defined IDs
-  .post('https://api.example.com/agent')
-  // ... other agent configurations ...
-  .end(); // Required!
+const workflow = builder.build();
+const validation = builder.validate();
+
+if (!validation.isValid) {
+  validation.errors.forEach(err => {
+    console.error(err.message);
+  });
+}
 ```
 
-## Workflow Configuration
+### Validation Checks
 
-These methods modify the overall graph configuration and require that no node or tool builder is currently active (i.e., the previous builder must have called `.end()`).
+- ✅ **Node IDs**: Unique and valid format
+- ✅ **Dependencies**: Valid references, no circular deps
+- ✅ **HTTP Config**: Valid URLs, methods, headers
+- ✅ **JSONata**: Syntax validation in templates
+- ✅ **ADK Structure**: Agent/tool references, type constraints
+- ✅ **Schema Compliance**: Zod validation against core schemas
 
-```typescript
-// Assuming previous node/tool builders have called .end()
+### Manual Validation
 
-// Set initial data available to all nodes via 'context'
-graph.withContext({
-  userId: "user-123",
-  userInput: "Tell me about GraphCompose",
-});
+```typescript
+import { validateWorkflow } from '@graph-compose/client';
 
-// Specify a URL to receive webhook updates about the workflow's progress
-graph.withWebhookUrl("https://my-app.com/graph-compose-webhook");
+const result = validateWorkflow(workflow);
 
-// Set global workflow limits
-graph.withWorkflowConfig({
-  workflowExecutionTimeout: "1 hour" // Max total execution time
-  // workflowTaskTimeout: "1m" // Max time for a single step/task
-});
+if (!result.isValid) {
+  console.error('Validation failed:', result.errors);
+}
 ```
 
-## Validation
+## Executing Workflows
 
-Ensuring your workflow definition is correct before execution is crucial.
+### Local Validation (Client-Side)
 
-### Local Validation
+Validate workflow structure without making API calls:
 
-The client performs structural and configuration validation locally when you call `graph.validate()`. This includes checking for:
-*   Valid node/tool IDs and names.
-*   Dependency cycles.
-*   Correct agent configuration (like `max_iterations`).
-*   Valid JSONata expressions used in configurations.
-*   Graph Tool structure rules.
+```typescript
+const workflow = new GraphCompose({ token: 'your-token' })
+  .http('fetchData')
+    .get('https://api.example.com/data')
+    .end()
+  .build();
 
-This method requires all nodes and tools to have been finalized with `.end()`. Execution methods (`.execute()`, `.executeSync()`) also perform this validation internally.
+// Client-side validation (fast, no API call)
+const validation = workflow.validate();
 
-```typescript
-// Assuming all node/tool builders have called .end()
-const validationResult = graph.validate();
-if (!validationResult.isValid) {
-  console.error("Workflow validation failed locally:", validationResult.errors);
+if (!validation.isValid) {
+  console.error('Validation errors:', validation.errors);
 } else {
-  console.log("Local validation successful!");
+  console.log('Workflow is valid!');
 }
 ```
 
-### API Validation
+### Server-Side Validation
 
-You can also send the *current* workflow definition to the Graph Compose API for validation. This might catch additional issues specific to the execution environment.
+Validate against the GraphCompose API (includes tier limits and quota checks):
 
 ```typescript
-// Assuming all node/tool builders have called .end()
-async function validateWithApi() {
-  try {
-    // validateApi returns ApiResponse<ApiValidationResult | null>
-    const apiResponse = await graph.validateApi();
+const workflow = new GraphCompose({ token: 'your-token' })
+  .http('fetchData')
+    .get('https://api.example.com/data')
+    .end();
 
-    if (apiResponse.success && apiResponse.data) {
-      // Check the validation result within the data field
-      if (apiResponse.data.isValid) {
-        console.log("API validation successful!");
-      } else {
-        console.error("API validation failed:", apiResponse.data.errors);
-      }
-    } else {
-      // Handle cases where the API call itself failed (e.g., network error, auth error)
-      console.error(`API validation request failed: ${apiResponse.message}`);
-    }
-  } catch (error) {
-    console.error("Failed to call validation API:", error);
+try {
+  const apiResult = await workflow.validateApi();
+  
+  if (apiResult.success && apiResult.data?.isValid) {
+    console.log('✅ Workflow passed server validation');
+  } else {
+    console.error('❌ Validation failed:', apiResult.data?.errors);
   }
+} catch (error) {
+  console.error('API error:', error);
 }
-validateWithApi();
 ```
 
-## Execution
+**Endpoint:** `POST /workflows/validate`
 
-Once defined and validated, you can run your workflow. Execution methods require all nodes and tools to have been finalized with `.end()`.
+### Async Execution
 
-*   **Asynchronous (`execute`)**: This is the recommended method. It starts the workflow on the Graph Compose platform and immediately returns a `workflowId`. You can monitor progress via webhooks or by polling the status API.
+Start workflow execution and return immediately (recommended for long-running workflows):
 
-    ```typescript
-    // Assuming all node/tool builders have called .end()
-    async function startWorkflowAsync() {
-      try {
-        // Pass any runtime context needed
-        // execute returns ApiResponse<WorkflowResponse | null>
-        const apiResponse = await graph.execute({ context: { batchId: "batch-789" } });
+```typescript
+const workflow = new GraphCompose({ token: 'your-token' })
+  .http('processData')
+    .post('https://api.example.com/process')
+    .withBody({ data: 'example' })
+    .end();
 
-        if (apiResponse.success && apiResponse.data) {
-          console.log("Workflow started successfully with ID:", apiResponse.data.workflowId);
-          // Use apiResponse.data.workflowId and apiResponse.data.runId
-        } else {
-          console.error(`Failed to start async workflow: ${apiResponse.message}`);
-        }
-        // Use workflowId to track status or receive webhook updates
-      } catch (error) {
-        console.error("Failed to start async workflow:", error);
-      }
-    }
-    startWorkflowAsync();
-    ```
-
-*   **Synchronous (`executeSync`)**: This method starts the workflow and *waits* for it to complete (or fail) before returning the final result or error. This is simpler for short-running workflows but can time out for longer processes.
-
-    ```typescript
-    // Assuming all node/tool builders have called .end()
-    async function runWorkflowAndWait() {
-      try {
-        // Pass any runtime context needed
-        // executeSync returns ApiResponse<WorkflowResponse | null>
-        const apiResponse = await graph.executeSync({ context: { overrideUserId: "new-user-456" } });
-
-        if (apiResponse.success && apiResponse.data) {
-          console.log("Workflow completed synchronously:", apiResponse.data);
-          // apiResponse.data contains status, executionState, error etc.
-        } else {
-          console.error(`Synchronous workflow execution failed: ${apiResponse.message}`);
-        }
-      } catch (error) {
-        console.error("Synchronous workflow execution failed:", error);
-      }
-    }
-    runWorkflowAndWait();
-    ```
+try {
+  const result = await workflow.execute({
+    context: {
+      userId: '123',
+      requestId: 'req-456'
+    },
+    webhookUrl: 'https://your-app.com/webhook'  // Optional: receive completion notification
+  });
 
-## Getting the Workflow Definition
+  if (result.success && result.data) {
+    console.log('Workflow started!');
+    console.log('Workflow ID:', result.data.workflowId);
+    console.log('Run ID:', result.data.runId);
+    console.log('Status:', result.data.status); // "RUNNING"
+    
+    // Poll for status or wait for webhook
+  }
+} catch (error) {
+  console.error('Execution failed:', error);
+}
+```
 
-After finalizing all nodes and tools with `.end()`, you can retrieve the raw workflow definition object that the client has built. This is useful for debugging, saving, or inspecting the structure.
+**Endpoint:** `POST /workflows`
 
-*   `graph.getWorkflow()`: Returns the complete `WorkflowGraph` object.
-*   `graph.toJSON()`: An alias for `getWorkflow()`, providing the standard JavaScript method for serialization.
+### Check Workflow Status
 
-Both methods will throw an error if any node or tool builder is still active (i.e., missing a final `.end()` call).
+Poll for workflow status after async execution:
 
 ```typescript
-// Assuming all builders are finalized
+const workflowId = 'wf_abc123';
+
+try {
+  const statusResult = await workflow.getWorkflowStatus(workflowId);
+  
+  if (statusResult.success && statusResult.data) {
+    console.log('Status:', statusResult.data.status);
+    // "RUNNING" | "COMPLETED" | "FAILED" | "TERMINATED"
+    
+    console.log('Started at:', statusResult.data.startTime);
+    
+    if (statusResult.data.status === 'COMPLETED') {
+      console.log('Results:', statusResult.data.results);
+    } else if (statusResult.data.status === 'FAILED') {
+      console.log('Error:', statusResult.data.error);
+    }
+  }
+} catch (error) {
+  console.error('Failed to get status:', error);
+}
+```
+
+**Endpoint:** `GET /workflows/{workflowId}`
 
-const workflowDefinition = graph.getWorkflow();
-console.log("Raw Workflow Definition Object:", workflowDefinition);
+### Terminate Running Workflow
 
-// Equivalent using toJSON() for easy serialization
-const workflowJsonString = JSON.stringify(graph.toJSON(), null, 2);
-console.log("Workflow JSON:", workflowJsonString);
+Stop a workflow that's currently executing:
+
+```typescript
+const workflowId = 'wf_abc123';
+
+try {
+  const result = await workflow.terminateWorkflow(workflowId, {
+    runId: 'run_xyz789',  // Optional: specific run ID
+    reason: 'User requested cancellation'  // Optional
+  });
+  
+  if (result.success) {
+    console.log('Workflow terminated successfully');
+  }
+} catch (error) {
+  console.error('Failed to terminate:', error);
+}
 ```
 
-## Interacting with Existing Workflows (API)
+**Endpoint:** `POST /workflows/{workflowId}/terminate`
 
-These methods interact directly with the Graph Compose API using a workflow ID, and don't depend on the local builder state.
+### Webhook Notifications
 
-*   **Get Workflow Status:** Check the current status (running, completed, failed, etc.) of a previously started workflow.
-    ```typescript
-    // Does not depend on local builder state
-    async function checkStatus(workflowId: string) {
-      try {
-        const statusResult = await graph.getWorkflowStatus(workflowId);
-        console.log(`Status for ${workflowId}:`, statusResult.status);
-        // Handle other details in statusResult like results or errors
-      } catch (error) {
-        console.error("Failed to get workflow status:", error);
-      }
-    }
-    checkStatus("existing-workflow-id-123");
-    ```
-
-*   **Terminate Workflow:** Stop a currently running workflow.
-    ```typescript
-    // Does not depend on local builder state
-    async function stopWorkflow(workflowId: string, reason?: string) {
-      try {
-        const terminateResult = await graph.terminateWorkflow(workflowId, { reason });
-        console.log(`Termination request for ${workflowId}:`, terminateResult);
-      } catch (error) {
-        console.error("Failed to terminate workflow:", error);
-      }
-    }
-    stopWorkflow("running-workflow-id-456", "User cancelled operation");
-    ```
+Receive notifications when async workflows complete:
+
+```typescript
+const workflow = new GraphCompose({ token: 'your-token' })
+  .http('longProcess')
+    .post('https://api.example.com/long-process')
+    .end()
+  .withWebhookUrl('https://your-app.com/webhook');
+
+// Your webhook will receive:
+// POST https://your-app.com/webhook
+// {
+//   "workflowId": "wf_abc123",
+//   "runId": "run_xyz789",
+//   "status": "COMPLETED",
+//   "results": { ... },
+//   "completedAt": "2024-01-15T10:30:00Z"
+// }
+```
 
-## Full Example: Putting it Together
+### API Response Format
 
-This example demonstrates defining nodes, setting context, validating, and executing.
+All API methods return a consistent response structure:
 
 ```typescript
-import { GraphCompose } from "@graph-compose/client";
+interface ApiResponse<T> {
+  success: boolean;
+  data: T | null;
+  error?: {
+    code: string;
+    message: string;
+    details?: any;
+  };
+  metadata?: {
+    requestId: string;
+    timestamp: string;
+    version: string;
+  };
+}
 
-async function main() {
-  const graph = new GraphCompose({ token: process.env.GRAPH_COMPOSE_TOKEN || "" });
+// Example: Successful execution
+{
+  "success": true,
+  "data": {
+    "workflowId": "wf_abc123",
+    "runId": "run_xyz789",
+    "status": "RUNNING",
+    "startTime": "2024-01-15T10:00:00Z"
+  },
+  "metadata": {
+    "requestId": "req_456",
+    "timestamp": "2024-01-15T10:00:00Z",
+    "version": "v1"
+  }
+}
 
-  // Define Node 1
-  graph.node("get_ip")
-    .description("Fetches the public IP address of the caller.")
-    .get("https://httpbin.org/ip")
-    .end(); // Required!
+// Example: Error response
+{
+  "success": false,
+  "data": null,
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Invalid node configuration",
+    "details": {
+      "nodeId": "fetchData",
+      "issue": "Missing required field: url"
+    }
+  }
+}
+```
+
+### Workflow Status Types
 
-  // Define Node 2 (depends on Node 1)
-  graph.node("echo_ip")
-    .description("Echoes the IP address back.")
-    .post("https://httpbin.org/post")
-    .withBody({ theIpAddress: "{{results.get_ip.origin}}" }) // Access results from 'get_ip'
-    .withDependencies(["get_ip"])
-    .end(); // Required!
+```typescript
+type WorkflowStatus = 
+  | "RUNNING"      // Workflow is currently executing
+  | "COMPLETED"    // Workflow finished successfully
+  | "FAILED"       // Workflow encountered an error
+  | "TERMINATED";  // Workflow was manually stopped
+```
 
-  // Set context *after* ending the last node builder
-  graph.withContext({ requestSource: "client-example-readme" });
+### Complete Execution Example
+
+```typescript
+import { GraphCompose } from '@graph-compose/client';
 
-  console.log("Validating workflow locally...");
-  // Validate *after* ending all node builders and setting context/config
-  const validation = graph.validate();
+async function runWorkflow() {
+  // Build the workflow
+  const workflow = new GraphCompose({ token: process.env.GRAPH_COMPOSE_TOKEN })
+    .http('fetchUser')
+      .get('https://api.example.com/users/{{context.userId}}')
+      .end()
+    .http('enrichProfile')
+      .post('https://api.example.com/enrich')
+      .withBody({
+        userId: '{{results.fetchUser.id}}',
+        email: '{{results.fetchUser.email}}'
+      })
+      .dependsOn(['fetchUser'])
+      .end();
+
+  // Validate locally
+  const validation = workflow.validate();
   if (!validation.isValid) {
-    console.error("Local Validation Failed:", validation.errors);
-    return;
+    throw new Error(`Invalid workflow: ${validation.errors.map(e => e.message).join(', ')}`);
   }
-  console.log("Local Validation Successful!");
-
-  console.log("Executing workflow asynchronously...");
-  // Execute *after* ending all node builders and setting context/config
-  try {
-    // execute returns ApiResponse<WorkflowResponse | null>
-    const apiResponse = await graph.execute(); // Using async execution
-
-    if (apiResponse.success && apiResponse.data) {
-      const workflowId = apiResponse.data.workflowId;
-      console.log("Workflow started with ID:", workflowId);
-      console.log("Monitor status using `getWorkflowStatus(workflowId)` or webhooks.");
-      // Example: Poll status after a short delay
-      // setTimeout(async () => {
-      //   await checkStatus(workflowId); // Assumes checkStatus function from above is defined
-      // }, 5000);
-    } else {
-      console.error(`Failed to start workflow: ${apiResponse.message}`);
+
+  // Execute async
+  const execution = await workflow.execute({
+    context: { userId: '123' },
+    webhookUrl: 'https://myapp.com/webhook'
+  });
+
+  if (!execution.success || !execution.data) {
+    throw new Error('Execution failed');
+  }
+
+  const workflowId = execution.data.workflowId;
+  console.log('Workflow started:', workflowId);
+
+  // Poll for completion
+  let status = 'RUNNING';
+  while (status === 'RUNNING') {
+    await new Promise(resolve => setTimeout(resolve, 2000)); // Wait 2s
+    
+    const statusResult = await workflow.getWorkflowStatus(workflowId);
+    if (statusResult.success && statusResult.data) {
+      status = statusResult.data.status;
+      console.log('Current status:', status);
     }
-  } catch (error) {
-    console.error("Execution Failed:", error);
   }
-}
 
-// Helper function for the example (copy from 'Interacting with Existing Workflows' section)
-async function checkStatus(workflowId: string) {
-  // Re-initialize graph object or ensure it's accessible in this scope
-  const graph = new GraphCompose({ token: process.env.GRAPH_COMPOSE_TOKEN || "" });
-  try {
-    const statusResult = await graph.getWorkflowStatus(workflowId);
-    console.log(`[Status Check] Status for ${workflowId}:`, statusResult.status);
-    if (statusResult.status === 'COMPLETED') {
-        console.log('[Status Check] Results:', statusResult.results);
-    } else if (statusResult.status === 'FAILED') {
-        console.error('[Status Check] Error:', statusResult.error);
+  // Get final results
+  const finalResult = await workflow.getWorkflowStatus(workflowId);
+  if (finalResult.success && finalResult.data) {
+    if (finalResult.data.status === 'COMPLETED') {
+      console.log('✅ Workflow completed successfully!');
+      console.log('Results:', finalResult.data.results);
+    } else {
+      console.error('❌ Workflow failed:', finalResult.data.error);
     }
-  } catch (error) {
-    console.error("[Status Check] Failed to get workflow status:", error);
   }
 }
 
-main();
+runWorkflow().catch(console.error);
+```
+
+## API Reference
+
+### GraphCompose
+
+Main workflow builder class.
+
+#### Constructor
+
+```typescript
+new GraphCompose(options?: { token?: string })
 ```
 
+- `options.token` - API token (or set `GRAPH_COMPOSE_TOKEN` env var)
+
+#### Building Methods
+
+- `http(id: string): NodeBuilder` - Create HTTP node
+- `adk(id: string): AdkNodeBuilder` - Create ADK agent node
+- `errorBoundary(id: string): ErrorBoundaryBuilder` - Create error boundary
+- `build(): WorkflowGraph` - Build the workflow definition
+
+#### Configuration Methods
+
+- `withContext(context: Record<string, any>): GraphCompose` - Set workflow context
+- `withWebhookUrl(url: string): GraphCompose` - Set webhook for async notifications
+- `withWorkflowConfig(config: WorkflowConfig): GraphCompose` - Set workflow-level config
+
+#### Validation Methods
+
+- `validate(): ValidationResult` - Client-side validation
+- `validateApi(): Promise<ApiResponse>` - Server-side validation with tier checks
+
+#### Execution Methods
+
+- `execute(options?): Promise<ApiResponse>` - Execute workflow (returns immediately with workflow ID)
+- `getWorkflowStatus(workflowId: string): Promise<ApiResponse>` - Check workflow status
+- `terminateWorkflow(workflowId: string, options?): Promise<ApiResponse>` - Stop workflow
+
+### NodeBuilder
+
+Builder for HTTP nodes.
+
+#### HTTP Methods
+- `get(url: string)` - GET request
+- `post(url: string)` - POST request
+- `put(url: string)` - PUT request
+- `patch(url: string)` - PATCH request
+- `delete(url: string)` - DELETE request
+
+#### Configuration
+- `withHeaders(headers: Record<string, string>)` - Set headers
+- `withBody(body: any)` - Set request body
+- `withParams(params: Record<string, string>)` - Set URL params
+- `withRetries(policy: RetryPolicy)` - Configure retry policy
+- `withStartToCloseTimeout(timeout: string)` - Set activity timeout
+- `dependsOn(nodeIds: string[])` - Set dependencies
+- `runWhen(condition: Condition)` - Conditional execution
+
+#### Completion
+- `end(): GraphCompose` - Finalize node
+
+### AdkNodeBuilder
+
+Builder for ADK agent nodes.
+
+#### Methods
+- `withWorkflow(workflow: ADKWorkflowDefinition)` - Set agent workflow
+- `withInitialPrompt(prompt: string)` - Set initial prompt
+- `withMaxCycles(max: number)` - Set max orchestration cycles
+- `withState(state: Record<string, any>)` - Seed initial state
+- `withRetries(policy: RetryPolicy)` - Configure retry policy
+- `dependsOn(nodeIds: string[])` - Set dependencies
+- `end(): GraphCompose` - Finalize node
+
+### AdkWorkflowBuilder
+
+Builder for agent workflow definitions.
+
+#### Methods
+- `agent(config: AgentConfig)` - Add agent
+- `httpTool(config: HttpToolConfig)` - Add HTTP tool
+- `agentTool(config: AgentToolConfig)` - Add agent tool
+- `setRootAgent(agentId: string)` - Set entry point agent
+- `withMaxCycles(max: number)` - Set workflow-level max cycles
+- `build(): ADKWorkflowDefinition` - Build the workflow
+
+### Helper Functions
+
+#### Agent Helpers
+- `createLlmAgent(config)` - Create LLM agent config
+- `createSequentialAgent(config)` - Create sequential orchestrator
+- `createParallelAgent(config)` - Create parallel orchestrator
+- `createLoopAgent(config)` - Create loop orchestrator
+- `createSubAgentReference(agentId)` - Create agent reference
+
+#### Tool Helpers
+- `createHttpTool(config)` - Create HTTP tool config
+- `createAgentTool(config)` - Create agent tool config
+
+## TypeScript Types
+
+Full TypeScript support with exported types:
+
+```typescript
+import type {
+  WorkflowGraph,
+  HttpNode,
+  AdkNode,
+  RetryPolicy,
+  ADKWorkflowDefinition,
+  AgentConfig,
+  ToolConfig,
+  ValidationResult
+} from '@graph-compose/client';
+```
+
+## Examples
+
+See the `examples/` directory for complete working examples:
+
+- **HTTP Workflow**: Service orchestration
+- **ADK Basic**: Simple agent with tools
+- **ADK Advanced**: Multi-agent hierarchies
+- **Error Handling**: Retry and fallback patterns
+- **Conditional**: Branch-based workflows
+
 ## Contributing
 
-Contributions are welcome! Please refer to the main repository's contribution guidelines.
+Contributions are welcome! Please see [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines.
 
 ## License
 
-This project is licensed under the MIT License. See the LICENSE file in the main repository for details. 
+MIT License - see [LICENSE](../../LICENSE) for details.
+
+## Support
+
+- 📖 [Documentation](https://github.com/your-org/graph-compose)
+- 💬 [Discord Community](https://discord.gg/your-server)
+- 🐛 [Issue Tracker](https://github.com/your-org/graph-compose/issues)
+- 📧 [Email Support](mailto:support@example.com)