Build a Tool-Calling AI Agent: A Practical Tutorial with Testing and Guardrails
AI-agentstool-callingLLM-developmentguardrailshands-on-tutorial

Build a Tool-Calling AI Agent: A Practical Tutorial with Testing and Guardrails

SSkilling Pro Editorial Team
2026-11-19
7 min read

Build a safer tool-calling AI agent with schemas, validation, approvals, retries, logging, tests, and a practical maintenance checklist.

Tool calling turns a language model into an agent that can retrieve information, update records, calculate results, or trigger workflows. This practical lab shows how to build a small, provider-neutral tool-calling AI agent with validated arguments, conversation state, retries, approval steps, logging, and tests. The implementation patterns are deliberately generic so you can adapt them to the model API or agent framework you use.

Overview

A reliable AI agent is not simply a prompt connected to a set of functions. It is a controlled workflow with clear boundaries between the model, the tool runner, application state, and external systems.

User request
    |
    v
Conversation state → Model decides: answer or tool call
                              |
                +-------------+-------------+
                |                           |
          Direct response              Tool request
                                            |
                                  Schema validation
                                            |
                                  Policy and approval check
                                            |
                                  Tool execution with timeout
                                            |
                                  Result sanitization and logging
                                            |
                                  Model receives tool result
                                            |
                                      Final response

For a first lab, use a low-risk read-only tool such as lookup_order, search_documents, or get_weather. Avoid starting with tools that send messages, transfer money, delete data, or modify production systems. A narrow tool makes it easier to inspect every decision and build a useful regression test set.

The core loop is:

  1. Send the user request and available tool definitions to the model.
  2. Inspect the model response for a tool call.
  3. Validate the tool name and every argument.
  4. Ask for approval when the operation is sensitive or consequential.
  5. Run the tool with a timeout and controlled permissions.
  6. Append the tool result to the conversation state.
  7. Call the model again so it can complete the task or request another tool.

Keep the model responsible for proposing an action, not authorizing itself to perform one. Your application should remain the final decision-maker.

What to track

1. Tool schemas and argument validation

Describe each tool as a strict contract. Include its name, purpose, required arguments, types, allowed values, and limits. The description should explain when the tool is appropriate and when it must not be used.

search_documents = {
  "name": "search_documents",
  "description": "Search the approved knowledge base for relevant documents.",
  "parameters": {
    "type": "object",
    "properties": {
      "query": {"type": "string", "minLength": 1, "maxLength": 300},
      "limit": {"type": "integer", "minimum": 1, "maximum": 10}
    },
    "required": ["query"],
    "additionalProperties": false
  }
}

Do not trust arguments because they arrived in structured form. Validate them again in application code. Check types, length, ranges, identifiers, permissions, and references to external resources. Reject unknown fields where possible. A schema helps the model format a request; it does not replace server-side validation.

2. Conversation state

Track the messages or events needed to understand the current task: user input, assistant tool calls, tool results, approval decisions, and the final response. Give each tool call an identifier so the result cannot be accidentally attached to the wrong request.

Separate short-lived conversation state from durable application data. A model transcript may help explain what happened, but it should not be treated as the source of truth for account balances, permissions, inventory, or approval records. Store those facts in the relevant system of record.

3. Execution and failure signals

Record the tool name, validation outcome, execution duration, success or failure category, retry count, approval status, and a correlation ID. Avoid logging secrets, access tokens, private user content, or complete raw payloads unless there is a documented reason and suitable access control.

Useful failure categories include invalid arguments, unknown tool, permission denied, timeout, rate limit, unavailable dependency, malformed result, and policy refusal. Categorization makes recurring problems easier to investigate than a single generic error message.

4. Model and prompt versions

Track the model identifier, system prompt version, tool-schema version, application release, and evaluation-set version. When an agent changes behavior, these fields help you determine whether the cause was a model update, prompt edit, schema change, dependency change, or external data change.

5. Outcome quality

Measure more than whether the final response was generated. Track whether the right tool was selected, arguments were correct, unnecessary calls were avoided, the answer reflected the tool result, and a human approval was requested when required. For important workflows, review a sample of traces rather than relying only on automated scores.

Cadence and checkpoints

Use a simple maintenance rhythm instead of waiting for a serious failure.

