Chapter 14: Building AI Agents

The Problem

You've been using Claude Code to build segments, journeys, and workflows. But what about your team members who aren't using Claude Code? What about the sales rep who needs quick answers about customer data? The support team that needs to look up product information?

You need AI assistants tailored to specific roles—assistants that know your data, follow your guidelines, and can be used by anyone through a simple chat interface.

The Key Idea

Core concept

Custom AI agents are chat assistants you design for specific purposes. They connect to your Treasure Data tables, follow your rules, and can be shared with your team through Slack, webhooks, or the TD Console.

What is AI Agent Foundry?

AI Agent Foundry is Treasure Data's platform for building and deploying AI agents. Each project contains:

Agents — Chat assistants with specific tasks and instructions
Knowledge Bases — Connections to your TD tables via SQL queries
Integrations — How users access the agent (Slack, webhooks, TD Console)

What You Can Build

Agent Type	Purpose	Example Questions
Customer Insights	Answer questions about customer behavior	"How many high-value customers do we have?"
Campaign Helper	Suggest targeting rules	"Who should I target for a win-back campaign?"
Product Expert	Answer product questions	"What's our best-selling product in Q4?"
Report Generator	Create ad-hoc reports	"Show me revenue by region this month"

The Agent Workflow

Building an agent with tdx follows the familiar pattern:

bash

# 1. Pull project to local files
tdx agent pull "Marketing Agents"

# 2. Edit agent files locally (with AI help)

# 3. Preview and push changes
tdx agent push --dry-run
tdx agent push

# 4. Share the chat URL with your team

Creating Your First Agent

Tell AI what you need:

> "Create a customer insights agent that can answer questions about our customer data"

AI creates the folder structure:

agents/marketing-agents/
├── tdx.json                      # Project config
├── customer-insights/
│   ├── agent.yml                 # Agent configuration
│   └── prompt.md                 # System prompt
└── knowledge_bases/
    └── customer-data.yml         # TD table connection

Project Config (tdx.json)

json

{
  "llm_project": "Marketing Agents"
}

Agent Configuration (agent.yml)

Before we look at the configuration, let's understand the three settings that shape your agent's personality:

Mental Model: Hiring an Employee

Think of creating an agent like hiring a new team member:

Setting	Hiring Analogy	What It Controls
Model	Experience level	Capability and cost. `claude-4.5-sonnet` is your senior analyst; `claude-4.5-haiku` is a quick assistant for simple tasks
Temperature	Work style	How creative vs. by-the-book. Low (0.3) = consistent, factual answers. High (0.9) = creative, varied responses
Prompt	Job description	What the agent knows, how it should behave, what it should never do

Temperature in practice:

0.0-0.3 — "Give me the same answer every time" (data lookups, customer counts)
0.7 — "Be helpful but consistent" (general questions, default)
0.9-1.0 — "Surprise me with ideas" (brainstorming, creative copy)

The default temperature is 0.7—a balanced middle ground. For a data-focused agent, we'll use 0.3 to get consistent, factual answers:

Reasoning Mode

If you enable reasoning mode (reasoning_effort), temperature must be set to 1 or omitted entirely.

yaml

name: Customer Insights
description: Answers questions about customer behavior and segments

model: claude-4.5-sonnet
temperature: 0.3           # Low for consistent, factual answers
max_tool_iterations: 5

starter_message: |
  Hi! I can help you understand our customer data.
  Try asking:
  - "How many high-value customers do we have?"
  - "What's the average order value this month?"
  - "Which segment grew the most last quarter?"

tools:
  - type: knowledge_base
    target: '@ref(type: "knowledge_base", name: "customer-data")'
    target_function: SEARCH
    function_name: search_customers
    function_description: Search customer data and metrics

System Prompt (prompt.md)

markdown

You are a Customer Insights assistant for our marketing team.

## Your Role

Help team members understand customer data without writing SQL.
Answer questions about:
- Customer counts and segments
- Purchase behavior and trends
- Campaign performance

## Guidelines

- Always cite the data source when providing numbers
- If you're unsure, say so rather than guessing
- Keep responses concise and actionable

## Data Access

You have access to customer-data which includes:
- Customer profiles and attributes
- Purchase history
- Segment membership

Knowledge Base (knowledge_bases/customer-data.yml)

A knowledge base gives your agent access to information. There are two types:

TD tables (.yml files) — Query your customer data
Text content (.md files) — Static information like FAQs, policies, product details

Here's a table-based knowledge base that connects to your TD data:

yaml

name: customer-data
database: marketing_db
tables:
  - name: customer_metrics
    td_query: |
      SELECT
        customer_id,
        lifetime_value,
        total_orders,
        last_purchase_date,
        segment_name
      FROM customer_360
    enable_data: true
    enable_data_index: true

The agent can now search this data when users ask questions.

Pushing and Testing

Preview your changes:

bash

tdx agent push --dry-run

Push summary for 'Marketing Agents':
  + 1 new agent
  + 1 new knowledge base

Changes:
  + customer-insights/agent.yml
  + customer-insights/prompt.md
  + knowledge_bases/customer-data.yml

Push to make it live:

bash

tdx agent push

✔ Pushed 2 resources to 'Marketing Agents'
Agent: Customer Insights
Chat: https://console.treasuredata.com/app/af/.../ag/.../tc

