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
- The user asks for the top 10 customers by revenue.
- The agent lists the tables in the schema.
- It describes the customers and orders tables.
- 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-reflector/reflect. An iteration limit prevents endless loops.
Working with people
Interrupt, clarify, carry on
- The user asks to list all tables.
- The agent starts querying every database.
Ctrl+Cinterrupts it.- 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
| Extension | What it adds |
|---|---|
| Planning mode | A plan before complex tasks |
| Approval flow | Approve, deny or always allow each tool |
| Skills | Domain-specific instructions |
| Persistent memory | Recall across sessions |
The takeaway
Building a Cortex agent doesn't need a complex framework.
Kevin Keller · kevinkeller.org · Educational article, not an official Snowflake document