Tool Integration for Agents 🛠️

Empower your AI agents by giving them tools! Learn how to define and integrate HTTP endpoints and sub-workflows as tools agents can use to interact with the outside world.

How Tools Work with Agents

Think of tools as callable functions that your agent can invoke. When your agent decides it needs to use a tool to proceed:

1. Agent Responds: Your agent's HTTP endpoint returns a specific response telling Graph Compose which tool to use and what data (payload) to send to it. (See Agent Contract).

2. Graph Compose Finds the Tool: Graph Compose looks up the requested tool's definition (which you configured in your workflow). Tools can be simple HTTP calls or more complex sub-workflows (Graph Tools).
3. Graph Compose Merges Payloads: The toolPayload provided by your agent is merged with the base configuration defined in the tool definition. Agent-provided values override any matching keys in the tool's base config.
4. Graph Compose Executes the Tool: The platform handles the actual execution – either making the configured HTTP request or running the defined sub-workflow graph.
5. Result Sent Back to Agent: On the next iteration, Graph Compose sends the result (or error) of the tool execution back to your agent endpoint within the toolResults array in the request body.

This allows your agent to request actions, get results, and decide its next step in the loop.

Tool Types

Graph Compose offers two types of tools:

• HTTP Tools: Best for simple, single actions like making a direct API call, validating data, or fetching a specific piece of information.
• Graph Tools: Ideal for multi-step processes that require orchestrating several HTTP calls in sequence or parallel, essentially encapsulating a mini-workflow within a tool.

Implementing Your HTTP Tool Endpoint

If you define an HTTP Tool, you need to build and host an HTTP endpoint that can receive requests from Graph Compose when an agent decides to use your tool. This endpoint contains your tool's core logic.

Tool Execution Logic

Your tool endpoint receives a request from Graph Compose and should perform its specific task based on the provided payload.

Request Format

Your HTTP tool endpoint receives this data in the request body each time it's called by Graph Compose:

{
  "toolId": "search_docs",           // ID of the tool being executed
  "agentIterationNumber": 3,        // The agent's iteration when calling the tool
  "toolPayload": {                 // Payload provided by the agent in its response
    "query": "password reset",
    "maxResults": 3,
    "filters": {
      "category": "security"
    }
  },
  "allResults": {                  // Current state of the *entire* workflow execution
    "context": {                   // Initial context provided when workflow started
      "userId": "user-123",
      "token": "actual-token-value",
      "requestId": "request-123"
      // ... other context values
    },
    "results": {                   // Results from all *other* completed nodes/tools
      "get_user_data": { "name": "Alice" },
      "previous_tool": { "value": 42 }
      // ... results from other nodes
    },
    "httpStatuses": {              // HTTP status details for completed nodes/tools
      "get_user_data": { "statusCode": 200, "headers": {} },
      "previous_tool": { "statusCode": 200, "headers": {} }
      // ... statuses from other nodes
    }
  }
}

Defining Tools in Graph Compose

Now that you understand how agents interact with tools, let's see how you define these tools within your Graph Compose workflow configuration.

Tools are defined in a top-level tools array in your workflow definition, alongside the nodes array.

Defining HTTP Tools

Use HTTP tools for direct interactions with a single API endpoint.

import { GraphCompose } from '@graph-compose/client';

const workflow = new GraphCompose()
  // ... other nodes ...
  .tool("analyze_sentiment")
    .description("Analyzes text sentiment")
    .post("https://api.example.com/analyze") // Sets method and URL
    .withHeaders({
      "Authorization": "Bearer {{context.nlp_api_key}}",
      "Content-Type": "application/json"
    })
    // Body might be set here or dynamically via agent payload
    // .withBody({ text: "{{ context.inputText }}" })
    .withRetries({ maximumAttempts: 3 })
  .end()
  // ... agent node definition referencing "analyze_sentiment" ...

Defining Graph Tools

Use Graph tools to encapsulate multi-step workflows that an agent can trigger as a single action.

import { GraphCompose } from '@graph-compose/client';

const workflow = new GraphCompose()
  // ... other nodes ...
  .tool("etl_pipeline")
    .description("Extracts, transforms, and loads data")
    .graph(subGraph => subGraph // Define the sub-workflow
      .node("extract")
        .get("https://api.example.com/data")
        // Agent payload could provide dynamic query params here
      .end()
      .node("transform")
        .dependencies(["extract"])
        .post("https://api.example.com/transform")
        .withBody({ data: "{{ results.extract.someField }}" })
      .end()
      .node("load")
        .dependencies(["transform"])
        .post("https://api.example.com/load")
        .withBody({ transformedData: "{{ results.transform.processedData }}" })
      .end()
    )
  .end()
  // ... agent node definition referencing "etl_pipeline" ...

Integrating Tools with Agents

Finally, you need to tell your agent node which tools it's allowed to use by listing their IDs in the agent node's tools array:

{
  "nodes": [
    {
      "id": "support_agent",
      "type": "agent",
      "http": { /* ... agent http config ... */ },
      "tools": ["kb_search", "ticket_lookup"]  // Agent can use these tools
    }
    // ... other nodes
  ],
  "tools": [
    {
      "id": "kb_search", // Defined tool
      "type": "http",
      /* ... kb_search config ... */
    },
    {
      "id": "ticket_lookup", // Defined tool
      "type": "http",
      /* ... ticket_lookup config ... */
    },
    {
      "id": "unused_tool", // Defined but not available to this agent
      "type": "http",
      /* ... unused_tool config ... */
    }
  ]
}