Tool Components¶

A tool component defines a callable capability that agents can invoke at runtime. Tools bridge the gap between an AI agent's reasoning and the outside world -- making API calls, querying data, performing calculations, or triggering side effects.

How Tools Work¶

When an agent decides it needs to take an action, it selects and calls a tool. The platform resolves the tool reference, validates the parameters, executes the implementation, and returns the result to the agent.

graph LR
    Agent["Agent"] -->|"Selects tool"| Tool["Tool Component"]
    Tool -->|"Resolves implementation"| Impl["Implementation"]
    Impl -->|"Code Block"| CB["Code Block"]
    Impl -->|"API Endpoint"| API["External API"]
    Impl -->|"Agent"| SubAgent["Sub-Agent"]
    CB -->|"Result"| Agent
    API -->|"Result"| Agent
    SubAgent -->|"Result"| Agent

Implementation Types¶

Tools support four implementation types:

Type	Description	`implementation_ref` value
`codeblock`	Backed by a Code Block component	Code block UUID
`function`	Python function path in the codebase	`app.tools.search_knowledge_base`
`api_endpoint`	External HTTP API call	`https://api.example.com/search`
`agent`	Delegates to another Agent component	Agent UUID

Creating a Tool¶

Code Block ToolAPI Endpoint ToolSub-Agent Tool

Coming Soon

The Python SDK for local development is not yet publicly available.

from flow_sdk.cli_client import CLIClient

client = CLIClient(config)

# First, create the code block
search_code = client.code_blocks.create({
    "name": "Knowledge Base Search",
    "slug": "kb-search-impl",
    "language": "python",
    "code": """
def main(query: str, limit: int = 5) -> list[dict]:
    \"\"\"Search the knowledge base for relevant articles.\"\"\"
    # Implementation connects to your data source
    from app.connectors import kb_connector
    results = kb_connector.search(query, top_k=limit)
    return [{"title": r.title, "content": r.content, "score": r.score}
            for r in results]
""",
    "entry_point": "main",
})

# Then create the tool that wraps it
tool = client.tools.create({
    "name": "Search Knowledge Base",
    "slug": "search-kb",
    "description": "Search the knowledge base for articles matching a query",
    "implementation_type": "codeblock",
    "implementation_ref": str(search_code.id),
    "code_block_id": search_code.id,
    "parameters": [
        {
            "name": "query",
            "type": "string",
            "description": "Search query text",
            "required": True,
        },
        {
            "name": "limit",
            "type": "integer",
            "description": "Maximum number of results",
            "required": False,
            "default": 5,
        },
    ],
    "timeout_seconds": 30,
})

Coming Soon

The Python SDK for local development is not yet publicly available.

tool = client.tools.create({
    "name": "Create Jira Ticket",
    "slug": "create-jira-ticket",
    "description": "Create a support ticket in Jira",
    "implementation_type": "api_endpoint",
    "implementation_ref": "https://your-org.atlassian.net/rest/api/3/issue",
    "parameters": [
        {
            "name": "summary",
            "type": "string",
            "description": "Ticket summary",
            "required": True,
        },
        {
            "name": "description",
            "type": "string",
            "description": "Detailed description",
            "required": True,
        },
        {
            "name": "priority",
            "type": "string",
            "description": "Ticket priority",
            "required": False,
            "default": "Medium",
        },
    ],
    "timeout_seconds": 15,
})

Coming Soon

The Python SDK for local development is not yet publicly available.

tool = client.tools.create({
    "name": "Research Assistant",
    "slug": "research-assistant",
    "description": "Delegates complex research questions to a specialized agent",
    "implementation_type": "agent",
    "implementation_ref": str(research_agent.id),
    "parameters": [
        {
            "name": "question",
            "type": "string",
            "description": "Research question to investigate",
            "required": True,
        },
    ],
    "timeout_seconds": 120,
})

Configuration¶

Required Fields¶

Field	Type	Description
`name`	string	Display name
`slug`	string	URL-safe identifier
`implementation_type`	enum	`codeblock`, `function`, `api_endpoint`, `agent`
`implementation_ref`	string	Points to the implementation (UUID, function path, or URL)

Optional Fields¶

Field	Type	Default	Description
`code_block_id`	UUID	`null`	Direct reference to a Code Block (for `codeblock` type)
`parameters`	list	`[]`	Parameter definitions
`return_type`	string	`null`	Return type hint
`return_schema_ref`	UUID	`null`	Reference to a Schema for the return value
`requires_context`	bool	`false`	Whether the tool needs execution context (tenant, user info)
`timeout_seconds`	int	`null`	Execution timeout (1-600 seconds)
`retry_max_attempts`	int	`1`	Maximum retry attempts (1-10)
`retry_delay_seconds`	int	`1`	Delay between retries (0-300 seconds)

Parameters¶

Each tool parameter is defined with a name, type, description, and optionality:

parameters=[
    {
        "name": "customer_id",
        "type": "string",
        "description": "Unique customer identifier",
        "required": True,
    },
    {
        "name": "include_history",
        "type": "boolean",
        "description": "Include purchase history in the response",
        "required": False,
        "default": False,
    },
    {
        "name": "date_range",
        "type": "object",
        "description": "Optional date range filter",
        "required": False,
        "properties": {
            "start": {"type": "string", "format": "date"},
            "end": {"type": "string", "format": "date"},
        },
    },
]

Supported Parameter Types¶

Type	Description
`string`	Text value
`integer`	Whole number
`number`	Floating-point number
`boolean`	True/false
`object`	Nested object with properties
`array`	List of values

Executing Tools¶

Tools can be executed directly for testing, or they are called automatically by agents at runtime.

Direct Execution¶

Coming Soon

The Python SDK for local development is not yet publicly available.

result = client.tools.execute(tool.id, {
    "query": "How do I reset my password?",
    "limit": 3,
})

print(f"Success: {result.success}")
print(f"Result: {result.result}")
print(f"Time: {result.execution_time_ms}ms")

Retry Behavior¶

When a tool fails, the platform retries according to the configured retry policy:

Coming Soon

The Python SDK for local development is not yet publicly available.

tool = client.tools.create({
    "name": "Flaky External API",
    "slug": "flaky-api",
    "implementation_type": "api_endpoint",
    "implementation_ref": "https://api.example.com/unstable",
    "retry_max_attempts": 3,       # Retry up to 3 times
    "retry_delay_seconds": 5,      # Wait 5 seconds between retries
    "timeout_seconds": 30,         # Each attempt times out at 30 seconds
    "parameters": [...],
})

Connecting Tools to Agents¶

Reference tools from an agent using the tool_refs field:

Coming Soon

The Python SDK for local development is not yet publicly available.

agent = client.agents.create({
    "name": "Support Agent",
    "slug": "support-agent",
    "model_ref": model.id,
    "tool_refs": [
        search_kb_tool.id,
        create_ticket_tool.id,
        check_status_tool.id,
    ],
})

The agent sees each tool's name, description, and parameters, and decides when and how to call them based on the user's request.

Write clear descriptions

The tool's name and description are what the agent sees when deciding which tool to use. Be specific about what the tool does, what it returns, and when it should be used. Vague descriptions lead to incorrect tool selection.