Implement Tool Use with Inline Tools

Learn how to create inline tools for rapid prototyping and simple functionality without deploying separate Lambda functions. Inline tools are TypeScript functions embedded directly into your agent's configuration.

What You'll Accomplish

By the end of this guide, you will:

Create an inline tool function in TypeScript
Define a function schema for your tool
Configure CDK to transpile and deploy your tool
Test your inline tool in a chat session

Prerequisites

A working Pika CDK deployment setup
Node.js and npm installed
Basic understanding of TypeScript
Familiarity with AWS CDK

Step 1: Create Your Tool Function

Create a TypeScript file with a standalone function following the required signature.

Location: services/your-service/src/your-tool/inline-code.ts

import { ActionGroupInvocationInput } from '@aws-sdk/client-bedrock-agent-runtime';

function random(event: ActionGroupInvocationInput, params: Record<string, any>) {
    console.log('Random number generator called with params:', params);

    const min = params.min;
    const max = params.max;
    const range = max - min;
    const val = Math.random() * range + min;
    const factor = Math.pow(10, params.precision ?? 0);

    return Math.round(val * factor) / factor;
}

Critical Requirements

Step 2: Define Function Schema

Create a schema that describes your tool's parameters and behavior.

Location: services/your-service/src/your-tool/tool-functions.ts

import { FunctionDefinition } from '@aws-sdk/client-bedrock-agent-runtime';

export const randomNumFunctions: FunctionDefinition[] = [
    {
        name: 'random-number',
        description: 'Creates a random number between min and max.',
        parameters: {
            max: {
                description: 'max value (exclusive)',
                required: true,
                type: 'number'
            },
            min: {
                description: 'min value (inclusive)',
                required: true,
                type: 'number'
            },
            precision: {
                description: 'number of decimal places to include (default 0)',
                required: false,
                type: 'number'
            }
        },
        requireConfirmation: 'DISABLED'
    }
];

Step 3: Add Transpilation to CDK Stack

Configure your CDK stack to transpile TypeScript to JavaScript.

Add Required Dependencies

Location: services/your-service/package.json

{
    "dependencies": {
        "esbuild": "^0.19.0"
    },
    "devDependencies": {
        "@types/node": "^18.0.0"
    }
}

Add Transpilation Method

Location: services/your-service/lib/stacks/your-stack.ts

import * as fs from 'fs';
import * as path from 'path';
import * as esbuild from 'esbuild';

export class YourStack extends Stack {
    // ... other code

    private transpileInlineCodeToJavascript(filePath: string): string {
        // Resolve the file path relative to this stack file
        const absolutePath = path.resolve(__dirname, filePath);

        // Read the TypeScript file
        const tsCode = fs.readFileSync(absolutePath, 'utf8');

        // Use esbuild to transpile TypeScript to JavaScript
        const result = esbuild.transformSync(tsCode, {
            loader: 'ts',
            target: 'es2022',
            format: 'esm'
        });

        const jsCode = result.code;

        if (!jsCode.trim()) {
            throw new Error(`No function found in ${filePath}`);
        }

        // Validate that the code starts with a function declaration
        if (!jsCode.trim().startsWith('function ')) {
            throw new Error(
                `Code does not start with a function declaration in ${filePath}`
            );
        }

        return jsCode;
    }
}

Step 4: Configure the Tool in Your Agent

Add the inline tool to your agent configuration.

const randomNumInlineCode = this.transpileInlineCodeToJavascript(
    '../../src/random-num-inline/inline-code.ts'
);

const agentData: AgentDataRequest = {
    userId: `cloudformation/${this.stackName}`,
    agent: {
        agentId: `${props.projNameKebabCase}-agent-${this.stage}`,
        basePrompt: `You are a random number generator. Use the tool provided to generate random numbers.

If the user doesn't provide min or max values, use defaults of 1 and 100 respectively.

{{prompt-assistance}}`
    },
    tools: [
        {
            toolId: `${props.projNameKebabCase}-tool-${this.stage}`,
            executionType: 'inline',  // Marks it as an inline tool
            name: `${props.projNameKebabCase}-tool`,
            displayName: `${props.projNameTitleCase} Tool`,
            code: randomNumInlineCode,  // The transpiled JavaScript
            description: 'A tool that can generate random numbers',
            functionSchema: randomNumFunctions,
            supportedAgentFrameworks: ['bedrock']
        }
    ]
};

Step 5: Deploy and Test

Deploy Your Stack

cd services/your-service
pnpm run deploy

Test in Chat

Open your chat application
Start a conversation with the agent
Ask it to use the tool:
- "Generate a random number between 1 and 100"
- "Give me a random decimal between 0 and 1 with 3 decimal places"
Check CloudWatch logs to see tool execution

Monitor Logs

View your agent's CloudWatch logs to see:

When the tool is called
The parameters passed
Your console.log() output
Any errors or issues

Project Structure

Organize your inline tool project:

your-inline-tool/
├── src/
│   └── your-tool/
│       ├── inline-code.ts          # Tool function
│       ├── tool-functions.ts       # Function schema
│       ├── tool-instructions.ts    # Agent instructions
│       └── tool-suggestions.ts     # Chat suggestions
├── lib/
│   └── stacks/
│       └── your-tool-stack.ts      # CDK stack
├── bin/
│   └── your-tool.ts                # CDK app entry
├── package.json
├── tsconfig.json
└── cdk.json

Complete Example

The random-num-inline sample demonstrates a complete working inline tool with:

TypeScript tool function
Function schema definition
CDK stack configuration
Agent and chat app setup

Review this sample for a complete reference implementation.

Testing Checklist

Verify your inline tool works correctly:

Troubleshooting

"Code does not start with a function declaration"

Ensure your TypeScript file contains only a single function
Remove any imports, exports, or other code
Check that the function isn't wrapped in any other constructs

"Function not found"

Verify file path in transpileInlineCodeToJavascript() is correct
Check file exists at the specified location
Ensure function has the correct signature

"Tool not executing"

Verify executionType is set to 'inline'
Check function schema matches the tool function's parameters
Review CloudWatch logs for error messages
Ensure agent instructions mention how to use the tool

Debugging Tips

Add extensive logging - Use console.log() to track execution
Log parameters - Check what the agent is actually passing
Test incrementally - Start simple before adding complexity
Validate transpilation - Check the generated JavaScript looks correct

Migration to Lambda

When your inline tool needs production features:

Reasons to Migrate

Need external dependencies (npm packages, AWS SDK)
Complex business logic
Performance requirements
Need better monitoring and observability
Require error handling and retry logic

Migration Steps

Create a new Lambda function project
Move your tool logic to the Lambda handler
Add any required dependencies
Implement proper error handling
Deploy as a Lambda-based tool
Update agent configuration to use Lambda tool

Next Steps

Use Model Context Protocol (MCP) - Connect to external MCP servers
Enable Multi-Agent Collaboration - Have agents work together
Define Agents Using Configuration - Learn more about agent configuration

Lambda-based Tools - For production deployments
Tool Configuration Reference - Complete tool configuration options
Agent Configuration - Agent configuration reference