Test in the TD Console, then share the URL or set up integrations.

Adding More Capabilities

Multiple Knowledge Bases

Connect different data sources:

yaml

tools:
  - type: knowledge_base
    target: '@ref(type: "knowledge_base", name: "customer-data")'
    target_function: SEARCH
    function_name: search_customers
    function_description: Search customer profiles and metrics

  - type: knowledge_base
    target: '@ref(type: "knowledge_base", name: "product-catalog")'
    target_function: SEARCH
    function_name: search_products
    function_description: Search product information

Web Search

Add real-time information:

yaml

tools:
  - type: web_search
    target: '@ref(type: "web_search_tool", name: "web-search")'
    target_function: SEARCH
    function_name: search_web
    function_description: Search the web for current trends

Agent-to-Agent

Create specialized agents that work together:

yaml

# In campaign-helper/agent.yml
tools:
  - type: agent
    target: '@ref(type: "agent", name: "Customer Insights")'
    target_function: CHAT
    function_name: ask_customer_insights
    function_description: Get customer data insights

Now Campaign Helper can ask Customer Insights for data.

Text-Based Knowledge Bases

For static content like FAQs or guidelines, use markdown files:

knowledge_bases/targeting-guidelines.md:

markdown

---
name: Targeting Guidelines
---

# Segment Targeting Guidelines

## High-Value Customers
- Definition: LTV > $1000
- Typical size: 5-10% of customer base
- Best for: Premium offers, early access

## At-Risk Customers
- Definition: No purchase in 90+ days
- Typical size: 15-20% of customer base
- Best for: Win-back campaigns

Reference it like any knowledge base:

yaml

tools:
  - type: knowledge_base
    target: '@ref(type: "knowledge_base", name: "Targeting Guidelines")'
    target_function: READ_TEXT
    function_name: read_guidelines
    function_description: Read targeting best practices

AI Agent Foundry supports multiple integration types:

Integration	Access	Use Case
TD Console	Browser chat	Internal testing, power users
Slack	Slack workspace	Team-wide access
Webhook	API calls	Custom apps, Google Sheets

Set up integrations in the TD Console after pushing your agent.

Managing Agents

bash

# List agents in current project
tdx agents

# Pull latest from server
tdx agent pull "Marketing Agents"

# Clone to staging/production
tdx agent clone "Marketing Agents" \
  --name "Marketing Agents (Prod)" \
  --profile production

Mental Model: Specialized Team Members

Think of each agent as a team member with a specific job:

Role	Agent
Data analyst answering questions	Customer Insights
Campaign strategist suggesting targets	Campaign Helper
Product specialist	Product Expert

They're available 24/7, know your data, and serve your entire team.

Pitfalls

"The agent doesn't know about recent data."

Knowledge bases query your TD tables via SQL. Ensure the underlying tables are fresh.

"The agent gives inconsistent answers."

Lower the temperature for more deterministic responses:

yaml

temperature: 0.2

"The agent makes up numbers."

Strengthen your system prompt:

markdown

## Important Rules
- Only cite data from the knowledge base
- If you can't find data, say "I don't have that information"
- Never make up numbers

What You've Learned

AI agents are chat assistants tailored to specific roles
Knowledge bases can be TD tables (queryable data) or markdown files (text content)
Agents connect to TD tables through knowledge bases
The workflow is pull → edit → push
Agents can chain together for complex tasks
Share agents via Slack, webhooks, or TD Console

Next Step

You've built AI agents for your team. Chapter 15 covers the final piece—how to validate, test, and safely deploy all your marketing configurations.

Resources

AI Agent Foundry Documentation — Official TD documentation
Agent Commands Reference — Full tdx command documentation
tdx-skills/agent — AI assistance for building agents

You can build AI assistants for your team. Next, you'll learn to ship with confidence.

Chapter 14: Building AI Agents ​

The Problem ​

The Key Idea ​

What is AI Agent Foundry? ​

What You Can Build ​

The Agent Workflow ​

Creating Your First Agent ​

Project Config (tdx.json) ​

Agent Configuration (agent.yml) ​

Mental Model: Hiring an Employee ​

System Prompt (prompt.md) ​

Knowledge Base (knowledge_bases/customer-data.yml) ​

Pushing and Testing ​

Adding More Capabilities ​

Multiple Knowledge Bases ​

Web Search ​

Agent-to-Agent ​

Text-Based Knowledge Bases ​

Sharing with Your Team ​

Managing Agents ​

Mental Model: Specialized Team Members ​

Pitfalls ​

What You've Learned ​

Next Step ​

Resources ​

Chapter 14: Building AI Agents

The Problem

The Key Idea

What is AI Agent Foundry?

What You Can Build

The Agent Workflow

Creating Your First Agent

Project Config (tdx.json)

Agent Configuration (agent.yml)

Mental Model: Hiring an Employee

System Prompt (prompt.md)

Knowledge Base (knowledge_bases/customer-data.yml)

Pushing and Testing

Adding More Capabilities

Multiple Knowledge Bases

Web Search

Agent-to-Agent

Text-Based Knowledge Bases

Sharing with Your Team

Managing Agents

Mental Model: Specialized Team Members

Pitfalls

What You've Learned

Next Step

Resources