For every development change

  • Run schema-validation tests, including missing, extra, malformed, and boundary-value arguments.
  • Test direct answers, one-tool tasks, multi-step tasks, and requests that should be refused.
  • Confirm that tool results are clearly labeled as untrusted external data where appropriate.
  • Verify that the agent stops after a sensible maximum number of tool calls.
  • Check that timeouts and exceptions produce a safe, useful response.

Weekly or at a regular review interval

  • Inspect failed and retried calls by category.
  • Review traces with unexpected tool selection or excessive tool use.
  • Check approval requests for clarity and confirm that sensitive actions remain blocked without approval.
  • Sample final answers for unsupported claims, missing citations, or incorrect summaries of tool results.

Monthly or quarterly

  • Re-run the full regression set against the current model, prompt, schemas, and tools.
  • Review permissions, credentials, network access, and tool ownership.
  • Remove obsolete tools and tighten descriptions for tools that are frequently misused.
  • Compare latency, failure rates, cost controls, and user-reported issues with the previous review.
  • Update the implementation notes when the model provider or framework changes its tool-calling syntax or structured-output behavior.

Keep a small, versioned test-case file. Each case should contain the user request, expected tool or expected no-tool outcome, valid argument constraints, approval requirement, simulated tool result, and acceptable final response characteristics.

{
  "name": "missing_order_id",
  "request": "Show me the status of my order",
  "expected": "ask for the order ID",
  "tool_calls": 0,
  "approval_required": false,
  "risk": "low"
}

How to interpret changes

A higher tool-call rate is not automatically an improvement. It may mean the agent is completing more tasks, or it may mean the prompt encourages unnecessary actions. Pair each metric with a quality check.

  • More invalid arguments: clarify the schema, add examples, tighten validation, or improve the model-facing description. Do not solve this only by silently repairing dangerous values.
  • More repeated calls: inspect whether tool results are too vague, conversation state is missing, or the agent lacks a stopping condition.
  • More refusals: determine whether the safety rule is working as intended or whether tool descriptions and user permissions are too broad or too restrictive.
  • More timeouts: separate model latency from external-service latency. Add bounded retries only for failures likely to succeed on repetition, and use backoff to avoid multiplying load.
  • Correct tools but wrong final answers: inspect result formatting, truncation, source freshness, and whether the model is instructed to distinguish evidence from inference.
  • Unexpected sensitive actions: treat this as a release-blocking issue. Add an explicit approval gate, narrow permissions, and test adversarial wording before further expansion.

Retries need particular care. A read-only lookup may be safe to retry, while a write operation can create duplicates if it is executed twice. For state-changing tools, use idempotency keys or an equivalent mechanism, verify the operation status before retrying, and require confirmation for material consequences.

Prompt injection is another reason to separate instructions from tool data. Content returned by a document search, webpage, email, or database may contain text that attempts to redirect the agent. Treat retrieved content as data, not as a new system instruction. Limit which tools can be called, validate outputs, and require approval before external side effects.

When to revisit

Revisit this tutorial at least monthly or quarterly, and immediately after any change to the model, SDK, agent framework, prompt, tool schema, permissions, or connected service. Tool-calling syntax and structured-output features can change across releases, so confirm the current API documentation before copying example request code into production.

Use this checklist before each deployment:

  1. Are all tools documented with narrow, testable schemas?
  2. Are arguments validated independently of the model?
  3. Are read-only and state-changing tools separated?
  4. Do sensitive actions require explicit approval?
  5. Are timeouts, bounded retries, idempotency, and maximum call limits implemented?
  6. Are secrets and private data excluded from routine logs?
  7. Can every tool call be traced to a user request and application version?
  8. Has the regression suite been run after the latest model or prompt change?
  9. Do failure messages avoid claiming that an action succeeded when its status is unknown?

For related practice, use the prompt engineering workflow for developers to refine instructions, then apply the evaluation principles in machine learning model evaluation to your agent test set. If your agent searches a knowledge base, the RAG tutorial on evaluation and debugging provides a useful adjacent lab. Finally, document the agent as a portfolio project with its architecture, safeguards, test cases, and known limitations rather than presenting only a successful demo.

Start with one read-only tool, a small test set, and a visible trace for every decision. Expand the tool list only when the current workflow is predictable, measurable, and safe to operate.

Related Topics

#AI-agents#tool-calling#LLM-development#guardrails#hands-on-tutorial
S

Skilling Pro Editorial Team

AI and Machine Learning Education Editors

Senior editor and content strategist. Writing about technology, design, and the future of digital media. Follow along for deep dives into the industry's moving parts.