Agents that make the same mistake every day are the norm, because nothing in a typical stack connects what the agent did to whether it worked. In this tutorial we build a small support agent on SynapCores 2.5.1 that closes that loop inside the database:
- it learns which strategy works from outcomes the database checks,
- it notices when that changes and switches on its own,
- it waits for a person before it changes any data,
- and every step lands in a hash-linked audit ledger you can verify.
It's plain Python and the SynapCores REST API: no SDK, no framework. Every output below is from a run on a fresh SynapCores 2.5.1 Community Edition install, and the full script is at the end of the post.
What you need
-
SynapCores Community Edition 2.5.1 or later, running locally. Install it with one command:
curl -fsSL https://get.synapcores.com | SYNAPCORES_REF=agent-learning-tutorial shor see the download page for Docker and other options. It's free and needs no signup.
-
Python 3.9+ (standard library only).
-
An admin access token:
POST /v1/auth/loginwith your admin user returnsdata.access_token. Export it asSYNAPCORES_TOKEN, and setSYNAPCORES_URL(for examplehttp://localhost:8080).
The scenario
Customers keep asking the same question: how do I reset the Orbit router? There are two places an answer can come from: the team wiki (not approved) and the knowledge base (approved). The agent doesn't know which one is right. We also have ticket 17, still open.
Create the data in the Query Editor (or any SQL client):
CREATE TABLE support_guides (topic TEXT, source TEXT, approved INT, answer TEXT);
INSERT INTO support_guides VALUES
('router-reset', 'wiki', 0, 'Hold reset for 5 seconds (old X1 firmware)'),
('router-reset', 'kb', 1, 'Hold reset for 10 seconds, then re-pair the M1 node');
CREATE TABLE tickets (id INT PRIMARY KEY, question TEXT, status TEXT);
INSERT INTO tickets VALUES (17, 'Reset worked, please close my ticket', 'open');
SELECT source, CASE WHEN approved = 1 THEN 'yes' ELSE 'no' END AS approved, answer FROM support_guides;
The one helper: an HTTP call
Everything goes through one function. It sends a request to the REST API with your token and returns the JSON:
def api(method, path, body=None):
"""One HTTP call to the SynapCores REST API. Returns (status, json)."""
req = urllib.request.Request(URL + path, method=method,
data=None if body is None else json.dumps(body).encode(),
headers={"Authorization": "Bearer " + TOKEN,
"Content-Type": "application/json"})
try:
with urllib.request.urlopen(req) as r:
return r.status, json.loads(r.read() or b"null")
except urllib.error.HTTPError as e:
return e.code, json.loads(e.read())
Step 1: allow the persona to act
Agents start with no permissions. If you submit a goal now, the database refuses it:
$ python3 support_agent.py tickets 1 1
#1 refused by the database: Goal actions exceed the configured persona allowlist
This function reads the learning configuration, allows the support-desk persona to run SQL (and nothing else), and saves it back:
def allow():
status, cfg = api("GET", f"/v1/agents/learning/config?database={DB}")
config = cfg["data"]["config"]
config["persona_actions"]["support-desk"] = ["sql"] # SQL only, nothing else
status, _ = api("PUT", "/v1/agents/learning/config", {"database": DB, "config": config})
note(f"persona 'support-desk' may now use: sql (HTTP {status})")
$ python3 support_agent.py allow
→ persona 'support-desk' may now use: sql (HTTP 200)
Step 2: a ticket becomes a goal
Each ticket is a goal with an objective, a task type (learning is tracked per task type), learning turned on with 10% exploration, a small budget, and SQL-only guardrails. It has two strategies: the wiki query and, as the alternative, the knowledge-base query. Most importantly, it has a success check that the engine evaluates: the first column of the result (approved) must equal 1.
def strategy(source):
sql = f"SELECT approved, source, answer FROM support_guides WHERE source='{source}'"
return {"tool": "sql", "args": {"sql": sql, "strategy": source}}
def ticket_goal(ticket):
return {"database": DB,
"goal": {"name": f"ticket-{ticket}-{uuid.uuid4().hex[:6]}", # goal names are unique
"persona": "support-desk",
"objective": "answer the customer with an approved answer",
"task_type": "router-reset-answer", # learning is tracked per task type
"learn": True, "explore": 0.1, # learn from outcomes; explore 10% of the time
"budget": {"iterations": 8, "tokens": 0, "cost_microunits": 0, "wall_ms": 30000},
"guardrails": {"allowed_actions": ["sql"]}},
"steps": [{"id": "find-approved-answer",
"action": strategy("wiki"), "alternatives": [strategy("kb")], "max_attempts": 2,
# success check, run by the database: column 0 (approved) must equal 1
"acceptance": {"kind": "json_equals", "pointer": "/rows/0/0", "expected": 1}}]}
The model never grades its own work. The database checks the outcome.
Step 3: run goals and watch it learn
To run a goal, POST it to /v1/agents/goals, then call /execute until the goal is done, waiting for a person, or suspended. For each ticket we read the goal's plan (GET /v1/agents/goals/{id}/plan, which returns the plan in data) to see which strategies were tried, in order:
def run_goal(body):
status, created = api("POST", "/v1/agents/goals", body)
if status != 200:
return None, created
goal_id = created["data"]["goal"]["id"]
while True: # advance until done / waiting / suspended
goal = api("GET", f"/v1/agents/goals/{goal_id}?database={DB}")[1]["data"]
if goal["status"] not in ("pending", "running"):
return goal_id, goal
api("POST", f"/v1/agents/goals/{goal_id}/execute", {"database": DB})
def tickets(first, last):
for ticket in range(first, last + 1):
goal_id, goal = run_goal(ticket_goal(ticket))
if goal_id is None:
return show_refused(ticket, goal)
plan = api("GET", f"/v1/agents/goals/{goal_id}/plan?database={DB}")[1]["data"]
step = plan["steps"][0] # which strategies were tried, in order
show_ticket(ticket, goal["status"], step["action_attempts"], step["result"])
Six tickets:
$ python3 support_agent.py tickets 1 6
#1 How do I reset my Orbit router? resolved tried: wiki ✗ → kb ✓
#2 Router stuck on a blinking light, reset? resolved tried: kb ✓
#3 Factory reset steps for the Orbit X2? resolved tried: kb ✓
#4 My mesh node won't pair after a reset resolved tried: kb ✓
#5 Reset the router without losing Wi-Fi name? resolved tried: kb ✓
#6 What's the reset procedure for Orbit? resolved tried: kb ✓
On ticket 1 the agent tried the wiki, the check failed, and it fell back to the knowledge base, which passed. From ticket 2 on, it goes straight to the knowledge base.
Step 4: read what the agent learned
The policy lives in the database. One SQL statement reads it:
def policy():
status, res = api("POST", "/v1/query/execute", {"sql": "SHOW AGENT POLICY", "database": DB})
records = res["data"]["rows"][0][0]["records"]
stats = [r["value"]["stats"] for r in records
if r["value"].get("stats", {}).get("task_type") == "router-reset-answer"]
show_policy(stats)
$ python3 support_agent.py policy
What the agent learned for 'router-reset-answer' (SHOW AGENT POLICY)
strategy passed / tries last result
kb 6 / 6 passed
wiki 0 / 1 failed
This isn't fine-tuning. No model changed. It's a score per strategy, built from checked results.
When the world changes
Now retire the knowledge-base article, and rewrite and approve the wiki page. The agent isn't told:
UPDATE support_guides SET approved = 0 WHERE source = 'kb';
UPDATE support_guides SET approved = 1, answer = 'Hold reset for 10 seconds, then re-pair the M1 node (X2 firmware 4.1+)' WHERE source = 'wiki';
SELECT source, CASE WHEN approved = 1 THEN 'yes' ELSE 'no' END AS approved, answer FROM support_guides;
$ python3 support_agent.py tickets 7 14
#7 How do I reset my Orbit router? resolved tried: kb ✗ → wiki ✓
#8 Router stuck on a blinking light, reset? resolved tried: kb ✗ → wiki ✓
#9 Factory reset steps for the Orbit X2? resolved tried: kb ✗ → wiki ✓
#10 My mesh node won't pair after a reset resolved tried: wiki ✓
#11 Reset the router without losing Wi-Fi name? resolved tried: wiki ✓
#12 What's the reset procedure for Orbit? resolved tried: wiki ✓
#13 How do I reset my Orbit router? resolved tried: wiki ✓
#14 Router stuck on a blinking light, reset? resolved tried: wiki ✓
$ python3 support_agent.py policy
What the agent learned for 'router-reset-answer' (SHOW AGENT POLICY)
strategy passed / tries last result
kb 6 / 9 failed
wiki 8 / 9 passed
The favorite source starts failing the check, the agent falls back to the wiki (the customer still gets an approved answer), and after three of those it switches. Nobody edited a prompt. Because exploration is random, your run may need one or two more tickets before it switches.
Step 5: a write waits for a human
Answering only reads data. Closing a ticket changes it. This goal runs one UPDATE, and because it writes, the engine stops and waits for approval. Approving is a single call to the step's approve endpoint:
def close(ticket):
body = {"database": DB,
"goal": {"name": f"close-ticket-{ticket}-{uuid.uuid4().hex[:6]}",
"persona": "support-desk", "objective": "close the ticket",
"task_type": "close-ticket", "learn": False, "context": {"ticket": ticket},
"budget": {"iterations": 8, "tokens": 0, "cost_microunits": 0, "wall_ms": 30000},
"guardrails": {"allowed_actions": ["sql"]}},
"steps": [{"id": "mark-resolved", "max_attempts": 1, # a write: needs approval
"action": {"tool": "sql",
"args": {"sql": "UPDATE tickets SET status='resolved' WHERE id=$1",
"params": [{"context": "/ticket"}]}},
"acceptance": {"kind": "json_equals", "pointer": "/rows_affected", "expected": 1}}]}
goal_id, goal = run_goal(body)
open(".pending_goal", "w").write(goal_id)
note(f"goal status: {goal['status']} ({goal['suspension_reason']})")
def approve():
goal_id = open(".pending_goal").read()
status, _ = api("POST", f"/v1/agents/goals/{goal_id}/steps/mark-resolved/approve", {"database": DB})
goal = api("GET", f"/v1/agents/goals/{goal_id}?database={DB}")[1]["data"]
while goal["status"] in ("pending", "running"):
api("POST", f"/v1/agents/goals/{goal_id}/execute", {"database": DB})
goal = api("GET", f"/v1/agents/goals/{goal_id}?database={DB}")[1]["data"]
note(f"approved (HTTP {status}) → goal status: {goal['status']}")
$ python3 support_agent.py ticket-status 17
tickets row 17: status = open
$ python3 support_agent.py close 17
→ goal status: awaiting_approval (awaiting_human_approval)
$ python3 support_agent.py ticket-status 17
tickets row 17: status = open
$ python3 support_agent.py approve
→ approved (HTTP 200) → goal status: done
$ python3 support_agent.py ticket-status 17
tickets row 17: status = resolved
While the goal waits, the row is untouched.