DEV Community: Kacper Włodarczyk

Read a run's cost in AgenticOS

Kacper Włodarczyk — Mon, 12 Oct 2026 16:19:47 +0000

Most teams learn what an agent costs from the provider's invoice at the end of the month, with no way to tie a number to the task that produced it. AgenticOS puts a run's model, token usage, reported cost and tool events together in Activity. That lets you connect a cost figure to the task that produced it. This guide reads an existing demo record, then explains how to use those fields when testing an agent and setting a budget in the platform we build at Vstorm.

This article was drafted and revised with AI assistance. The amounts shown are from an existing demo capture. They are not provider invoices, current price recommendations or a benchmark of a representative workload.

Open one run

The record shows Support Copilot answering "how do I rotate a provider key?" through Slack. It names OpenRouter and anthropic/claude-opus-4.5, displays 5,397 input tokens and 170 output tokens, and reports $0.0312. A completed search_documents call appears in the timeline.

Read those fields together. The amount without the task says little about whether the run was useful. The token counts without the resolved model are not enough to interpret pricing. The successful status tells you the run completed, but the source passage and answer still need a quality check.

For this example, the screen helps you understand where to look. It does not establish what another document question will cost or how much a model switch would save. Use your own fixed task and inputs for that comparison.

Keep a comparison tied to the task

Suppose you want to shorten a support agent's prompt. Choose a small set of sample questions and preserve the expected source material. Run the current configuration and the proposed revision with those same cases.

Keep the configured model, answer, retrieved sources, status and total recorded usage. If fallbacks are enabled, the documented run row can retain the primary profile even when another model answers. Use a no-fallback test profile or separate provider evidence for a controlled model comparison. Check whether the shorter prompt preserves the instructions the task depends on. If the answer drops an important exception, lower usage does not make it an equivalent result.

Include retries and unsuccessful attempts when evaluating the complete task. Selecting only the cheapest successful run can hide the work needed to obtain that answer. If a model or provider setting changes as well as the prompt, record that change rather than attributing the difference to the prompt alone.

This is a proposed comparison procedure. No result from that experiment is reported here.

Include work performed before failure

A run can fail after it has already made billable model requests. AgenticOS keeps failed runs in history with their recorded usage. That makes failures relevant when reviewing the cost of a workflow, even if the user never received a final answer.

When inspecting a failed run, locate the stage that stopped. A tool error after model work is different from a request refused before execution. The record can help you connect usage with the progress made before the failure.

Do not assume that every failure has the same cost or that failures are necessarily more expensive than successful runs. Use the recorded events and usage for the actual task. If you retry, keep the earlier attempt beside the successful one when assessing the resources needed to complete it.

Read the Spend view's coverage

The existing Spend capture shows a warning about unpriced runs. A missing price is not a zero price: the displayed total can be a floor for the usage in that window.

Before comparing the dashboard with a provider account, check which model identifiers were priced and whether the provider or proxy adds charges outside that lookup. Also compare the same reporting period. A calendar-month figure and a rolling window can describe different sets of runs even when both appear on the same page.

Model usage is only one cost component of an agent workflow. External tool services, sandbox compute and storage can have separate bills. Keep those components visible when estimating the cost of operating the whole task rather than treating the model-cost field as the entire invoice.

Set the budget on the intended configuration

AgenticOS checks accounted spend before model requests. If the applicable limit has already been reached, the next request can be refused. Use the published configuration when checking which limit a run is meant to use; changing a draft setting is not the same as publishing it.

A useful trial is to use a disposable configuration with a deliberately small limit and inspect the refusal path. Check the run's status and recorded usage, then confirm which setting caused the stop. This establishes the behavior of that trial rather than a universal upper bound on every possible workflow.

The budget is not a reservation for the full future bill. A request can incur cost after passing its check, and concurrent or already committed work may not yet be reflected in the accounted total. Pricing gaps add another reason that a displayed amount may not describe all usage.

Keep those conditions beside the cap when deciding how much traffic to allow. A spending limit and a request-rate limit answer different questions, and external-service charges need their own controls.

Look at the input behind the number

Input usage can include instructions, tool definitions, retrieved material and conversation history. The actual request also depends on runtime behavior such as selection, caching and history processing. Counting the words visible in the chat does not reproduce that request.

If input grows during a long task, inspect what is being retained. Compaction can summarize history, but the summary may omit details the next step needs and producing it can require work of its own. Compare both the task result and total usage before deciding that the change helped.

The same approach applies to a smaller model: keep the source inputs and success criteria fixed, inspect the answer and record the whole task's usage. A cheaper individual request is useful only if it still does the work you need or reduces the complete workflow's cost at an acceptable quality level.

Keep a useful run record

For your first trial, retain the task input, published configuration, resolved model, output and usage together. Add unsuccessful attempts and identify any external costs the platform does not count. That gives a later prompt or model change something concrete to compare with.

The governance guide explains budgets and their accounting limits. The demo screen above shows how to read one run; a workload estimate needs observations from the tasks and traffic you actually intend to support.

Which of your agents would you want to see a cost for first, and what would you compare it with?

I'm Kacper, Principal Engineer and Open Source Tech Lead at Vstorm. I build AI agents and open-source tools in the Pydantic AI ecosystem. Find me on LinkedIn or GitHub.

Reverse-engineering a web page into a Claude Code skill

Kacper Włodarczyk — Fri, 09 Oct 2026 10:41:45 +0000

I saw a long read on Frontstory, a Polish investigative outlet, that tells its story by scrolling over one large illustrated map. You read a short card, and the map glides to a city. A few cards later it pulls back to show the whole region, then zooms somewhere else. The format is usually called scrollytelling: the text scrolls, and a picture behind it changes with every paragraph.

I wanted pages like that for explaining how AI systems work, so I asked Claude Code to take the page apart and teach itself to build them. This article follows what it did and where I had to step in. It was drafted and revised with AI assistance. Most examples shown use invented data.

The prompt

The whole request, translated from Polish, was this:

Analyse the structure of https://frontstory.pl/sabotaze. It scrolls, content appears, and it's nicely animated. Could you add a skill to our system for creating pages like this in HTML? Analyse the format thoroughly, then make three examples for the Gallery.

The skill was for Content OS, the internal system we use at Vstorm to plan, research, draft and check content. A skill there is the same thing as a Claude Code skill anywhere: a folder with a SKILL.md that tells the agent how to do one kind of job, plus whatever scripts and references that job needs. Content OS is internal, so there's nothing to install from this article. The approach is the part worth taking.

What the agent read

Claude Code downloaded the page and read its HTML. It also opened the page in a headless browser and took screenshots at desktop and phone widths, to see what a reader sees rather than only what the source says. Those copies stayed in a temporary folder. None of the page's text, images or code went into our repository.

The page turned out to be a single hand-written HTML file with no framework:

The stage. One SVG drawing fixed to the screen: the map as an image, with about fifteen illustrations placed on top of it.
Camera targets. Fourteen invisible rectangles in the SVG, each drawn around something a shot should show.
Steps. Thirty-six text cards. Each names a camera target and the illustrations to show while it is on screen.
The camera. When a card becomes active, a script measures its target rectangle and animates the SVG's viewBox toward it. Changing the viewBox is what makes the drawing appear to zoom and pan.
The trigger. An IntersectionObserver decides which card is active as you scroll.

It also noticed the rhythm, which turned out to be the real lesson: an establishing shot of the whole map, a zoom to one place, several cards held on that place while the text continues, a pull back, the next place. Most cards change only the text. The camera moves perhaps every third card.

What it built

