SynapCores

Build an AI Agent That Learns From Verified Outcomes (Python Tutorial)

By , Founder & CTO, SynapCores · Published

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 sh
    

    or 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/login with your admin user returns data.access_token. Export it as SYNAPCORES_TOKEN, and set SYNAPCORES_URL (for example http://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.

Step 6: verify the audit ledger

Every decision, result and approval is appended to a hash-linked ledger: each entry carries the fingerprint of the one before it. We walk the chain one entry at a time and count anything that doesn't verify:

def verify():
    verified, broken, cursor = 0, 0, None
    while True:
        page = f"/v1/agents/soul/audit/verify?database={DB}&limit=1" + (f"&after={cursor}" if cursor else "")
        status, res = api("GET", page)
        if status != 200:                                         # this entry's hash doesn't match the chain
            broken += 1; cursor = str(int(cursor or 0) + 1).zfill(20); continue
        verified += 1
        if res["data"].get("complete") or not res["data"].get("next_cursor"):
            break
        cursor = res["data"]["next_cursor"]
    show_ledger(verified, broken)
$ python3 support_agent.py verify
audit ledger: 320 of 320 entries verified, 0 broken  (hash-linked, append-only)

Your count will differ: it depends on how many goals and attempts have run in the database. What matters is the second number: 0 broken. If someone edited a stored record, verification would fail at that entry. The ledger makes tampering evident; for compliance you still need access control, retention and, ideally, anchoring the latest hash somewhere independent.

What you built

A goal → a success check the database runs → a policy that learns from the results → approval before any write → a ledger you can verify. Learning is off until you turn it on, and the agent can only do what its persona is allowed to do.

Next steps:

FAQ

Is this fine-tuning the model? No. No model weights change. In this tutorial no language model is called at all: each strategy is a SQL query. What learns is a small policy that keeps a score per strategy and task type, built from outcomes the database verified.

Who decides whether an attempt succeeded? A success check you define on the goal. Here it's a JSON check on the query result (the answer row must have approved = 1), evaluated by the engine, not a model grading its own answer.

Can the agent change data on its own? Not without approval. A step that writes stops at awaiting_approval, and the row is unchanged until a person approves it. The persona also has to be explicitly allowed an action type (here, SQL only) before any goal runs.

Is autonomous learning on by default? No. Learning is opt-in per goal (learn: true), and agents have no allowed actions until you configure them.

Does this need a GPU or an LLM? No. The tutorial runs on Community Edition on a laptop. The strategies are SQL queries and the success check is deterministic.

Full script

support_agent.py:

"""Tutorial: a support agent that learns from verified outcomes (SynapCores 2.5.1, REST API).

Run:  python3 support_agent.py <step> [args]
Steps: allow | tickets FROM TO | policy | close TICKET | approve | ticket-status TICKET | verify
"""
import json, os, sys, urllib.error, urllib.request, uuid
from pretty import show_ticket, show_policy, show_status, show_ledger, show_refused, note

URL = os.environ.get("SYNAPCORES_URL", "http://localhost:8080")
TOKEN = os.environ["SYNAPCORES_TOKEN"]          # an admin access token: POST /v1/auth/login
DB = "main"


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 can do nothing until you allow it) ──
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})")


# ── Step 2: each ticket becomes a goal with two strategies and a success check ──
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}}]}


# ── Step 3: submit a goal and let the engine execute it ──
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"])


# ── Step 4: read what the agent learned ──
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)


# ── Step 5: a goal that changes data waits for a human ──
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']}")


def ticket_status(ticket):
    sql = f"SELECT status FROM tickets WHERE id={int(ticket)}"
    res = api("POST", "/v1/query/execute", {"sql": sql, "database": DB})[1]
    show_status(ticket, res["data"]["rows"][0][0])


# ── Step 6: verify the hash-linked audit ledger, entry by entry ──
def verify():
    verified, broken, cursor = 0, 0, None
    while True:
        page = f"/v1/agents/soul/audit/verify?database={DB}&limit=1" + (f"&after={cursor}" if cursor else "")
        status, res = api("GET", page)
        if status != 200:                                         # this entry's hash doesn't match the chain
            broken += 1; cursor = str(int(cursor or 0) + 1).zfill(20); continue
        verified += 1
        if res["data"].get("complete") or not res["data"].get("next_cursor"):
            break
        cursor = res["data"]["next_cursor"]
    show_ledger(verified, broken)


if __name__ == "__main__":
    step, args = sys.argv[1], sys.argv[2:]
    {"allow": allow, "tickets": lambda: tickets(int(args[0]), int(args[1])), "policy": policy,
     "close": lambda: close(int(args[0])), "approve": approve,
     "ticket-status": lambda: ticket_status(args[0]), "verify": verify}[step]()

pretty.py (terminal formatting only; no logic):

"""Terminal formatting for support_agent.py. Prints what the API returned; no logic lives here."""
G, R, Y, B, DIM, BOLD, X = "\033[32m", "\033[31m", "\033[33m", "\033[36m", "\033[2m", "\033[1m", "\033[0m"
QUESTIONS = ["How do I reset my Orbit router?", "Router stuck on a blinking light, reset?",
             "Factory reset steps for the Orbit X2?", "My mesh node won't pair after a reset",
             "Reset the router without losing Wi-Fi name?", "What's the reset procedure for Orbit?"]
STRATEGIES = ["wiki", "kb"]          # action_index 0 = the main action (wiki), 1 = the alternative (kb)


def note(text):
    print(f"{B}→{X} {text}")


def show_refused(ticket, error):
    print(f"{BOLD}#{ticket:<3}{X}{R}refused by the database:{X} {error['error']['message'].replace('Invalid argument: ', '')}")


def show_ticket(ticket, status, attempts, result):
    tried = [STRATEGIES[a["action_index"]] for a in sorted(attempts, key=lambda a: a["attempt"])]
    ok = status == "done"
    path = "  →  ".join([f"{R}{s} ✗{X}" for s in tried[:-1]] + [f"{G if ok else R}{tried[-1]} {'✓' if ok else '✗'}{X}"])
    question = QUESTIONS[(ticket - 1) % len(QUESTIONS)]
    print(f"{BOLD}#{ticket:<3}{X}{question:<44} {G + 'resolved' if ok else R + status}{X}   {DIM}tried:{X} {path}")


def show_policy(stats):
    print(f"{BOLD}What the agent learned for 'router-reset-answer'{X}  {DIM}(SHOW AGENT POLICY){X}")
    print(f"  {'strategy':<10} {'passed / tries':>15}   last result")
    for s in sorted(stats, key=lambda s: s["action"]):
        passed = int(round((s["count"] + s["reward_sum"]) / 2))   # each try scores +1 (passed) or -1 (failed)
        last = f"{G}passed{X}" if s["last_reward"] > 0 else f"{R}failed{X}"
        print(f"  {s['action'].replace('sql:', ''):<10} {passed:>8} / {s['count']:<4}   {last}")


def show_status(ticket, status):
    print(f"tickets row {ticket}: status = {BOLD}{status}{X}")


def show_ledger(verified, broken):
    col = G if broken == 0 else R
    print(f"audit ledger: {col}{BOLD}{verified} of {verified + broken} entries verified{X}, {broken} broken  {DIM}(hash-linked, append-only){X}")