Core Concepts

Agent contexts

Agent contexts define the read model an agent is allowed to use.

Overview

A context is a named bundle of bindings and data sources.

Context names, table names, aliases, output slot names, and search step names are developer-defined. SESSION values such as tenant_id and current_ticket_id are trusted values your backend sets before the context is used.

SEARCH ... QUERY ARG question means the query text is supplied later by the capability caller through INVOKE/PROPOSE JSON or SDK arguments.

The capability references a context instead of letting prompts assemble raw database access.

Developer notes

Use one context per trust boundary.
Keep tenant, principal, and entitlement values hidden.
Version contexts before changing semantics used by customer workflows.
Add parser tests before making public grammar changes.

Context grammar

SQL

CREATE AGENT CONTEXT <namespace.name>         -- replace with e.g. support.ticket_context
ROOT <table> AS <alias>                       -- e.g. tickets AS ticket
LOOKUP <alias>.<id_column> = SESSION <current_object_id> -- app-selected row id
BIND <trusted_name> FROM SESSION <session_key> -- e.g. tenant_id from SESSION tenant_id
SEARCH <table> AS <step_name> USING HYBRID(<table>.<text_column>) -- retrieval step
  QUERY ARG <question_arg>                    -- caller-provided search text
  FILTER <table>.tenant_id = SESSION tenant_id -- trusted tenant filter
  TOP <n>                                     -- max retrieved chunks
OUTPUT SLOTS
  <slot_name> AS <alias>.<column>             -- named value exposed by context
EVIDENCE ON;                                  -- record rows/search hits

Examples

sql

CREATE AGENT CONTEXT support.ticket_context -- developer-defined context name
ROOT tickets AS ticket                       -- tickets is your table; ticket is the local alias
LOOKUP ticket.id = SESSION current_ticket_id -- current_ticket_id comes from SET SESSION/API session
BIND tenant_id FROM SESSION tenant_id        -- trusted tenant scope
BIND principal FROM SESSION principal        -- trusted actor identity
OUTPUT SLOTS
  ticket_id AS ticket.id,                    -- output slot mapped from ticket.id
  subject AS ticket.subject,
  status AS ticket.status
EVIDENCE ON;                                 -- record source rows in evidence bundles