After a few minutes of reading, the agent went straight to code. In order: a small runtime that moves the camera and shows layers, a stylesheet, a build script, a recorder that films a page, then three examples, and only then the skill. Next to the skill it saved its teardown of the original page as a reference file, with the table of parts above and the rhythm.

That file ended up being one of the most useful things in the whole skill. It explains the format in plain terms, and every later page starts from it. Asking for that teardown as its own deliverable, before any code, is a cheap way to check that the agent understood the format before it builds on that understanding.

A single article and a tool that makes many pages have different jobs, so the teardown also lists where our version differs:

Any card height works. A card becomes active when its top crosses one line on the screen, however long the card is. Long cards on a narrow phone screen were the case that drove this.
One camera at a time. A new camera move cancels the running one and starts from wherever it got to.
Nothing remote. The stage is vector, fonts are embedded, and the build refuses anything loaded from another server. The finished page is one HTML file that works offline.
Typos fail loudly. A card inherits what it leaves out from the card before, and the build rejects an attribute it doesn't know or an id that points at nothing.
Reduced motion. For readers who ask their system for less motion, the camera cuts instead of gliding.
Scroll-scrubbed animation. A card can publish how far through it the reader is, from 0 to 1, so something on the stage can grow or fill as you scroll.

None of this is a criticism of the original. It's what changes when the same idea has to survive in pages written by an agent, for subjects nobody has seen yet.

How the skill works

The skill tells the agent to design the story before drawing anything. First a beat sheet: one row per step, with the sentence the card says, what the stage shows and where the camera is. Then one stage, drawn once in one SVG, with invisible cam-* rectangles around everything a shot will frame and a .layer group for everything a step will reveal. Then the cards.

A card is ordinary HTML with a few data attributes. This one, from the example about agent requests, zooms to the app and shows three parts of the drawing:

<section class="step" data-camera="#cam-app" data-show="#b-request, #p-ask, #b-wrap">
  <h2>The app adds what the model needs</h2>
  <p>The model sees nothing but text. The app sends your message together with
     standing instructions and a description of every tool it may use.</p>
</section>

A build script turns that story.html into the finished page. Before writing anything, it checks that every camera and layer a card names exists in the drawing, that the page has a title, a language and alt text, and that nothing loads from the network. Then it opens the page in a headless browser, scrolls to every step and fails if one never becomes active, which no static check can see. With --film it also records the page as a video at reading pace, for channels that take video and not interactive pages.

The checks matter because an agent can easily write a card that points at #cam-tools when the rectangle is called #cam-tool. Without the check, that card would just do nothing, and nobody would notice until a reader did.

My first review, and the apology

The first version came back about half an hour after the prompt. I opened the examples and wrote, roughly: only the text moves and the background doesn't, the point is that the background can change too. Agent request map is nice, but the others are weak.

Then, in the same message: damn, sorry, I put that badly, the examples are actually nice. Make more of them and vary the style so there's more choice. Five to ten more.

The agent took both halves seriously. The next round added three more ways for the stage to change:

Scenes. A card can name a mood, and the stylesheet recolours the whole stage for it. In one example a city goes from dusk to night to morning as you read.
Depth. Parts of the stage can sit at different depths, so every camera move becomes parallax.
Rearranging. A page script can move the stage's own elements. In another example 400 dots, one per invented support ticket, gather into piles by topic and then stack into a bar chart.

The skill now says it plainly: a page where only the text moves is an article with a picture.

Nine examples in different styles

From the first prompt at 19:49 to the merged pull request with nine examples took about two hours. That includes two review rounds by Codex on the pull request. It found things like a page referring to files that a single-file page would lose, and old video files left behind by an earlier build, and Claude Code fixed them. I merged after the second round. A third round came back after the merge with eight more findings, which are still open.

Each one uses a different visual style and a different way of moving the stage:

a request travelling through an AI agent, with the camera hopping across one diagram
a night on call, told across a city that changes from dusk to day
a week of support tickets as dots that sort themselves
retrieval in a RAG system, with text chunks turning into points
seventy years of AI history on one long, newspaper-styled page, citing the real papers
a conversation between an agent and an MCP server, printed in a terminal as you scroll
an eval catching a regression, in loud full-colour scenes
why retries need backoff, on a chart the page computes itself
a context window filling up and being compacted as you scroll

They all sit in the Gallery of our panel, where each opens as a live page in a sandboxed frame, with a phone-width toggle.

I asked for different styles so there would be more to choose from. In hindsight they also show something else: one example only proves the agent can reproduce what it saw, while nine in different styles show the technique got separated from its original subject.

Doing this yourself

This was one evening with Claude Code, but I'd expect the same steps to carry over to other formats and other coding agents:

Point the agent at the real thing. Ask it to download the page and open it in a browser at desktop and phone width, not just to guess from a screenshot.
Ask for the teardown as its own file. A short reference that lists the parts, how they connect and what the rhythm is. Read it. If you can't follow it, the skill built on it will be shaky too.
Have it list what a reusable tool must do differently. One page and a generator have different jobs.
Then the skill. A SKILL.md with the method, a template to start from and a script that checks the output, so the agent's mistakes fail loudly.
Ask for several examples in different styles. They test whether the technique survives a new subject.
Review honestly. My reaction to the first version produced the biggest change of the evening, apology included.

And borrow the technique, never the content. The skill itself says so: a page that reuses another publication's structure takes none of its text, drawings or branding.

What this doesn't show

The skill is new. Our publication records list nothing made with it yet, so it hasn't met real readers or subjects with messy data. Most examples are teaching pieces with invented numbers. Eight review findings are still waiting. And the two hours were possible because Content OS already had a build pipeline, a Gallery and checks for other formats that the new skill could plug into.

Still, it's a good way to learn a format. Instead of only admiring a page, I can ask an agent to read it properly, build a tool from it and leave an explanation of how it works.

Which format have you seen lately that you'd want a coding agent to take apart?

The original that started it: Frontstory, "Paczka z bombą", with the interactive visualisation by Anastasiia Morozova and illustrations by Alisa Szorochowa.

I'm Kacper, Principal Engineer and Open Source Tech Lead at Vstorm. I build AI agents and open-source tools in the Pydantic AI ecosystem. Find me on LinkedIn or GitHub.

AgenticOS: self-hosted AI agents your whole team can improve

Kacper Włodarczyk — Wed, 07 Oct 2026 11:39:00 +0000

AgenticOS: self-hosted AI agents your whole team can improve

Vstorm AgenticOS is an open-source, self-hosted platform for company AI agents. It lets you build your own AI agents in a browser, give them access to your documents, and choose the tools they can use, on infrastructure you control. This week it has a new README and two decks built on the real product screens, and this article is the longer version of them.

I'm Principal Engineer and Open Source Tech Lead at Vstorm, and I build AgenticOS, so read this as the maintainer's account rather than a review. The article was drafted with AI assistance. Every product fact in it was checked against the repository at release v0.0.516 or the README pull request that ships this week.

The problem it is built around

Most agent frameworks give you a library. You write Python, you deploy it, and every change to an agent's behaviour is a pull request, a review and a release. That is the right shape for a product feature. It is a poor shape for the many small agents a company actually wants, and the AgenticOS docs put the reason in one sentence: the person who knows what the agent should say is not the person with commit access.

So AgenticOS splits the work along that line. Engineers add capabilities in typed Python. The people who know the work write the instructions, upload the documents and maintain the procedures, in the browser. Colleagues use the published agent in web chat, Slack, Mattermost or Telegram, and developers call it through the API.

The promise on the README is the short form of that: AI agents your whole team can use and improve.

What is new this week, and what is not

There is no 0.1.0. AgenticOS is still 0.0.x: the public history starts on 28 July 2026, and releases v0.0.1 to v0.0.516 followed between 2 August and 1 October. Treat the interfaces as young.

