Code blueprint

Everything about the Cortex Agent API in one Python file

Nanocortex: a working coding assistant and a blueprint for building your own agents.

Kevin Keller · kevinkeller.org

Why it matters

The only limit on an agent is the tools you give it

  • Productivity: decks and reports built from Snowflake data
  • Security: a firewall analyst that reasons over traffic logs
  • Data engineering: a data quality agent that explains drift
  • Domain assistants: finance briefings, customer support
Define tools, register them, let the agent reason about when to use them.

What it is

The minimal viable Cortex agent

  • About 1,600 lines of Python, standard library only.
  • PAT, key pair JWT, workload identity federation or browser login.
  • Client-side tools: bash, read, write, edit, glob, grep, SQL.
  • One server-side tool: web search.
  • Streaming, multi-turn context and a self-correction loop.

The idea

An AI agent is just a loop.

Stream the response, collect tool calls, execute, send results, repeat. Everything else is plumbing.

Context

The LLM only knows your account through what you tell it

At start, nanocortex queries the account, database, schema and role, then injects a system prompt with the first message.

The LLM is not magic: it is guided by the context you give it.

Text to SQL

A good agent explores before it acts

  1. The user asks for the top 10 customers by revenue.
  2. The agent lists the tables in the schema.
  3. It describes the customers and orders tables.
  4. It writes and runs the real query.

4 to 5 tool calls, no hardcoded mappings, no SQL templates.

Client-side execution

The LLM decides. Your client runs the SQL.

  • Tool calls arrive with client_side_execute: true.
  • SQL runs with your credentials, in your network, under your control.
  • That is the security advantage of custom agents.

Self-correction

The agent reviews its own work

  • After answering, it sends itself a review prompt.
  • A wrong column name is spotted and the query rerun.
  • If all is fine it replies "LGTM".
  • Toggle with --no-reflect or /reflect. An iteration limit prevents endless loops.

Working with people

Interrupt, clarify, carry on

  1. The user asks to list all tables.
  2. The agent starts querying every database.
  3. Ctrl+C interrupts it.
  4. The user narrows it to one schema and the agent continues.

Context switches like /db and /schema are injected into the next call.

Lessons for builders

Seven rules from 1,600 lines

  • Start minimal. Don't over-engineer.
  • Run most tools client-side for control.
  • Invest in system prompts and track context.
  • Stream responses in real time.
  • Return structured errors from tools so the model can recover.

Extend it

Patterns you can add yourself

ExtensionWhat it adds
Planning modeA plan before complex tasks
Approval flowApprove, deny or always allow each tool
SkillsDomain-specific instructions
Persistent memoryRecall across sessions

The takeaway

Building a Cortex agent doesn't need a complex framework.

Read the full article

Kevin Keller · kevinkeller.org · Educational article, not an official Snowflake document