Self-Improving Agents

Let an agent capture a reusable technique as a skill — and a durable fact as memory — after each task, automatically

Enable self_improve=True on an agent and after every task it asks itself “did I just learn something reusable, or a durable fact worth remembering?” — if yes, it writes/patches a skill and/or persists a memory for next time. Use self_improve="background" to reply first and run the review off the hot path.

from praisonaiagents import Agent

agent = Agent(
    name="Engineer",
    instructions="Help debug and fix issues. Read project files first.",
    self_improve=True,
    tools=["read_file"],
)
agent.start(
    "Debug this flaky deploy script and fix it. "
    "Read deploy.sh in the current directory first."
)

The user assigns a task; after each run the agent may write or patch a skill when it learns something reusable.

Quick Start

1. Simple Usage

   from praisonaiagents import Agent
   
   agent = Agent(
       name="Engineer",
       instructions="Help debug and fix issues. Read project files first.",
       self_improve=True,
       tools=["read_file"],
   )
   agent.start(
       "Debug this flaky deploy script and fix it. "
       "Read deploy.sh in the current directory first."
   )

   After the task ends, the agent runs a guarded review pass — but only if at least one tool was used. If a reusable technique emerged it may write a SKILL.md; otherwise it replies NO_SKILL.

2. With Configuration

   Require at least three tool calls before a review fires:

   from praisonaiagents import Agent
   
   class HeavySessionPolicy:
       def should_review(self, trajectory):
           return len(trajectory.get("tools_used", [])) >= 3
   
       def review_prompt(self, trajectory):
           return (
               "If a reusable technique emerged, call skill_manage to save it. "
               "Otherwise reply NO_SKILL."
           )
   
   agent = Agent(
       name="Engineer",
       instructions="Help debug and fix issues. Read project files first.",
       self_improve=HeavySessionPolicy(),
       tools=["read_file"],
   )
   agent.start(
       "Debug this flaky deploy script. "
       "Read deploy.sh, README-deploy.md, and check-staging.sh in order."
   )

3. Background Mode (no added latency)

   Reply first, run the review turn off the hot path — ideal for latency-sensitive gateway and bot agents:

   from praisonaiagents import Agent
   
   agent = Agent(
       name="Support Bot",
       instructions="Answer customer questions. Use read_file for playbooks when needed.",
       self_improve="background",
       tools=["read_file"],
   )
   agent.start("How do I reset my password? Check reset-playbook.md if needed.")
   # Reply returns immediately; the skill review runs in the background after tool use.

4. Chat and Async Chat

   The same self_improve flag works with chat() / achat() — the review fires after any turn that used at least one tool.

   import asyncio
   from praisonaiagents import Agent
   
   agent = Agent(
       name="Support",
       instructions="Answer customer questions. Use read_file for playbooks when needed.",
       self_improve=True,
       tools=["read_file"],
   )
   
   # Sync chat — review runs after the reply
   agent.chat("How do I reset my password? Check reset-playbook.md if needed.")
   
   # Async chat — same behaviour, non-blocking
   asyncio.run(agent.achat("Escalate this ticket. Check escalation-rules.md first."))

   The review pass is scheduled after every chat turn that used ≥1 tool — inline for self_improve=True, off the hot path for self_improve="background".

5. Background + Memory (grow skills and user model)

   With memory=True, the same guarded review pass can also persist a durable fact via store_memory — closing the learning loop for memory, not just skills.

   from praisonaiagents import Agent
   
   agent = Agent(
       name="Personal Assistant",
       instructions="You are a personal assistant on Telegram.",
       self_improve="background",   # skills: guarded background review
       memory=True,                 # memory: same pass also persists durable facts
       tools=["read_file"],
   )
   agent.chat("I prefer flights that land before 6pm — book Delhi → Bangalore next Friday.")
   # Reply returns immediately. Off the hot path, the guarded review may:
   #   • call skill_manage(...) if a reusable technique emerged, and/or
   #   • call store_memory("prefers flights landing before 6pm", ...) to remember the preference.

How It Works

After each turn — whether you called agent.start(), agent.chat(), or agent.achat(), and whether the tool ran sync or async — if self_improve is enabled:

1. The policy checks should_review(trajectory) — by default, only when ≥1 tool was called
2. The agent runs one extra turn with a restricted toolset — skill_manage always, plus store_memory when the agent has memory=True
3. The agent calls skill_manage to create/patch a skill, and/or store_memory to persist a durable fact, or replies NO_SKILL
4. The internal review exchange is trimmed back out of chat_history

Execution Modes

self_improve accepts strings that pick when the review runs relative to the reply.

• Inline (True, "inline", "blocking", "sync") — the review turn runs before the reply returns. Simplest; adds one extra LLM round-trip to reply latency.
• Background ("background", "async") — the reply returns first, then the review runs off the hot path on the shared BackgroundJobManager. No added user-visible latency.

