Why you shouldn't write your agents in code

The first version of Digitorn was a Python framework. Inheriting from Agent, registering tools as decorators, the whole pattern. We had a working coding agent in three weeks. We then spent six months unwinding that decision.

This is not a Python hate piece. Python is fine, and it still runs everywhere underneath Digitorn. The problem is more specific: writing an agent in code means writing the shape of the agent and its behaviour in the same language, in the same files, at the same level of abstraction. That sounds clever until you have to ship the thing, audit it, hand it to a non-engineer, or change a prompt at three in the morning. Then it stops being clever.

So we rewrote the runtime. An agent is now a declarative definition the runtime parses, validates, and executes, and you build that definition visually in Studio: you describe what you want, the builder assistant assembles the agent, and you refine it on a live canvas. The code is still there, underneath, doing the actual work. But the surface you touch is a workspace, not a codebase.

#Shape versus behaviour

An agent has a shape: which tools it has, which model it uses, what its system prompt is, when it's allowed to spawn workers. The shape is mostly static across runs. It doesn't loop, branch, or compute. It just describes structure.

An agent also has behaviour: the actual decisions the LLM makes, the tool calls it issues, the error paths it takes. The behaviour is dynamic. It can't be encoded statically because the whole point of an LLM is that the runtime decisions live in the weights, not in your code.

In a code-based framework, both live in the same file. You read a 200-line Agent class and try to figure out which lines describe the shape (so they're stable) and which lines hook into runtime callbacks (so they're load-bearing). Six months in, nobody on the team can tell you with confidence.

Building in Studio forces the split. The shape is what you assemble on the canvas, and it is all you have to reason about. The behaviour is decided by the LLM at run time. The plumbing in between lives in the runtime, not in your project. You look at the agent and you know exactly what it can and cannot do, because there is no other surface to check.

#The iteration problem, which is the whole pitch

If you've worked on agent prompts for any length of time, you know the loop: edit a system prompt, restart the agent, send the same test message, see what changed. Repeat thirty times an afternoon. The thing you actually care about is fast iteration. Everything else is overhead.