What changed is how the project explains itself:

The README now opens with what AgenticOS is and who it is for, then what you can do with it, what ships today and where it stops.
A short introduction deck (14 slides at launch) covers the problem, the idea, the product, its controls and limits, and how to start. A longer product tour (44 slides at launch) goes through every screen in detail.
The README and the decks include a list of where it stops today. The parts that matter most for an evaluation are at the end of this article.

Building an agent in the browser

An agent starts as instructions, a model and a set of tools. You choose them in the builder, publish a version, then test it in chat. Earlier versions stay readable, and you can roll back.

Three kinds of company knowledge sit beside the agent:

Skills are reusable procedures, such as how to review code or write a report. You maintain one once and attach it to several agents.
Context is standing knowledge, such as a glossary or a policy. The agent gets it in the prompt or reads it on demand.
Knowledge bases make uploaded documents searchable, so an answer can come from your own files and cite the passage it used.

With a container sandbox configured and command execution switched on, an agent can also read and edit files, run shell commands and execute Python or JavaScript. If you have used Claude Code or Codex, that part will feel familiar. What AgenticOS adds is the shared workspace around it: company knowledge, published agents and organisation access controls. What any agent achieves still depends on its model, tools and instructions.

If you'd rather watch than read, the README has a 37-second recording of one run from 1 October: an agent reads a brief in Notion, researches our GitHub repositories and publishes an interactive page with its sources. The recording is edited, with the waiting cut out, and it runs on our own projects, so it is an integration example, not a customer story.

Three controls an IT or security reviewer will ask about

Putting agents in front of a whole team raises three questions before anyone asks about features. What can it spend? What can it do without asking? What happened yesterday?

The budget is checked before every model request

Each agent can have a monthly budget, and a new organisation starts with one ($100 by default). AgenticOS checks both before each model request, not after. The docs explain why: checking afterwards means the request that broke the budget was already paid for.

There is a limit worth knowing before you rely on it. A run's cost lands on its record when the run finishes, so runs that start together cannot see one another. Fifty parallel runs against a cap that is one call short of full can each read the same under-cap total and overshoot it by up to their combined cost. If you need a strict cap, run those agents through one queue.

Sensitive tools wait for a person

A tool that acts on the outside world parks the run and waits. A person sees the call, approves or rejects it, and the decision is recorded with who asked and who decided. You set this per tool or per capability. In the screenshot the same test account asked and decided. The permission to decide approvals is its own, and the built-in Operator role holds it without being able to edit agents.

The limit here is coverage. The gate applies to the platform's own capability tools. Tools from an MCP server (the Model Context Protocol, an open standard for connecting agents to external tools) pass through it only when a web-chat session is set to Ask about everything, and a tool that runs inside the model provider never reaches the local gate. Test the approval policy for the tools you actually enable.

Every run is recorded

Every run lands in run history with the agent version that executed, the tools it called, the tokens and the cost. Because the version is recorded, a run from last week still makes sense after someone rewrites the agent.

Governance actions go into a separate audit log: approval decisions, sharing and membership changes, secret rotation, exports and more. Each entry carries a hash over its own contents with the previous entry's hash folded in, per organisation, so editing, reordering, inserting or deleting an entry shows up when the chain is verified. That is detection, not prevention. It does not protect against someone holding the database's own credentials, who can rewrite a row and recompute the chain. And not every write is audited. Knowledge-base edits, for one, are not.

For developers: code defines, configuration composes

AgenticOS is built on Pydantic AI, the Python agent framework from the Pydantic team, and pydantic-ai-harness, a set of ready-made capabilities for Pydantic AI agents such as planning and tool-output limits. The backend is FastAPI with PostgreSQL (pgvector for the document search), Redis and Prefect for background and scheduled jobs, and the console is Next.js.

The built-in capabilities are typed Python that an engineer writes, tests and registers. The console can only switch on what code registered, which the docs call "code defines, configuration composes". That is the boundary that lets the person who owns an agent's instructions change them without a release.

MCP servers are the exception, and it is worth knowing before you choose a platform for a team. A builder or an admin connects one by pasting its URL, with no code change, and its tools sit outside the approval gate described above unless a chat asks about everything. Decide who holds the Builder role with that in mind.

Running it yourself

The quick start is a Docker Compose deployment through an installer script, on macOS, Linux or Windows under WSL2. You can run it with --check first to test the prerequisites without installing anything, or read the script, or follow the manual installation guide. You need access to a model: a hosted provider, or a local model through Ollama or an OpenAI-compatible server such as vLLM, both of which serve open-weight models on your own hardware.

Self-hosting the console does not make everything local. A hosted model, a cloud document parser or an external tool still receives the data you send it, so review the destinations you configure.

Two things from the repository that a self-hoster may find more useful than a feature list:

The first bottleneck was the database pool, not CPU. On 16 September we load-tested one laptop: one worker, a stub model instead of a paid provider, 4,740 requests across a ramp, a sustained rate, a burst and a recovery. With the default pool of 5 connections plus 10 overflow, 1,537 requests failed. With 20 plus 30, 13 failed. CPU peaked at about 90 percent of one core in both runs. The shipped defaults are still 5 plus 10, so if you expect parallel load, raise DB_POOL_SIZE and DB_MAX_OVERFLOW first. This is one machine and a stub model, a request rate rather than a user count, so it says where the first wall is, not what a production deployment can carry.

There is a HIPAA configuration profile, and it is not a certification. It covers the technical safeguards of 45 CFR §164.312 and nothing else: TLS to Postgres, Redis and the browser, a long vault key, a local model, local traces, single sign-on (OIDC or Kerberos), invite-only or closed signup, six years of audit retention and the audit chain. A doctor command checks the profile and exits non-zero when something is missing. The administrative and physical safeguards, encryption of content at rest and any business associate agreement remain the operator's job, and the profile says so.

What it does not do yet

This is the short list for an evaluation:

No ACL mirroring. Permissions from SharePoint or Google Drive are not copied per user into a knowledge base. Scope the credential and share the collection with the right group.
No SAML, no SCIM, no native MFA. OIDC, LDAP and Kerberos sign-in work. A SAML-only identity provider can come in through a broker such as Keycloak, and multi-factor is your identity provider's job.
No Kubernetes manifests. It is Docker Compose on one host today.
No reranker. Retrieval is vector search with options.
No visual workflow builder. It is in development and not in any release.
Budgets can be overshot by parallel runs, as described above.

The README and the decks add a few more, such as no built-in Microsoft 365 trigger.

Try it

Start with the introduction deck if you want the shape of it: https://vstorm-co.github.io/agenticos/presentation/

For every screen in detail, the product tour: https://vstorm-co.github.io/agenticos/presentation/tour/

Then the quick start and the document-assistant walkthrough, which uploads a handbook, asks questions and checks the answers against cited sources: https://github.com/vstorm-co/agenticos

It is Apache-2.0. Issues and pull requests are open, and I'd especially like to hear what would stop you from running it: a missing sign-in method, a deployment target, a control your security team would ask for.

I'm Kacper, Principal Engineer and Open Source Tech Lead at Vstorm. I build AI agents and open-source tools in the Pydantic AI ecosystem. Find me on LinkedIn or GitHub.

How We Built the AgenticOS Desktop Pets

Kacper Włodarczyk — Thu, 10 Sep 2026 11:27:42 +0000

Amigo walks around the desktop, follows the cursor with his eyes, and says “No more caramba.” Move the cursor back and forth over him and he closes his eyes with a little heart above his head.

He's one of five pets in the AgenticOS desktop app. You can also pick a ghost, a small terminal on legs, a sprout, or a round creature with an antenna. They share the same movements, but each has its own appearance and lines.

