The Agent's Working World: Tools, Skills, Sandboxes, and Artifacts
DeerFlow’s lead agent does not receive one flat menu called “the tools.” This chapter examines how its capabilities are supplied, narrowed, executed, and turned into deliverables, so the reader can choose an integration by its ownership and trust model rather than by its name. The key distinction is between what an agent can discover, what it is authorized to invoke, where the action runs, and what survives as evidence afterward.
Capability is a supply chain, not a menu
A tool is an action interface that the model can call. In DeerFlow, the action may come from several very different places. Built-in tools belong to the harness itself: they cover operations such as presenting files, asking for clarification, or handling images. Configured and community tools are selected by the operator and can connect the agent to web search, page fetching, knowledge retrieval, or other providers. MCP servers expose additional tools through a protocol. Python extensions can contribute to the runtime more deeply, adding middleware, services, observers, or authenticated routes. These sources can all appear in one lead-agent toolset, but they do not have the same lifecycle or trust boundary.
That difference becomes clearer if the capability paths are viewed as layers. A built-in tool is part of the host’s known execution contract. A configured provider is an adapter chosen in configuration, with its own network and availability assumptions. An MCP tool is produced by another server and may run in a separate process or remote service. A Python extension is imported into the Gateway and can participate in the host process. Treating those four things as interchangeable hides the question of who can change the code, who controls the data, and what happens when the provider fails.
The lead-agent factory assembles these sources before the model is bound to them. It combines configured groups with the model’s capabilities, user identity, skill settings, sub-agent availability, and authorization. When authorization is enabled, denied tools are removed before the model sees their schemas, and the runtime checks again before execution. This two-stage arrangement matters because a prompt instruction is not a reliable substitute for capability filtering. If the model cannot see a tool, it is less likely to select it; if a tool is still reached through a deferred or stateful path, the execution gate remains the final decision.
A skill sits beside the tool layer rather than replacing it. A skill is a package built around a SKILL.md file: it describes a workflow, gives the model domain-specific instructions, and can declare which tools are appropriate. The package may be enabled without loading its entire body into every request. With deferred skill discovery, the system can expose a compact index, let the model describe a selected skill, and load the full instructions only when they are relevant. Explicit slash activation provides another path: a user can select a skill for the current turn instead of relying entirely on the model to guess relevance.
The distinction between discovery and activation protects two scarce resources at once. Prompt space is limited, especially when many skills are installed, and tool authority should not expand merely because metadata happens to be visible. DeerFlow applies a skill’s allowed-tools policy after explicit activation or after the runtime has captured a real skill-file load. The active policy filters model-visible business tools and blocks unauthorized execution. Discovery helpers such as describe_skill and tool_search remain available as framework infrastructure, but promoting a deferred tool does not override the active skill policy.
Skill state is also user-scoped. Public, custom, legacy, and managed integration skills can have different enabled states for different users. When a custom agent has an explicit allowlist, DeerFlow materializes a corresponding thread view rather than allowing the sandbox to read the entire canonical skill tree. The projection copies files into an isolated view, rejects escaping symlinks, and can be rebuilt when policy changes. That copy costs storage and I/O, but it prevents a sandbox write from mutating the canonical skill inode. It is a concrete example of a design choosing isolation over the cheapest possible mount.
The package is reviewed before it becomes an active capability. DeerFlow’s deterministic SkillScan checks archives and agent-managed skill writes before the LLM-based scanner, blocks high-confidence findings, and applies safe extraction limits. Yet the project describes the policy as defense in depth, not as a complete security boundary. A mounted skill root remains an operator-controlled trust surface, and behavioral allowed-tools rules cannot prevent every alternate way of reading or executing content. The stronger boundary is the sandbox in which the skill eventually runs.
MCP extends the supply chain beyond the DeerFlow process. A server can use stdio, SSE, or HTTP transport. The MCP manager can initialize tools lazily, cache them, prefix their names to prevent collisions, and defer their schemas until the model asks to promote them. Routing hints can prefer a particular server or tool without turning that preference into a hard prohibition. This is useful when a deployment has many integrations: the lead agent need not carry every remote schema in every model request, and the operator can still keep the catalog under configuration control.
Credentials make MCP’s ownership question unavoidable. DeerFlow supports OAuth for HTTP/SSE servers, user-scoped credentials, and request-scoped secrets. Those values are resolved through runtime context and interceptors rather than being placed in a prompt or ordinary run metadata. Missing credentials fail closed by default, because silently falling back to a discovery credential could make one user’s request execute under another authority. Headers are checked before transport use so malformed values do not leak into model-visible error text. The result is not perfect trust in the remote service; it is a narrower and more explicit path for authority to cross into it.
Long-running MCP work is treated differently from an ordinary tool call. The model sees a submit operation and a DeerFlow-local task identity, while a durable service persists the remote handle, polls status, handles cancellation, and sends a bounded projection back to the thread. That separation keeps a slow remote operation from occupying the model’s immediate tool loop indefinitely. It also means the remote server’s status protocol, retry behavior, and idempotency remain meaningful dependencies rather than details hidden by the word “MCP.”
Python extensions are the most powerful capability seam and therefore the most restricted one. Their startup-only plugins configuration is kept out of the API-writable MCP and skill settings because importing an extension means executing Python in the Gateway’s privilege context. The extension manager can validate sources, snapshot local directories, manage dependency locks, and roll back a failed transaction. None of those safeguards sandbox the extension’s runtime code. A useful rule follows: declarative capability configuration may be exposed to an authenticated management surface; host-code import remains an operator decision.
The diagram’s arrows represent different kinds of ownership. A skill does not become a tool; it can shape how tools are discovered and used. An MCP server does not become part of the model; it supplies an action interface through a transport. An extension can alter the host runtime rather than merely add a callable. Policy touches the capability surface before and during execution, while the sandbox contains—or fails to contain—the resulting side effect.
The sandbox turns capability into side effect
The most important tool boundary is physical. DeerFlow gives a thread a virtual filesystem view for uploads, workspace files, and outputs. The lead agent sees stable paths, while the selected provider maps those paths to local directories, a Docker-based container, a provisioner-managed pod, or another supported execution environment. This common virtual interface means a file-reading operation can remain conceptually the same while its security meaning changes with the provider.
A local sandbox is convenient for development because the files are available on the host and no remote container must be created. It is not, however, a secure boundary for shell access. DeerFlow disables host Bash by default and warns that a host subprocess can address canonical paths without respecting the provider’s virtual mappings. Re-enabling host Bash is appropriate only for a fully trusted local workflow. The choice is not a minor performance setting: it determines whether a model-directed command is contained by a sandbox or is effectively a host operation.
Container and remote providers supply a stronger boundary, but they introduce their own conditions. A Docker/AIO sandbox can isolate commands and provide network modes such as open, isolated, or allowlist. Remote providers can require asynchronous creation, readiness checks, file synchronization, capacity reservations, warm-pool reuse, and cross-instance ownership leases. A warm sandbox reduces startup latency, but it must not be mistaken for a free cache: the runtime has to know which user and thread may reclaim it, whether the provider is still healthy, and which process may destroy it. If shared ownership state is unavailable, safe acquisition and reaping can fail closed rather than risk one worker destroying another worker’s live environment.
The virtual filesystem has three distinct categories of data. Uploads are user inputs. The workspace is where the agent can place intermediate material. Outputs are where final deliverables are expected. This separation gives the runtime a way to reason about side effects without relying on a model-generated filename. A report assembled from fetched evidence can be drafted in the workspace, then written to the output area when it is ready to present. Temporary files or process feedback can remain internal instead of being advertised as final work.
File tools make the boundary actionable. The agent can list and search files, read selected ranges, write content, replace text, and inspect images when the model supports vision. The tools translate virtual paths, enforce containment, and attach their results to the current thread. A read-before-write gate can require a fresh content mark before an existing file is changed, reducing the chance that a stale model view overwrites a concurrent edit. Output limits can externalize oversized tool results into internal process-feedback files while leaving the model a compact synopsis and a reference for targeted reading.
The resulting workspace is not merely scratch space. DeerFlow snapshots the thread-owned workspace and output directories before and after a run, records created or modified files, and shows a compact change summary in the user interface. Uploads are excluded because they are inputs rather than agent-generated changes. Large, binary, or sensitive-looking files can be represented as metadata rather than copied into a diff. This turns “the agent changed something” into a narrower, inspectable statement about which part of the thread filesystem changed during the run.
Artifact presentation is the final step in that chain. If a run produces or modifies an output file, DeerFlow can require the agent to present a matching path through its artifact mechanism. Presenting an unrelated pre-existing file does not satisfy that requirement. The terminal delivery receipt records the produced and presented paths and can downgrade a nominally successful run when no matching delivery exists. That check does not judge whether the report is accurate or whether the code is good; it checks a more modest but valuable fact: the output made by this run was actually connected to the user-visible result.
This is why the same write_file or bash name cannot be evaluated in isolation. With host Bash enabled, the command may have access to the host’s canonical filesystem. In an isolated container, it runs inside a separate environment whose mounts and network policy determine its reach. With a remote provider, file synchronization and lease expiry add failure modes of their own. The tool interface is shared, but the trust boundary belongs to the provider configuration and its lifecycle.
A research report illustrates the whole working world. Search and fetch tools gather material. A skill can specify how to compare sources and structure the report. The workspace holds notes and intermediate tables. The sandbox gives the agent a place to transform those inputs. The output area holds the finished document. Events and a delivery receipt let the user inspect what happened. If the task uses a remote MCP search provider or a custom skill, their credentials and instructions cross additional boundaries; if the task runs on a local host, the operator accepts a different security posture. The report is therefore not just an answer generated at the end. It is the visible result of a chain of capability choices.
The practical lesson is to select the narrowest capability path that meets the objective. Use a skill when the challenge is repeatable workflow knowledge. Use a configured tool when a known provider is sufficient. Use MCP when the capability belongs to an external service or process and its authority can be scoped. Use a Python extension only when host-level integration is necessary and the source is trusted. Choose the sandbox according to the consequences of a wrong or malicious action, not merely according to startup speed. Then treat artifact delivery and execution evidence as part of the result, not as optional interface polish.
These choices give DeerFlow a working world, but they also create a question about composition. A capability may be available without being authorized; an action may run without being safely isolated; a file may exist without being delivered; and a tool receipt may show execution without proving correctness. The next checkpoint brings those dimensions together before considering when DeerFlow should split work across sub-agents or defer it to a durable background task.