Pular para o conteúdo principal

​
📋Tables

​
When to Use

Tables are structured, live databases. Each row is a record. Each column is a typed field. The agent reads, creates, updates, and deletes via Table Actions. Use Tables when:
  • Data changes frequently and needs to be written by the agent in real time
  • Data has a fixed, predictable structure — defined columns with types
  • You need to persist information across conversations
  • The use case involves CRUD operations
Examples:
  • Leads: name, email, phone, status, contact date
  • Inventory: SKU, name, price, stock
  • Schedule: client, date, time, service type
  • Tickets: ID, description, status, assignee
Golden rule: if the agent is going to write to that data, it’s a Table.

​
URL and Image Columns

Tables work with typed columns. Beyond the basic types (text, number, boolean, date), there are two specialized types for external references. URL Column Stores web addresses as the primary cell value. The system recognizes that field as a link — not generic text. When to use:
  • Each record has an associated link the agent needs to return
  • Catalogs with a link to a purchase page
  • Articles with a link to external access
  • Records with links to forms, videos, or landing pages
Example: Table: Course Catalog
  • name (text): “Advanced Digital Marketing”
  • category (text): “Marketing”
  • price (number): 497
  • enrollment_link (URL): “https://site.com/courses/marketing”
  • active (boolean): true
Image Column Stores URLs pointing to image files. The difference from the URL type is visual semantics — the system knows the content is an image. When to use:
  • Product catalogs with photos
  • Digital menus
  • Portfolios with thumbnails
  • Profiles with avatars
Example: Table: Menu
AspectURLImage
ContentAny linkLink to an image file
RenderingClickable linkImage displayed (where supported)
Typical usePage, form, videoProduct photo, thumbnail

​
Semantic Search and Non-Searchable Items

Semantic search in Tables is fundamentally different from a SQL query. Exact match: 
SELECT * FROM products WHERE name = 'nike sneaker'
-- Only finds if the field is exactly "nike sneaker"
Semantic search:

Query: “sports footwear for running”
→ Finds: “Nike Air Max Sneaker”, “Adidas Running Shoe”
→ Even with no words in common with the query

​
Searchable vs Non-Searchable Columns

Not all columns should be included in the semantic index. Include in embedding:
  • Descriptive fields: name, description, category, tags
  • Fields the user will reference in natural language
Exclude from embedding:
  • Internal IDs (PRD-00847)
  • Dates and timestamps
  • Booleans (true/false)
  • Exact numeric values (97.50, 12)
  • URLs and images
  • Internal control fields
Including non-semantic fields pollutes the index. The model cannot create meaningful embeddings from "true" or "PRD-00847". This reduces search precision with no benefit.

​
How to Handle Non-Searchable Items

📍Strategy 1 — Separate search from filtering The agent first runs semantic search on descriptive columns, then applies exact filters on numeric/boolean columns. User: “I want running sneakers under $100 that are in stock”
  1. Semantic search: “running sneakers” → name, description, category columns
  2. Filter: price <= 100 AND available = true
  3. Returns items that passed both
📍Strategy 2 — Derived text fields To make normally non-searchable data easier to query, create an auxiliary column that describes it: price_range (text): “budget” / “mid-range” / “premium”
— Instead of letting the search try to interpret “89.90” 📍Strategy 3 — Explicit prompt instruction “When searching for products in the Table, use semantic search on the
‘description’ and ‘category’ fields. Then filter by ‘available = true’.
For price range, use the ‘price_range’ field, not the numeric field.”

​
📚 Knowledge Base

​
When to Use

Knowledge Bases are knowledge repositories for semantic lookup. The agent does not write to them — it only reads via the Knowledge Base Search Tool. Use a Knowledge Base when:
  • Content is textual, unstructured, or semi-structured
  • Content is meant to answer questions, not to be manipulated
  • Volume is too large for the Prompt (above ~5000 characters)
  • Content changes editorially — you update it, not the agent
  • You need similarity-based semantic search
Examples: 
- Product manual
- Return and refund policy
- FAQ with dozens of questions
- Technical documentation
- Descriptive catalog with narrative specifications
- Contracts and terms of service
Golden rule: if the agent is only going to read/consult, it’s a KB (if long) or Prompt (if short and static).

​
Query Scoped by Document

By default, KB Search scans all documents in the base simultaneously. A scoped query restricts the search to one specific document. When to Use KB with documents from very different contexts 
KB contains: product A manual, product B manual, privacy policy

User: "How do I reset it?"

Global search may return chunks from the wrong documents.
Scoped search to "product_a_manual.pdf" → only the right context.
Multi-context agent with dynamic scoping 
1. User states they have Product X
2. Agent stores in Contextual Memory: product = "product_x"
3. KB Search scoped to: document = "product_x_manual.pdf"
4. All answers come only from that manual
Compliance and information isolation 
User: "What does my contract say about termination?"
→ Agent scopes to that specific client's contract
→ Never returns clauses from other clients' contracts
Very large KBs Scoping reduces the search space and improves both precision and speed. How to Implement in the Prompt 
"When the user asks questions about their contract, use KB Search scoped
to the document identified by the {contract_id} variable from
Contextual Memory."
When Not to Scope
  • The question is genuinely cross-document
  • You don’t know in advance which document is relevant
  • Small KB with few homogeneous documents

​
📄 PDF Reader Tool

​
When to Use

Use when the document does not exist beforehand — it is brought by the user at the moment of interaction. Use cases: 
- User sends a résumé → agent analyzes and scores the application
- User sends a bank statement → agent categorizes expenses
- User sends a commercial proposal → agent summarizes key points
- User sends a medical report → agent explains it in plain language
- User sends a contract → agent flags problematic clauses
The document is different for every user. It makes no sense to index it in a KB because each instance is unique. The agent only needs the content for that conversation.

​
PDF Reader vs Knowledge Base

DimensionPDF ReaderKnowledge Base
When the document existsAt runtime (user sends it)Pre-loaded in configuration
Who provides itThe user, during the conversationThe agent creator
Reading typeDirect file readingSemantic search on vector index
PersistenceTemporary (lasts the conversation)Permanent
VolumeOne document at a timeMultiple indexed documents
Pitfall: using KB to process documents the user sends. KB does not accept uploads at execution time.
Pitfall: using PDF Reader for documents that are always the same. Inefficient — processes the same file repeatedly with no semantic search.

​
Using Both Together

There are scenarios where both make sense in the same solution. Contract analysis agent: 
Knowledge Base:
→ Current legislation, case law, standard templates
→ Always available for any query

PDF Reader:
→ The specific contract the user just sent
→ Agent reads the contract and cross-references with KB legislation
Onboarding agent: 
Knowledge Base:
→ Company handbook, code of conduct, benefits, policies

PDF Reader:
→ The specific employment contract of the new hire
→ Agent explains the clauses of that particular contract