AgenticOS is an open-source project I'm building at Vstorm for creating and using AI agents. The pet is a small extra in its Tauri desktop app. This article is about how that extra works: drawing the characters, deciding what they do, and keeping them on the desktop beside the main window.

Amigo has his own window, so he can stay visible when the main app is minimised.

Drawing a pet from separate parts

The artwork starts as a small grid. Each character in the grid represents a colour, and a dot represents a transparent pixel. The body, eyes, feet and other details are placed on top of one another to produce a frame.

That means we can change the expression without drawing the whole character again. A blink uses closed eyes in place of open ones. A wave moves the arm. A hop lifts the parts together and then brings them back down.

Each pet has its own body and coordinates for those parts. The ghost has no feet, while Amigo has a sombrero and moustache. The animation code works with those differences, using the parts that each character provides.

The definitions live in pet-sprites.js. In the same file, a waving animation is described by these two positions:

wave: () => [{ arm: "up" }, { arm: "down" }],

That's an excerpt from the animation table, rather than a standalone program. The renderer combines each position with the selected pet's artwork. Other entries describe blinking, walking, sleeping and hopping in the same way.

For these simple characters, that gives us a shared set of movements to work on. A new pet needs artwork and part positions, then it can use the existing animations. A character with a very different shape or movement would need more work. Sprite sheets would still be a reasonable choice for more detailed, individually drawn animation.

Deciding when to move

Drawing the frames is separate from choosing what happens next. That second part lives in pet-engine.js.

When left alone, the pet spends most of its time standing still. It occasionally looks around, walks a little, or dozes. At night, it dozes instead of choosing another stroll. When it reaches the edge of the usable screen area, it turns back.

Those decisions are functions with explicit inputs. The choice of the next behaviour takes a random-number function and the hour. Walking takes the current position, direction, elapsed time and screen boundaries. None of those calculations needs to open a desktop window.

That makes the rules easier to check independently. You can supply a particular hour or position and inspect the result without waiting for a pet to happen to do the right thing on screen. The repository includes tests alongside the pet code for these behaviours.

Making the cursor interaction feel intentional

The eyes follow the cursor, with a small area around the centre where they keep looking straight ahead. Otherwise, small pointer movements near the middle would keep changing their direction.

Stroking needs a different rule. A cursor passing over the character once shouldn't trigger the same reaction as moving back and forth over it. The engine tracks changes in direction within a short time window. Enough changes trigger the closed eyes and heart animation.

Clicking makes the pet wave and say something. Double-clicking brings the AgenticOS window forward. Hovering reveals a “+ New chat” button, and the right-click menu lets you change the character or hide it.

These interactions give the pet a few useful links back to the app without requiring it to move constantly. It also respects the operating system's reduced-motion setting by standing still while remaining draggable.

Giving it a window of its own

The pet lives in a transparent, always-on-top Tauri window. The main console is a separate window, so minimising or closing that window doesn't remove the pet while the app is still running.

The app remembers the selected character, whether it's visible, and where it was left. On the next launch, you don't need to pick the same pet and drag it back into place.

The console itself loads the web app from the configured AgenticOS server. You still need that server running. Installing the desktop shell doesn't install the platform or make it available offline.

One current limitation is that the pet doesn't show agent activity. A sleeping Amigo doesn't mean your agent has stopped, and a wave doesn't mean a task has finished. Connecting those events to the pet would require an explicit connection between the web app and the desktop shell. For now, its reactions come from the interactions described here.

Where to look in the code

If you'd like to explore the implementation, start with these three files in desktop/ui:

pet-sprites.js holds the artwork, part positions and animation frames.
pet-engine.js handles behaviour, movement and cursor interactions.
pet-lines.js contains what each character says.

The desktop documentation covers the Tauri setup and commands for running it against your own AgenticOS installation.

Changing a line in pet-lines.js is a small place to start. Changing the artwork gives you something more visible to play with. You can explore either without needing to understand the agent builder or the rest of the platform first.

Kacper Włodarczyk, building AgenticOS at Vstorm.

24 Claude Code Skills to Fix Your AI Stack: Introducing production-stack-skills and content-skills

Kacper Włodarczyk — Mon, 20 Apr 2026 11:59:05 +0000

78% of Fortune 500 companies are adopting AI coding assistants. 45% of that generated code ships with security vulnerabilities. On the content side, 76% of readers identify AI-written text within three seconds, and engagement drops around 47% when they do.

Those three numbers describe the same problem from two angles: AI outputs need guardrails, whether the output is code or writing. Today we're shipping two Claude Code skill packs that sit on those guardrails.

A Claude Code skill is a packaged slash command that augments your AI coding agent with a specific expertise, readable via SKILL.md and invocable from any AGENTS.md-compatible runtime. The Skills Wave is two of those packs, released the same day because the failure modes on both sides of the AI workflow deserve the same fix.

I'm Kacper, AI Engineer at Vstorm, an Applied Agentic AI Engineering Consultancy. We've shipped 30+ production AI agent implementations and open-source our tooling at github.com/vstorm-co.

production-stack-skills: 10 Claude Code Skills for Production-Ready AI Code

production-stack-skills is a 10-skill pack that audits AI-generated code across six weighted categories and hands back a 0 to 100 production-readiness score with a prioritized action plan.

The flagship command is /production check. You point it at a repo, it reads the FastAPI routes, Postgres migrations, Dockerfiles, and config, and returns:

A headline score (e.g., "Production Readiness: 34/100")
Six category scores: security, error handling, observability, deployment, data layer, code quality
A Quick Wins section with point deltas
An Action Plan sorted by weighted impact

In first internal runs across client repos, Quick Wins alone consistently moves the score about 30 points. That's the number I'd quote if a CTO asked "what does running this for a morning actually buy me".

The other nine skills split by surface area: /production review, /production planner, /production fastapi, /production postgres, /production docker, /production deploy, /production monitoring, /production security, /production error-handling. Each is a focused slash command rather than a sub-mode of a monolithic agent.

content-skills: 14 Brand-First Skills That Kill AI Slop

content-skills is a 14-skill pack with a /brand/ directory at its core, so every piece of content generated after a five-minute brand interview reads your BRAND.md, VOICE.md, VISUAL.md, and voice samples before writing a word.

Run /content setup once. Five questions. It writes /brand/. From that moment, every content skill auto-reads that directory on every invocation.

The exit point is /content audit. Score any piece of content 0 to 100 on voice consistency, anti-slop markers, visual consistency, and brand alignment.

Between setup and audit sit 12 production skills: strategy, calendar, blog, twitter, linkedin, reddit, hackernews, presentation, infographic, image, video, repurpose.

One Install, Dual-CLI, Uninstall-Safe

curl -fsSL https://raw.githubusercontent.com/vstorm-co/production-stack-skills/main/install.sh | bash
curl -fsSL https://raw.githubusercontent.com/vstorm-co/content-skills/main/install.sh | bash

Each install mirrors the skills into both ~/.claude/ (Claude Code) and ~/.agents/ (Codex, Amp, and anything AGENTS.md-compatible). You don't pick the runtime up front. A skill written for Claude Code works identically in Codex.

Uninstall is boring by design. /content-skills uninstall removes the skills. Your /brand/ stays.

Both repos are MIT.

Why Two Packs Shipped the Same Day

In 30+ production AI agent deployments at Vstorm, the failures cluster into two shapes: code that passes demo but fails the first prod incident, and content that sounds like the AI wrote it because the AI wrote it.

One pack addresses the first. The other addresses the second. Both use the same architecture because the lesson that skills beat monolithic agents applies to both. You don't want "one AI that does everything". You want 24 small, composable, auditable slash commands that you can swap, tune, or remove when they stop pulling weight.