Prefer background for latency-sensitive gateway or bot agents; prefer inline for batch jobs where latency does not matter.

Configuration Options

Agent(self_improve=...)

When the agent also has memory=True, the guarded review turn additionally exposes store_memory so the same pass can persist a durable fact off the hot path. The set stays restricted — never the agent’s full toolset.

DefaultSkillReviewPolicy

SkillReviewProtocol (custom policy)

trajectory shape: {"prompt": str, "response": str, "tools_used": list[str]}.

Choosing What to Pass

Inline vs Background

Choose based on how latency-sensitive the reply is.

Common Patterns

Agent that gets sharper over time

from praisonaiagents import Agent

engineer = Agent(
    name="Backend Engineer",
    instructions="Diagnose and fix production issues. Read logs and scripts first.",
    self_improve=True,
    tools=["read_file"],
)

# Day 1: agent solves a flaky-deploy problem from scratch.
engineer.start(
    "Why does deploy fail intermittently on the staging cluster? "
    "Read deploy.sh and check-staging.sh first."
)
# After answering, the review MAY write a skill (e.g. diagnose-flaky-deploy) — not guaranteed.

# Day 2: if a skill was saved, it is now available and the agent can reuse it.
engineer.start("Staging deploys are flaky again — same as last week?")

Persistent assistant that grows both skills and user model

from praisonaiagents import Agent

assistant = Agent(
    name="Concierge",
    instructions=(
        "You are a long-running concierge for one user across many sessions. "
        "Help with travel, calendar and reminders."
    ),
    self_improve="background",   # skills grow autonomously
    memory=True,                 # user model grows autonomously — same pass
    tools=["read_file"],
)

# Turn 1 — user reveals a preference
assistant.chat("I only fly economy on flights under 4 hours; premium economy otherwise.")

# Turn 2 — a totally new session (or process). The reply already reflects it.
assistant.chat("Find me options for Delhi → Singapore next month.")
# The background review from turn 1 may have persisted the seat-class rule via store_memory;
# on turn 2 memory recall surfaces it, so the agent proposes premium economy without asking.

Conservative policy (only review heavy sessions)

from praisonaiagents import Agent

class MinToolsPolicy:
    def should_review(self, trajectory):
        return len(trajectory.get("tools_used", [])) >= 3

    def review_prompt(self, trajectory):
        return "Save a skill via skill_manage if reusable; else NO_SKILL."

agent = Agent(
    name="Researcher",
    instructions="Research and report.",
    self_improve=MinToolsPolicy(),
    tools=["read_file"],
)
agent.start(
    "Debug this flaky deploy script. "
    "Read deploy.sh, README-deploy.md, and check-staging.sh."
)

Fully custom policy

from praisonaiagents import Agent

class TimedReviewPolicy:
    """Only review every 5th tool-using session."""
    def __init__(self):
        self.counter = 0

    def should_review(self, trajectory):
        if not trajectory.get("tools_used"):
            return False
        self.counter += 1
        return self.counter % 5 == 0

    def review_prompt(self, trajectory):
        return (
            "Reflect on this session. If a reusable technique emerged, "
            "call skill_manage to save it. Otherwise reply NO_SKILL."
        )

agent = Agent(
    name="Worker",
    instructions="Read provided files carefully.",
    self_improve=TimedReviewPolicy(),
    tools=["read_file"],
)
for prompt in [
    "Read deploy.sh and summarize the flake.",
    "Read README-deploy.md and list the checklist.",
    "Read check-staging.sh — what does it simulate?",
    "Read deploy.sh — what line causes random failure?",
    "Read all three files and write a one-paragraph runbook.",
]:
    agent.start(prompt)

Guarantees

Troubleshooting

Ran self-improve and see no SKILL.md on disk? Work through these four causes in order.

import logging
logging.basicConfig(level=logging.INFO)

from praisonaiagents import SkillManager

print(SkillManager().list_pending())   # look for your skill, then approve(id)

mkdir -p .praisonai/skills

pip install -U "praisonaiagents>=1.6.151"

from praisonaiagents import Agent

agent = Agent(
    instructions="Read files before answering.",
    self_improve=True,
    tools=["read_file"],
)
agent.chat("Read deploy.sh in the current directory and summarize.")
print("tools_used after turn:", agent._turn_tools_used)
# Expect [] here (buffer is consumed by the hook), but you should see the review turn run.

from praisonaiagents import Agent

agent = Agent(
    self_improve="background",
    memory=True,                 # required for store_memory in the review toolset
    tools=["read_file"],
)

Best Practices

from praisonaiagents import Agent

agent = Agent(name="Bot", self_improve="background", tools=["read_file"])

import os
os.environ["SKILL_WRITE_APPROVAL"] = "0"  # direct writes — local/trusted only

from praisonaiagents import Agent

agent = Agent(name="Engineer", self_improve=True, tools=["read_file"])
agent.start("Read deploy.sh and fix the flake.")

Related