In a code framework, every edit means stopping the process, re-importing modules (if you trust your import graph, which you usually shouldn't), reloading credentials, re-establishing the session, then re-sending the test. On our internal benchmark we measured around eight seconds end to end on a warm machine. Cold start was closer to twenty.

In Studio, you change the agent while it is running. The runtime catches the change, swaps the affected pieces in place, and resumes the next turn with the new instructions. About 200 milliseconds in normal cases. The conversation history is preserved, which means you can tweak a prompt mid-task and watch the next decision land with the new instructions, without losing anything.

A 40× speed-up on the inner loop sounds like a vanity metric until you sit through a debugging session with both. The code loop punishes iteration. You start batching changes ("let me just try ten things at once and see what happens") which is the worst possible debugging strategy for a stochastic system. The live loop rewards iteration. You change one thing, you see the effect immediately, you keep your mental model intact.

#What you give up

This is the part the marketing pages skip.

The biggest thing you give up is unrestricted reach into the Python ecosystem. If you want to plug a custom retriever from llama-index, run a bespoke schema validator on a tool input, or use a niche embedding model that ships as a Python class, you can't just import it into your agent.

The second thing you give up is fluent low-level debugging. A stack trace through a def think(): you wrote yourself is more informative than a stack trace through a runtime that dispatched into modules on your behalf. The trade is roughly: you debug less often, but when you do, it's harder.

The third thing is the feel of being in control. Writing an agent in code feels like programming. Building one in Studio feels closer to directing. For some teams, especially research-heavy ones, that shift is a deal-breaker. We respect that. Not every problem wants the same answer.

#What you gain

The wins, in roughly the order we noticed them.

Reviews stop being theatre. A change to an agent is small, scannable, and has no flow control. Reviewers can actually tell what changed. Compare to a code diff that adds a decorator and reorders an import: nobody can tell at a glance whether that change is a no-op or a new behaviour.

Non-engineers can ship. Our product manager builds and edits agents directly in Studio. She catches issues we miss because she's actually reading the agent's outputs against her acceptance criteria. In the code version, she filed tickets. Now she ships changes herself.

Audit and compliance become trivial. "What does this agent have access to?" is answerable by opening the agent. It used to be a meeting.

Deploys are deterministic. An agent hashes to a stable bundle. Two copies of the same agent behave the same, run for run. The code version had install variability we couldn't fully eliminate (transitive deps, environment-dependent behaviour) until we shipped containers, at which point we'd already lost half the iteration speed.

Agents can travel. An agent on Digitorn is a small, self-contained bundle. Publish it to the Hub, a teammate installs it in one click, and they have your agent. No virtualenv. No "works on my machine".

Live iteration, again. This is the one we underestimated. It's not a productivity nice-to-have. It changes what kinds of debugging you do. You debug differently when the cycle is 200ms.

#The 1% case where you actually need code

The honest answer is that some agents are not config-shaped. A Slack bot that needs to reach into your CRM, look up the customer's tier, conditionally enable two tools, call a third tool's API directly with a derived auth token, and post the result with a custom formatter, that's not really a declarative problem. It's a code problem wearing a config hat.

We hit this wall ourselves. The fix is a layered escape hatch.

The first layer is the visual agent you build in Studio. The vast majority of agents stop here. We ran the numbers on the Hub: about 95% of published agents never need more, and most of the rest just want a one-line snippet, which the runtime already supports through hooks.

The second layer is hooks. You attach a small hook (a shell, JS, or Python snippet) to a moment in the agent's life: after a tool runs, at the start of a turn, on an error. The snippet runs in a sandbox, sees the tool result, and can transform or branch on it. This is enough to handle conditional logic, cross-tool state, custom validation, retry policies, and most of what people think they need a full codebase for.

The third layer is a custom module. You drop a small code file into the agent and the runtime loads it like any other module. From the agent's point of view it's just another tool. From your point of view you have full freedom for that one piece, while everything else stays visual and reviewable as a whole.

This structure is the answer to "does a no-code tool eventually paint you into a corner?". It does, briefly, on the way to a more useful place. The corner is the hooks layer, which is enough for almost everything. The 1% that breaks through keeps the visual agent for its shape and gains a small code file for the behaviour.

#A pragmatic recommendation

If you're at the start of an agent project and you're choosing between hand-writing the orchestration in Python or picking a workspace that builds agents for you, ask yourself two questions.

Is the shape of your agent going to change a lot, or is the behaviour going to change a lot? If it's the shape (new tools, new sub-agents, new model providers), a workspace wins by a huge margin because every change is a small edit. If it's the behaviour (new prompt strategies, dynamic dispatch, model-specific tweaks per turn), then you're going to spend most of your time in the inner loop, and fast live iteration matters more than language flexibility. The workspace still wins, just for a different reason.

How many people are going to read this? If the answer is "two engineers", raw code is fine. If the answer is "two engineers, a PM, a designer reviewing prompts, and an on-call in three months who's never seen this project", the workspace wins on review surface alone.

We're not religious about it. We use Python every day, in Digitorn's runtime, in our internal tooling, and inside the builder assistant that assembles agents for users. What we don't use it for is the agent's own definition. That's a job for a workspace a human can review in two minutes and the runtime can reload in 200 milliseconds.

#Try it for yourself

If this argument resonates, the fastest way to see it is to open Studio and edit an agent while it is running.

1. Open Studio in your browser, nothing to install.
2. Ask the builder assistant for a coding agent, or install one from the Hub.
3. Change one line of its system prompt while a conversation is open, and send the next message.

It uses the new prompt on the next turn, no restart. The first time you do this, it feels like cheating.

The full architecture lives in the docs. The companion piece on multi-agent dispatch is How to build a Claude Code clone, which works through a real coordinator-plus-explorer setup end to end.

If you push back on this take, we want to hear it. Digitorn is open source on GitHub. Open an issue, send a PR, or just write a thread about why we got it wrong. We've changed our minds about smaller things.