Key Takeaways

production-stack-skills ships 10 skills with a 0-100 scorer and Quick Wins section that typically moves scores +30 in under five minutes.
content-skills ships 14 skills built around a /brand/ directory auto-read on every invocation.
Both packs install via one curl command, mirror into ~/.claude/ and ~/.agents/, work on Claude Code, Codex, and any AGENTS.md-compatible runtime.
Skill-first architecture beats monolithic agents for auditability and local updates.
Both repos are MIT.

Frequently Asked Questions

What are Claude Code skills and how do I install them?

Claude Code skills are packaged slash commands backed by a SKILL.md file that extends a coding agent with specific expertise. You install a skill pack with a single curl command that mirrors files into ~/.claude/ and ~/.agents/. After install, slash commands become available immediately without restart.

What's the difference between production-stack-skills and content-skills?

production-stack-skills audits and hardens AI-generated code across security, error handling, observability, deployment, data, and code quality, returning a 0-100 score. content-skills audits and produces on-brand content using a /brand/ directory you set up once, returning voice-consistency and anti-slop scores.

Do these skills work with Codex or only Claude Code?

Both. Each install script mirrors files into both ~/.claude/ and ~/.agents/, so the same skill works in Claude Code, Codex, Amp, and any AGENTS.md-compatible runtime without modification.

How long does `/production check` take on a real repo?

On a typical FastAPI + Postgres repo of a few thousand lines, about a minute. The Quick Wins section is what you act on first, usually under five minutes to apply.

When should I use a Claude Code skill instead of writing a full agent?

Use a skill when the job is scoped expertise invoked explicitly (audit this, write a post in my voice). Use a full agent when the job is open-ended, multi-step, and requires planning across tools. Skills are composable building blocks; agents orchestrate them.

Get Started

production-stack-skills: github.com/vstorm-co/production-stack-skills
content-skills: github.com/vstorm-co/content-skills
Full writeup: oss.vstorm.co/blog/skills-wave-launch-claude-code-skills

Follow me on LinkedIn for the follow-ups: Wednesday's production deep-dive, Thursday's content walkthrough, Friday's "8 Lessons from Shipping 24 Claude Code Skills".

Full Observability in AI Agents: What We Added to the pydantic-deepagents TUI

Kacper Włodarczyk — Sat, 18 Apr 2026 09:58:43 +0000

Full Observability in AI Agents: What We Added to the pydantic-deepagents TUI

This is a cross-post. Canonical version: oss.vstorm.co/blog/ai-agent-tui-observability-pydantic-deep/

This week I covered how pydantic-deepagents handles stuck loops, context window blindness, and frictionless installation. Today: what you actually see when all of that runs.

The problem with invisible agents

When an AI agent runs, a lot happens between your prompt and the response. The model reasons. It calls tools. Each action burns tokens and costs money. Without observability, you're flying blind — you can't debug, optimize, or trust what's happening.

pydantic-deepagents v0.3.5 — the modular agent runtime for Python — reworks the TUI to surface everything.

What changed

Per-turn token usage

Below every assistant response:

in:2.1K · out:412 · total:2.5K · reqs:3

in = input tokens, out = output tokens, total = turn total, reqs = API calls in this turn.

Cumulative cost in the header

pydantic-deepagents  in:45K out:3K · $0.12

Updates after each response. You always know the running total.

Thinking streamed live → collapsed

Model reasoning appears as dimmed text while running. Collapses to a one-line summary when done. Watch the agent reason without drowning in it.

Side panel on startup

Opens automatically when terminal ≥100 chars wide. Shows subagents before any task:

Subagents:
• planner (idle)
• research (idle)

Status updates as agents are delegated work.

All tool calls visible

Todo tools (read_todos, write_todos, add_todo, update_todo_status, remove_todo) were previously hidden. Now surfaced. Every agent action is visible.

Session saved on crash

_save_session() is now in a finally block. Crash, exception, keyboard interrupt — messages.json is always written. No more lost sessions.

Subagent logs: 20K chars (was 2K)

tool_log.jsonl now stores full subagent output. Critical for /improve — the pipeline that extracts learnings from sessions (more on that tomorrow).

The full layout

┌─────────────────────────────────┬──────────────────┐
│ pydantic-deepagents  in:45K out:3K · $0.12         │
├─────────────────────────────────┼──────────────────┤
│ [thinking... dimmed text]       │ Subagents:       │
│ [collapsed to summary]          │ • planner (idle) │
│                                 │ • research (idle)│
│ Agent response here...          │                  │
│ in:2.1K · out:412 · $0.04       │                  │
└─────────────────────────────────┴──────────────────┘

Try it

curl -fsSL https://oss.vstorm.co/install.sh | bash

GitHub: github.com/vstorm-co/pydantic-deep

Observability is how you debug, optimize, and trust your agent. A black box is a liability.

What's the first metric you check when debugging an agent run?

Browser Automation + /improve: AI Agents That Browse the Web and Fix Themselves

Kacper Włodarczyk — Fri, 17 Apr 2026 12:20:41 +0000

This week I shipped 5 versions of pydantic-deepagents — the modular agent runtime for Python. Today: the two features that close the loop — browser automation and session-based self-improvement.

Part 1: BrowserCapability — 9 Playwright Tools

pip install 'pydantic-deep[browser]'
playwright install chromium

from pydantic_deep.capabilities import BrowserCapability

agent = create_deep_agent(
    model="anthropic:claude-opus-4-6",
    extra_capabilities=[BrowserCapability(
        allowed_domains=["github.com", "docs.python.org"],
        auto_screenshot=True,
    )]
)

The 9 tools: navigate, click, type_text, get_text, screenshot, scroll, go_back, go_forward, execute_js.

