Agent Tools | nfyio

Agent Tools are callable functions that agents use to perform actions: search documents, list bucket contents, fetch web pages, and more. NFYio provides built-in tools and a custom tool SDK. The policy gateway controls which tools each agent can use.

Built-in Tools

Document Search

Search your indexed document corpus using semantic similarity.

Parameter	Type	Required	Description
`query`	string	Yes	Search query
`bucket`	string	No	Limit to specific bucket
`topK`	number	No	Max results (default: 5)
`similarityThreshold`	number	No	Min similarity (0–1, default: 0.5)

Example (agent-invoked):

{
  "tool": "document_search",
  "args": {
    "query": "refund policy for enterprise customers",
    "bucket": "knowledge-base",
    "topK": 5
  }
}

Response:

{
  "chunks": [
    {
      "content": "Enterprise customers may request a full refund within 60 days...",
      "source": "s3://knowledge-base/docs/policies.pdf",
      "similarity": 0.89
    }
  ]
}

Bucket Operations

List, read, and write objects in S3 buckets.

Operation	Description
`bucket_list`	List objects in a bucket/prefix
`bucket_get`	Read object content
`bucket_put`	Upload object
`bucket_delete`	Delete object

Example: List objects

{
  "tool": "bucket_list",
  "args": {
    "bucket": "my-bucket",
    "prefix": "reports/",
    "maxKeys": 20
  }
}

Example: Get object

{
  "tool": "bucket_get",
  "args": {
    "bucket": "my-bucket",
    "key": "reports/q1-2026.pdf"
  }
}

Web Fetch

Fetch content from URLs. Useful for retrieving external documentation or web pages.

Parameter	Type	Required	Description
`url`	string	Yes	URL to fetch
`method`	string	No	HTTP method (default: GET)
`headers`	object	No	Custom headers

Example:

{
  "tool": "web_fetch",
  "args": {
    "url": "https://docs.example.com/api-reference",
    "method": "GET"
  }
}

Response:

{
  "status": 200,
  "content": "<html>...</html>",
  "contentType": "text/html"
}

Note: The policy gateway can restrict which URLs web_fetch can access. Configure allowlists per workspace.

Custom Tool SDK

Build and register custom tools with the NFYio Agent SDK:

Install

npm install @nfyio/agent-sdk

Define a Tool

import { defineTool } from "@nfyio/agent-sdk";

export const getWeather = defineTool({
  name: "get_weather",
  description: "Get current weather for a city",
  parameters: {
    type: "object",
    properties: {
      city: { type: "string", description: "City name" },
      unit: { type: "string", enum: ["celsius", "fahrenheit"], default: "celsius" }
    },
    required: ["city"]
  },
  async execute({ city, unit }) {
    const response = await fetch(
      `https://api.weather.com/v1/current?city=${city}&unit=${unit}`
    );
    return response.json();
  }
});

Register the Tool

curl -X POST "https://api.yourdomain.com/v1/tools" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "get_weather",
    "description": "Get current weather for a city",
    "parameters": {
      "type": "object",
      "properties": {
        "city": { "type": "string" },
        "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }
      },
      "required": ["city"]
    },
    "handler": {
      "type": "function",
      "arn": "arn:aws:lambda:us-east-1:123456789:function:get-weather"
    }
  }'

Use in Workflow

{
  "steps": [
    {
      "id": "weather",
      "agent": "workflow-agent",
      "tools": ["get_weather", "document_search"]
    }
  ]
}

Tool Permissions and Policy Gateway

The policy gateway enforces which tools each agent can use. Configure rules per workspace or agent:

{
  "policyGateway": {
    "rules": [
      {
        "tool": "document_search",
        "action": "allow",
        "scope": ["bucket:knowledge-base", "bucket:docs"]
      },
      {
        "tool": "bucket_list",
        "action": "allow",
        "scope": ["bucket:my-bucket"]
      },
      {
        "tool": "bucket_put",
        "action": "deny"
      },
      {
        "tool": "web_fetch",
        "action": "allow",
        "scope": ["https://docs.example.com/*", "https://api.trusted.com/*"]
      }
    ]
  }
}

Scope Format

Tool	Scope Format	Example
`document_search`	`bucket:<name>`	`bucket:knowledge-base`
`bucket_*`	`bucket:<name>`	`bucket:reports`
`web_fetch`	URL pattern (glob)	`https://docs.example.com/*`
Custom tools	`workspace:<id>` or resource-specific	`workspace:ws_123`

Default Behavior

No rule → Tool is denied
allow without scope → Tool allowed for all resources (use with caution)
deny → Tool always denied, overrides any allow

Community Tool Marketplace (Coming Soon)

NFYio will offer a community tool marketplace where you can:

Discover tools built by other users
Install tools into your workspace with one click
Publish your own tools for the community
Rate and review tools

Tools in the marketplace will be vetted for security and compatibility. Stay tuned for updates.

Tool Invocation Flow

┌─────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Agent     │────►│  Policy Gateway │────►│  Tool Executor  │
│  (workflow  │     │  (allow/deny)   │     │  (run tool)     │
│   or custom)│     │                 │     │                 │
└─────────────┘     └─────────────────┘     └────────┬────────┘
                            │                       │
                            │ deny                  │ allow
                            ▼                       ▼
                     ┌─────────────┐         ┌─────────────────┐
                     │  Error:     │         │  Audit Log      │
                     │  Forbidden  │         │  (tool, args,   │
                     └─────────────┘         │   result)        │
                                            └─────────────────┘

Next Steps

Workflow Agents — Use tools in multi-step pipelines
Custom Agents — Build agents that use custom tools
RAG Agents — Document search powers RAG retrieval