Moving Agent Orchestration from Python to Markdown Files

The Shift to File-Based Agent Orchestration

Philipp Schmid demonstrates that as LLM reasoning capabilities improve, the need for custom Python-based agent harnesses decreases. The evolution of a GitHub pull request review agent shows a transition from manual Python loops with explicit JSON schema tool definitions to a remote agent architecture. In this final iteration, the agent operates within a hosted, isolated Linux sandbox that manages session state, context compaction, and tool routing server-side. This removes the need for developers to write boilerplate code for function calling, error handling, or state management.

Implementing Remote Agents

Instead of defining specific Python functions and schemas, developers provide the agent with general-purpose tools and environment configurations. The agent uses its reasoning capabilities to decide which tools to invoke to achieve a goal. Key implementation details include:

• Environment Configuration: Use a sources parameter to inject repositories, GCS buckets, or inline files into the sandbox.
• Credential Proxying: Configure a network proxy that injects credentials (e.g., GitHub tokens) into outbound requests from the sandbox, ensuring the agent never directly accesses the raw tokens.
• Instruction Files: Define agent behavior, rules, and capabilities in AGENTS.md and skills.md files rather than hard-coded Python logic.
• General-Purpose Tooling: Provide access to standard CLI tools like the GitHub CLI (gh) and bash, allowing the model to explore and execute tasks dynamically rather than relying on pre-defined function signatures.

The Heuristic for Overengineering

Schmid argues that if an agent harness becomes more complex as the underlying model improves, the system is likely overengineered. He highlights that teams like Cursor have successfully replaced thousands of lines of orchestration code with a few hundred lines of markdown instructions. The primary focus for developers should shift toward domain-specific instructions, defining clear evaluation criteria, and verifying outcomes, rather than micromanaging the execution path of the model.