Safety design: Single-tab (predictable state), domain allowlist (agent can't navigate outside allowed domains), automatic popup interception, content truncation to prevent context overflow.

Browser lifecycle: Chromium starts before the agent run, stops after — whether the run succeeds, fails, or is cancelled. No orphaned processes.

CLI:

pydantic-deep tui --browser --browser-headed   # visible window
pydantic-deep run "research X on GitHub" --browser --sandbox docker

Bug fix: Browser tools now force kind='function' — they never trigger approval dialogs mid-task.

Part 2: /improve — Session-Based Self-Improvement

After each session, /improve analyzes the full run and extracts:

UserFactInsight — what the agent learned about you and your preferences
AgentLearningInsight — strategies that worked, failure modes encountered

Both write to MEMORY.md. Next session loads MEMORY.md automatically.

Key finding: We tested summaries vs raw tool traces as input to the synthesis step. Raw traces performed significantly better — summaries compress away the signal that matters. /improve reads from tool_log.jsonl (written per session), not from a summary.

The loop: agent runs → /improve extracts insights → MEMORY.md grows → next run starts smarter.

This Week's Full Stack

Monday: StuckLoopDetection | Tuesday: LimitWarnerCapability | Wednesday: curl install | Thursday: Docker sandbox | Today: browser + /improve

An agent that detects loops, knows its context limits, installs in 30s, runs in Docker, browses the web, and learns from every session.

Full breakdown: https://oss.vstorm.co/blog/browser-automation-improve-ai-agents-pydantic-deep/

GitHub: https://github.com/vstorm-co/pydantic-deep

curl | bash for AI Agents: One-Command Install for pydantic-deep

Kacper Włodarczyk — Wed, 15 Apr 2026 11:57:47 +0000

The standard Python AI tool install experience:

Install Python (which version?)
Create a venv
pip install
ModuleNotFoundError: No module named 'textual'
pip install again with correct extras
Figure out PATH

Seven steps. Fifteen minutes. That's before you've even seen the tool.

We fixed this for pydantic-deep — the modular agent runtime for Python:

curl -fsSL https://raw.githubusercontent.com/vstorm-co/pydantic-deep/main/install.sh | bash

That's it.

What install.sh does

Detects whether uv is installed
If not: installs uv via the official Astral installer
Runs uv tool install "pydantic-deep[cli]" — isolated environment, binary available globally
Verifies the install
Prints PATH fix instructions if needed

No virtual environment management. No extras guessing. The cli extras group includes everything including textual (which was the original bug — it was missing from the base install).

Self-update

pydantic-deep update

Uses uv tool upgrade if available, falls back to pip. One command to stay current.

Startup notifications

Every invocation checks PyPI for updates silently (2-second timeout, 24-hour cache):

Update available: v0.3.6 → v0.3.7  Run: pydantic-deep update

Never blocks startup.

Why uv?

uv tool install is designed exactly for this use case — isolated tool environments, global binary access, no activation required. Fast, well-maintained, increasingly standard for Python CLI tooling.

Alternatives considered: pipx (slower, needs separate install), Homebrew tap (maintenance overhead), native binary (too brittle for dynamic imports).

Full write-up with implementation details: oss.vstorm.co/blog/pydantic-deep-one-command-install-curl-bash

GitHub: github.com/vstorm-co/pydantic-deep

What's the worst install experience you've had with an AI/ML tool?

Context Window Blindness: Why Your AI Agent Doesn't Know It's Running Out of Space

Kacper Włodarczyk — Tue, 14 Apr 2026 11:05:25 +0000

On Monday I showed how agents waste tokens by getting stuck in loops — repeating the same tool call dozens of times, burning money on nothing. Today — a quieter problem that costs just as much, and is far harder to spot.

Your AI agent has been going blind. It had no idea its context window was 90% full.

The Problem: Two Different Realities

When you run a long agent task, here's what you see: a status bar showing "Context: 87% used." It's right there in the TUI. You can see the agent is almost out of space.

But the model can't see the status bar. It has no idea.

From the model's perspective, every message it writes, every tool call it makes, every plan it sketches — all of that just continues normally. It has no signal that the conversation history is filling up. It keeps producing long responses, initiating multi-step plans, making tool calls that generate pages of output.

Then at 90%: auto-compression kicks in. The model's working memory gets force-compressed. It loses the thread of what it did 40 messages ago. It starts contradicting its earlier decisions.

This is context window blindness: the gap between what the user sees and what the model knows about its own situation.

The Fix: LimitWarnerCapability

In pydantic-deep v0.3.8 — the modular agent runtime for Python — we added LimitWarnerCapability. The solution: inject usage information directly into the conversation as a user message, at two thresholds.

At ~70% usage:

You are approaching the context limit. Begin wrapping up your current task. Avoid starting new complex subtasks.

At ~85% usage:

CRITICAL: Your context window is almost full. Use /compact NOW before continuing.

These are injected as user messages — not system prompt modifications. The model treats them as authoritative input.

from pydantic_deep import DeepAgent

agent = DeepAgent(
    model="claude-opus-4-5",
    context_manager=True,  # default — enables LimitWarnerCapability
)

Auto-enabled by default. No configuration needed.

BM25 History Search

We also rewrote search_conversation_history from naive substring to BM25:

# Before v0.3.8
results = [msg for msg in history if query in msg.content]

# After v0.3.8 — BM25 ranked, zero external deps
results = search_conversation_history(history, "explain the authentication flow")
# Rare terms rank higher. Multi-word queries tokenized properly.

Pure Python. Zero external dependencies. Standard Lucene BM25 formula.

EvictionCapability

Large tool outputs are intercepted via the after_tool_execute hook before they enter message history — not trimmed after. The difference matters on long tasks.

Key Takeaways

Models have no intrinsic awareness of context usage — that info lives in the orchestration layer
LimitWarnerCapability bridges that gap with runtime user message injection at 70%/85%
BM25 replaces naive substring search for conversation history
EvictionCapability prevents large outputs from entering history at all

Full write-up: oss.vstorm.co/blog/context-window-blindness-ai-agents-limit-warner

GitHub: github.com/vstorm-co/pydantic-deep

Have you hit this? How did the hallucinations manifest?

StuckLoopDetection: How We Stopped an Agent Burning $12 on 47 Identical Calls

Kacper Włodarczyk — Mon, 13 Apr 2026 12:20:49 +0000

TL;DR: Most agent loops aren't model failures — they're mechanical repetitions that the model itself doesn't recognize. pydantic-deep v0.3.8 introduces StuckLoopDetection, a capability that catches three loop patterns before they waste tokens.

This is post 1/3 in the "Self-Aware Agents" series. Overview of all 5 releases here.

Here's the incident that made this necessary.

A coding agent was working on a refactor task overnight. It hit a file with an unusual import pattern, couldn't parse the result, and defaulted to reading the file again.

By morning: 47 calls to read_file on the same path. $12 in API costs. Zero progress.

The model wasn't broken. Each call looked locally reasonable. From outside: it was stuck.

Why Prompting Isn't Enough

"Don't repeat tool calls" in a system prompt works sometimes. The problems:

The model often doesn't recognize loops as loops — each repeated call looks locally justified
Prompt compliance degrades under cognitive load (long tasks, many tools, complex context)
You have to add the instruction to every agent separately

Detection at the capability level fixes all three.

The Three Loop Patterns

Pattern 1: Repeated Identical Calls

Turn 12: read_file(path="src/config.json")  → {"imports": [...], "unknown_field": ...}
Turn 13: read_file(path="src/config.json")  → {"imports": [...], "unknown_field": ...}
Turn 14: read_file(path="src/config.json")  → same result

Agent can't process the result, has no fallback, tries again. Default threshold: 3 calls.

Pattern 2: A-B-A-B Alternating

Turn 8:  list_directory(path="src/")
Turn 9:  read_file(path="src/main.py")
Turn 10: list_directory(path="src/")
Turn 11: read_file(path="src/main.py")

Tool A suggests Tool B, Tool B suggests Tool A. Looks like progress — it's not.

Pattern 3: No-Op Loops

Same call, same result, keeps going. Common with writes, status checks, verification calls.

The Implementation

from pydantic_deep import create_deep_agent
from pydantic_deep.capabilities import StuckLoopDetection

# Default: enabled with threshold=3
agent = create_deep_agent(
    model="anthropic:claude-opus-4-6",
    stuck_loop_detection=True,
)

# Custom config
agent = create_deep_agent(
    model="anthropic:claude-opus-4-6",
    capabilities=[
        StuckLoopDetection(
            max_repeated=5,
            action="warn",   # "warn" = ModelRetry, "error" = StuckLoopError
        )
    ],
)

action="warn" (default)

Triggers ModelRetry. The model gets a message:

You have called read_file(path="src/config.json") 3 times with identical arguments
and received the same result. This indicates a stuck loop. Try a different approach.

Most of the time, the model pivots. If it doesn't — the threshold triggers again.

action="error"

Raises StuckLoopError. Clean failure for automated pipelines.

from pydantic_deep.capabilities import StuckLoopDetection, StuckLoopError

try:
    result = await agent.run("refactor the imports in src/")
except StuckLoopError as e:
    print(f"Agent got stuck: {e.pattern} pattern detected")

Per-Run Isolation

Parallel agent.run() calls don't share stuck-detection state. Each run is isolated via for_run() — no leaked state between concurrent tasks.

# Safe to run concurrently with a shared agent instance
results = await asyncio.gather(
    agent.run("analyze src/module_a.py"),
    agent.run("analyze src/module_b.py"),
)

The Business Case

A 47-call loop at Claude Opus pricing: ~$12. Same task with detection: ~$0.50 + one ModelRetry.

Cost of stuck_loop_detection=True: zero API calls, negligible latency, enabled by default.

Even false positives are cheap: one ModelRetry message, then the model tries a different approach.

Tomorrow: LimitWarnerCapability — teaching agents to know their context window is almost full.

Get Started

curl -fsSL https://raw.githubusercontent.com/vstorm-co/pydantic-deep/main/install.sh | bash

GitHub: github.com/vstorm-co/pydantic-deep
OSS portal: oss.vstorm.co

Pydantic Deep Agents 0.3.3: ACP, Thinking, Lifecycle Hooks, and Opinionated Defaults

Kacper Włodarczyk — Thu, 02 Apr 2026 15:29:56 +0000

We just released pydantic-deep 0.3.3 — and this is the biggest release since we open-sourced the project. ACP support, deep subagents by default, thinking, Anthropic caching, lifecycle hooks, skills as slash commands, and a provider setup wizard.

Let's walk through the changes.

ACP: Your Agent in Any Editor

ACP (Agent Client Protocol) is a standardized protocol that lets AI agents run inside editors. Think of it like LSP, but for AI agents instead of language servers.

Our new apps/acp/ adapter exposes any pydantic-deep agent as an ACP-compatible server. The same agent you run in your terminal now runs in Zed with zero code changes.

What you get:

Streaming text deltas — real-time output, not waiting for completion
Tool call visibility — see tool names, arguments, and results (not a black box)
Model switching — change from Claude to GPT mid-session
Session management — conversation persistence across editor restarts
Auto-detect provider — reads your API keys, no manual config

The adapter wraps the same create_deep_agent() you already use. No new API to learn.

Because ACP is a protocol (not a Zed-specific plugin), it'll work with any editor that adopts it. We expect more editors to support ACP in the coming months.

Subagents Are Now Deep Agents by Default

This is the change that affects the most users.

Previously, subagents were plain pydantic-ai Agents — lightweight, but limited. They couldn't read files, search the web, or remember things between runs.

Now, every subagent (built-in and custom) is created via create_deep_agent() with:

Filesystem access (read, write, edit, grep, glob)
Web search and web fetch
Persistent memory
Large output eviction (auto-save to files when output exceeds 20K tokens)
Orphaned tool call patching

If your custom subagent doesn't specify agent or agent_factory, it automatically gets the full deep agent factory. You don't have to change anything — your subagents just got more capable.

We also replaced include_general_purpose_subagent with include_builtin_subagents, which adds a "research" deep agent for codebase exploration and web research.

Thinking Enabled by Default

thinking="high" is now the default. This enables model reasoning via pydantic-ai's Thinking capability.

We support 7 levels:

agent = create_deep_agent(
    model="anthropic:claude-opus-4-6",
    thinking="high",  # default
    # Options: True, False, "minimal", "low", "medium", "high", "xhigh"
)

For models that don't support thinking (like GPT-4.1), the parameter is silently ignored.

Anthropic Prompt Caching — On by Default

Three new defaults enabled automatically:

anthropic_cache_instructions — cache system prompt
anthropic_cache_tool_definitions — cache tool schemas
anthropic_cache_messages — cache conversation history

This reduces token costs and latency for Anthropic models significantly. For non-Anthropic models, these settings are silently ignored.

5 New Lifecycle Hooks

class HookEvent(Enum):
    BEFORE_RUN = "before_run"
    AFTER_RUN = "after_run"
    RUN_ERROR = "run_error"
    BEFORE_MODEL_REQUEST = "before_model_request"
    AFTER_MODEL_REQUEST = "after_model_request"

These map directly to pydantic-ai's lifecycle hooks. Use cases:

Session tracking — log when an agent run starts and ends
LLM call logging — capture every model request for debugging
Error alerts — get notified when a run fails
Cost monitoring — track token usage per request

Skills as Slash Commands

Skills now work as slash commands in the CLI. Type /code-review and the skill activates directly from the picker.

Discovery follows a 3-tier hierarchy:

Built-in (apps/cli/skills/) — ships with pydantic-deep
User (~/.pydantic-deep/skills/) — your personal skills
Project (.pydantic-deep/skills/) — project-specific skills

Later sources override earlier ones by name, so you can customize built-in skills per project.

Other Notable Changes

compact_conversation tool — the agent can manually trigger context compression with an optional focus topic
Provider setup wizard — first-run auto-detects missing API keys and guides through provider selection
/provider slash command — switch AI provider and model mid-session
/config slash command — view and change settings interactively
approve_tools config — choose which tools need user approval (default: ["execute"])
Enhanced BASE_PROMPT — Claude Code-inspired sections for code quality, careful execution, and formatting
Context files simplified to AGENTS.md and SOUL.md only

Opinionated Defaults

The philosophy behind 0.3.3: make the powerful thing the default thing.

Setting	Before	After
Memory	off	on
Thinking	off	`"high"`
Prompt caching	off	on (Anthropic)
Subagent type	plain Agent	deep agent
Max nesting depth	0	1
Eviction limit	none	20K tokens
Patch tool calls	off	on

You get a capable, production-ready agent with create_deep_agent("anthropic:claude-opus-4-6"). No configuration needed.

Get Started

pip install pydantic-deep-agents

Or try the CLI:

pip install pydantic-deep-agents[cli]
pydantic-deep

Full changelog: CHANGELOG.md

Repo: github.com/vstorm-co/pydantic-deepagents

We build open-source AI agent tooling at Vstorm. pydantic-deep is our framework — modular, type-safe, production-tested across 30+ deployments.

Pydantic AI Capabilities, Hooks & Agent Specs - What Changed and How Our Libraries Migrated

Kacper Włodarczyk — Mon, 30 Mar 2026 14:38:10 +0000

Pydantic AI just shipped the biggest API change since launch. Capabilities, hooks, and agent specs landed in v1.71+, and they fundamentally change how you extend agents.

We maintain 5 open-source libraries built on top of Pydantic AI: pydantic-ai-shields (formerly pydantic-ai-middleware), pydantic-ai-subagents, pydantic-ai-summarization, pydantic-ai-backend, and the full-stack AI agent template. All five have been migrated. This article covers what changed, why it matters, and real before/after code from our repos.

What Are Capabilities?

Capabilities are reusable, composable units of agent behavior. Instead of threading multiple configuration arguments separately -- tools here, instructions there, model settings somewhere else -- a capability bundles everything into a single capabilities parameter on the Agent constructor.

Each capability can provide:

Tools (via get_toolset())
Instructions (static strings or dynamic callables)
Model settings (per-step configuration)
Lifecycle hooks (before/after/wrap patterns for runs, model requests, tool calls)
Tool preparation (filter or modify tool definitions per step)

The base class is AbstractCapability. You subclass it, override the methods you need, and pass instances to the agent:

from pydantic_ai import Agent
from pydantic_ai.capabilities import AbstractCapability

agent = Agent(
    "openai:gpt-4.1",
    capabilities=[MyCapability(), AnotherCapability()],
)

Multiple capabilities compose automatically. Before-hooks fire in order (cap1 then cap2), after-hooks fire reversed (cap2 then cap1), and wrap-hooks nest as middleware layers. This is not something we had to build -- the framework handles it.

What Are Hooks?

Hooks are the lifecycle interception points within capabilities. Pydantic AI provides hooks at four levels:

Run hooks -- before_run, wrap_run, after_run, on_run_error
Node hooks -- before_node_run, wrap_node_run, after_node_run, on_node_run_error
Model request hooks -- before_model_request, wrap_model_request, after_model_request, on_model_request_error
Tool hooks -- split into validation and execution phases, each with before/wrap/after/error variants

Plus prepare_tools for filtering tool visibility per step.

That's roughly 20 hook points across 4 lifecycle levels. Error hooks use a neat pattern: raise to propagate, return to recover. If your error handler raises the original exception, it propagates unchanged. Raise a different exception to transform the error. Return a result to suppress it entirely.

For simple use cases, the Hooks capability gives you decorator-based registration without subclassing:

from pydantic_ai.capabilities import Hooks

hooks = Hooks()

@hooks.on.before_model_request
async def log_request(ctx, request_context):
    print(f"Sending {len(request_context.messages)} messages")
    return request_context

agent = Agent("openai:gpt-4.1", capabilities=[hooks])

What Are Agent Specs?

Agent specs separate agent configuration from code entirely. You define your agent in YAML or JSON:

model: anthropic:claude-opus-4-6
instructions: You are a helpful assistant.
capabilities:
  - WebSearch
  - Thinking:
      effort: high

Then load it:

agent = Agent.from_file("agent.yaml")

Capabilities that implement get_serialization_name() and from_spec() are automatically available. This means your custom capabilities can be YAML-driven too.

How Our Libraries Migrated

pydantic-ai-middleware to pydantic-ai-shields

This was the most dramatic change. Our middleware library had grown to include MiddlewareAgent, MiddlewareChain, ParallelMiddleware, ConditionalMiddleware, PipelineSpec, config loaders, a compiler -- a whole parallel abstraction layer.

We deleted all of it.

The v0.3.0 release renamed the package to pydantic-ai-shields and rebuilt everything as capabilities.

Before (middleware era):

from pydantic_ai_middleware import MiddlewareAgent, CostTrackingMiddleware

middleware_agent = MiddlewareAgent(
    agent,
    middlewares=[CostTrackingMiddleware(budget_limit_usd=5.0)]
)
result = await middleware_agent.run("Hello")

After (capabilities era):

from pydantic_ai import Agent
from pydantic_ai_shields import CostTracking, PromptInjection, PiiDetector

agent = Agent(
    "openai:gpt-4.1",
    capabilities=[
        CostTracking(budget_usd=5.0),
        PromptInjection(sensitivity="high"),
        PiiDetector(detect=["email", "ssn", "credit_card"]),
    ],
)
result = await agent.run("Hello")

No wrapper agent. No middleware chain. The shields are just capabilities that hook into before_run, after_run, prepare_tools, and before_tool_execute as needed.

The new package ships 10 capabilities: CostTracking, ToolGuard, InputGuard, OutputGuard, AsyncGuardrail for infrastructure, plus PromptInjection, PiiDetector, SecretRedaction, BlockedKeywords, and NoRefusals as zero-dependency content shields.

pydantic-ai-subagents

The subagents library now exposes SubAgentCapability that bundles the subagent toolset and dynamic instructions:

from pydantic_ai import Agent
from subagents_pydantic_ai import SubAgentCapability, SubAgentConfig

agent = Agent(
    "openai:gpt-4.1",
    capabilities=[SubAgentCapability(
        subagents=[
            SubAgentConfig(
                name="researcher",
                description="Researches topics",
                instructions="You are a research assistant.",
            ),
        ],
    )],
)

The capability provides tools via get_toolset() and injects instructions via get_instructions(). It also supports agent spec serialization.

pydantic-ai-summarization

Four capabilities replace the old middleware-based context management:

SummarizationCapability -- triggers LLM summarization when thresholds are reached
SlidingWindowCapability -- zero-cost alternative that discards oldest messages
LimitWarnerCapability -- injects warnings when limits approach
ContextManagerCapability -- full package: token tracking, auto-compression, tool output truncation

from pydantic_ai import Agent
from pydantic_ai_summarization.capability import ContextManagerCapability

agent = Agent(
    "openai:gpt-4.1",
    capabilities=[ContextManagerCapability(max_tokens=100_000)],
)

pydantic-ai-backend

Our filesystem toolkit became ConsoleCapability -- bundling tools, instructions, and permission enforcement:

from pydantic_ai import Agent
from pydantic_ai_backends import ConsoleCapability
from pydantic_ai_backends.permissions import READONLY_RULESET

agent = Agent(
    "openai:gpt-4.1",
    capabilities=[ConsoleCapability(permissions=READONLY_RULESET)],
)

Key Takeaways

1. Delete your abstraction layers. We removed thousands of lines of middleware code. The framework does it better now.

2. Composition is free. Multiple capabilities stack without you writing any merge logic.

3. Agent specs change deployment. Define agent behavior in YAML, deploy by changing a config file.

4. The migration is mechanical. For each middleware hook, there's a direct capability equivalent.

5. Think in capabilities, not agents. The old pattern: build a specialized agent. The new pattern: build a capability, attach it to any agent.

DEV Community: Kacper Włodarczyk

Read a run's cost in AgenticOS

Open one run

Keep a comparison tied to the task

Include work performed before failure

Read the Spend view's coverage

Set the budget on the intended configuration

Look at the input behind the number

Keep a useful run record

Reverse-engineering a web page into a Claude Code skill

The prompt

What the agent read

What it built

How the skill works

My first review, and the apology

Nine examples in different styles

Doing this yourself

What this doesn't show

AgenticOS: self-hosted AI agents your whole team can improve

AgenticOS: self-hosted AI agents your whole team can improve

The problem it is built around

What is new this week, and what is not

Building an agent in the browser

Three controls an IT or security reviewer will ask about

The budget is checked before every model request

Sensitive tools wait for a person

Every run is recorded

For developers: code defines, configuration composes

Running it yourself

What it does not do yet

Try it

How We Built the AgenticOS Desktop Pets

Drawing a pet from separate parts

Deciding when to move

Making the cursor interaction feel intentional

Giving it a window of its own

Where to look in the code

24 Claude Code Skills to Fix Your AI Stack: Introducing production-stack-skills and content-skills

production-stack-skills: 10 Claude Code Skills for Production-Ready AI Code

content-skills: 14 Brand-First Skills That Kill AI Slop

One Install, Dual-CLI, Uninstall-Safe

Why Two Packs Shipped the Same Day

Key Takeaways

Frequently Asked Questions

What are Claude Code skills and how do I install them?

What's the difference between production-stack-skills and content-skills?

Do these skills work with Codex or only Claude Code?

How long does /production check take on a real repo?

When should I use a Claude Code skill instead of writing a full agent?

Get Started

Full Observability in AI Agents: What We Added to the pydantic-deepagents TUI

Full Observability in AI Agents: What We Added to the pydantic-deepagents TUI

The problem with invisible agents

What changed

Per-turn token usage

Cumulative cost in the header

Thinking streamed live → collapsed

Side panel on startup

All tool calls visible

Session saved on crash

Subagent logs: 20K chars (was 2K)

The full layout

Try it

Browser Automation + /improve: AI Agents That Browse the Web and Fix Themselves

Part 1: BrowserCapability — 9 Playwright Tools

Part 2: /improve — Session-Based Self-Improvement

This Week's Full Stack

curl | bash for AI Agents: One-Command Install for pydantic-deep

What install.sh does

Self-update

Startup notifications

Why uv?

Context Window Blindness: Why Your AI Agent Doesn't Know It's Running Out of Space

The Problem: Two Different Realities

The Fix: LimitWarnerCapability

BM25 History Search

EvictionCapability

Key Takeaways

StuckLoopDetection: How We Stopped an Agent Burning $12 on 47 Identical Calls

Why Prompting Isn't Enough

How long does `/production check` take on a real repo?