GraphAI Documentation

GraphAI provides a wide variety of specialized agents categorized by their primary function. You can use these agents to handle different stages of a graph workflow, such as providing initial input, processing data, interacting with LLMs, or performing string and array manipulations.

Available agent categories include:

• input: Agents that provide initial data to the graph (e.g., textInputAgent).
• data: Agents for data transformation and aggregation (e.g., mergeObjectAgent, totalAgent, propertyFilterAgent).
• llm: Agents that interface with Large Language Models (e.g., anthropicAgent, geminiAgent, openAIAgent, replicateAgent).
• service: Agents that interact with external services or APIs (e.g., fetchAgent, wikipediaAgent).
• sleeper: Agents that manage timing or delays (e.g., sleeperAgent).
• embedding: Agents for generating vector embeddings (e.g., stringEmbeddingsAgent).
• string: Agents for text manipulation (e.g., stringTemplateAgent, jsonParserAgent).
• array: Agents for array operations (e.g., pushAgent, arrayFlatAgent).
• matrix: Agents for mathematical matrix operations (e.g., dotProductAgent).
• graph: Agents for managing graph structure (e.g., mapAgent, nestedAgent).
• image: Agents for image processing (e.g., images2messageAgent).
• fs: Agents for file system operations (e.g., fileReadAgent).

Since dataflow graphs must be acyclic, GraphAI provides a loop property at the graph level to control iterative execution. A loop can be controlled by two optional properties:

• count: Specifies the exact number of times the graph executes.
• while: Specifies a data source to check after each iteration. The loop continues as long as the value from that data source is truthy (non-null, non-undefined, non-zero, non-false, non-NaN, and non-empty array/string).

To implement a loop, you typically use the update property on static nodes to refresh their values based on the results of the previous iteration, eventually reaching a state that breaks the while condition.

version: 0.5
loop:
  while: :people
nodes:
  people:
    value:
      - Steve Jobs
      - Elon Musk
      - Nikola Tesla
    update: :retriever.array
  result:
    value: []
    update: :reducer.array
    isResult: true
  retriever:
    agent: shiftAgent
    inputs:
      array: :people
  query:
    agent: openAIAgent
    params:
      system: Describe about the person in less than 100 words
      model: gpt-4o
    inputs:
      prompt: :retriever.item
  reducer:
    agent: pushAgent
    inputs:
      array: :result
      item: :query.text

The streamAgentFilterGenerator allows you to receive stream data externally via a streamTokenCallback provided in the filter parameters. This is useful for handling real-time token streaming in both server and client environments.

Server-side implementation (Express)

In an Express server, you can use the callback to write tokens directly to the response stream (e.g., for Server-Sent Events):

const callback = (context: AgentFunctionContext, token: string) => {
  if (token) {
    res.write(token);
  }
};
const streamAgentFilter = {
  name: "streamAgentFilter",
  agent: streamAgentFilterGenerator<string>(callback),
};

Client-side implementation (Web)

In a web client, you can use a callback to update local state (like a Vue ref) as tokens arrive:

const callback = (context: AgentFunctionContext, data: string) => {
  const { nodeId } = context.debugInfo;
  streamingData.value[nodeId] = (streamingData.value[nodeId] ?? "") + data;
};
const agentFilters = [
  {
    name: "streamAgentFilter",
    agent: streamAgentFilterGenerator(callback),
    agentIds: streamAgents,
  },
];

// Example of the callback pattern used by streamAgentFilterGenerator
const callback = (context: AgentFunctionContext, token: string) => {
  if (token) {
    // Handle the token (e.g., res.write(token) or updating UI state)
  }
};

GraphData is a JSON-based format used to define a computational graph where nodes represent agents and edges represent data flow. To use OpenAI agents, define nodes in the nodes object. Each node can specify an agent (e.g., openAIAgent or openAIImageAgent), inputs (using the :nodeName syntax to reference values from other nodes), and params for agent-specific configuration.

Key properties for nodes:

• agent: The identifier of the agent to use.
• inputs: An object mapping agent input keys to values or references to other nodes (e.g., "prompt": ":inputData").
• params: Configuration parameters such as model, system, max_tokens, or images.
• isResult: A boolean indicating if this node's output is the final result of the graph.

{
  "version": 0.5,
  "nodes": {
    "inputData": {
      "value": "hello, let me know the answer 1 + 1"
    },
    "llm": {
      "agent": "openAIAgent",
      "inputs": {
        "prompt": ":inputData"
      },
      "params": {
        "max_tokens": 2000
      }
    }
  }
}