Agent execution modes

Most agents need tools — file edits, database queries, deploys, browser actions, anything with a side effect. Nimblesite gives you two ways to run those tools, and you pick per agent config:

Both modes share the same chat endpoint, the same memory, the same multi-tenancy, and the same model picker. The only thing that changes is who actually executes the tool call.

You set the mode on the agent config:

{
  "agent_type": "client-side"
}

{
  "agent_type": "sandboxed"
}

Internally we use disembodied for client-side and sandbox-embodied for sandboxed — those names appear in the API and SDKs. The concepts are what this page documents.

Client-side tools (default)

This is the standard tool-use pattern from raw LLM APIs: the agent decides what to call, your app runs it, you post the result back. Same shape as OpenAI function calling, Anthropic tool use, or PydanticAI's native tool loop — just persisted and multi-tenant-safe out of the box.

sequenceDiagram
    participant Client as Your app
    participant API as Nimblesite
    participant LLM
    Client->>API: POST /chat { message }
    API->>LLM: model + history + tool defs
    LLM-->>API: tool_call(write_file, {...})
    API-->>Client: { tool_calls: [...] }
    Note over Client: Run the tool in your trust boundary
    Client->>API: POST /chat { tool_results }
    API->>LLM: history + tool return
    LLM-->>API: final text
    API-->>Client: { response: "Done." }

Choose this when any of the following are true:

• Tools touch data or APIs you don't want anyone else holding credentials for.
• Your tools already exist as functions in your backend.
• You want auditors to see that no third-party platform ever executed code against your systems.
• You want to ship the agent into a mobile app or CLI where the tool runs locally on the user's device.

You write a tool_calls handler in your app — usually a match statement or a dispatch dict that maps tool names to your existing functions. There is no Nimblesite SDK to import for this; the contract is plain HTTP.

Full protocol detail: Tools.

Sandboxed agents

The agent runs against a managed sandbox Nimblesite provisions for the config: a long-running container with a filesystem, network, shell, and a tool API. Tool calls never leave the platform — the agent loop dispatches them straight to the sandbox and feeds the result back to the model in a single chat turn. The user just sees the final text reply.

This is the same pattern as OpenAI Code Interpreter, Anthropic's computer-use sandbox, or E2B — but wired into the same persistent-conversation, multi-tenant API as everything else in Nimblesite.

sequenceDiagram
    participant Client as Your app
    participant API as Nimblesite
    participant Sandbox as Managed sandbox
    participant LLM
    Client->>API: POST /chat { message }
    loop until model emits text
        API->>LLM: model + history + tool defs
        LLM-->>API: tool_call(write_file, {...})
        API->>Sandbox: POST /tools/write_file
        Sandbox-->>API: result
        API->>LLM: history + tool return
    end
    LLM-->>API: final text
    API-->>Client: { response: "Done." }

Choose this when any of the following are true:

• The agent needs to edit files, run a build, or use shell commands.
• You want a durable per-agent workspace that persists between conversations.
• You want users to be able to SSH or open a web terminal into the agent's environment for inspection or manual edits.
• You're building a coding / dev / website-edit agent.

How the sandbox works

• One sandbox per agent config, not per conversation. Switching conversations or starting new ones reuses the same workspace.
• Lazy-provisioned. The sandbox boots on the first tool call and idles after a few minutes of inactivity. The next chat resumes it automatically — your code never sees the cold start.
• Conversations stay continuous. Pause, resume, replace the sandbox — the chat history is unaffected.
• Out-of-band access. Your users get shell / file / network access to the sandbox independent of the chat API. The chat agent and the human user share the same workspace.
• Replaceable. POST /api/v1/configs/{config_id}/workspace/replace swaps the underlying container while keeping every conversation intact.
• Bring your own image if the default doesn't fit. The default reference image runs Node, Python, Git, and a pluggable tool API; consumers can ship their own image as long as it speaks the container protocol.

Configuring a sandboxed agent

{
  "name": "Site Editor",
  "agent_type": "sandboxed",
  "workspace_image": "nap-workspace:latest",
  "workspace_secrets": {
    "GITHUB_TOKEN": "...",
    "DEPLOY_KEY": "..."
  },
  "system_prompt": "You edit and deploy a static site. Use the file tools and pipeline tools.",
  "model_config": {"provider": "anthropic", "model": "claude-sonnet-4-6"},
  "tools_config": [
    "read_file",
    "write_file",
    "replace_in_file",
    "list_files",
    "build_site",
    "git_commit",
    "git_push"
  ]
}

workspace_secrets are injected into the sandbox at boot. They never enter the agent loop's memory and never appear in chat history.

Differences at the chat-API layer

The chat endpoint is the same in both modes, but the shape of the response differs:

If you build a chat UI on top of Nimblesite, sandboxed agents are simpler to render — every chat turn ends with text. Client-side agents need your UI to handle the intermediate tool_calls turn (run the tool, show progress, post the result back).

Mixing modes

Each agent config picks one mode. A single tenant can run any mix — a sandboxed coding agent and a client-side support-desk agent under the same API key, billed and scoped together. The mode is per config, not per tenant.

What about other patterns?

If you've used other agent platforms, here's where they map:

• OpenAI Function Calling, Anthropic Tool Use, Gemini function calling — same shape as our client-side mode, but stateful and multi-tenant.
• OpenAI Code Interpreter, Anthropic computer-use, E2B sandboxes — same idea as our sandboxed mode, with the agent loop, memory, and model selection wired in.
• LangChain / LangGraph agents — those are frameworks (the loop driver). Nimblesite is the platform (memory, tenancy, transport). You can run a sandboxed agent that uses any of those frameworks under the hood; future config field base_agent will let you pick.

Next

• Tools — full client-side tool protocol.
• Agent configs — every field on a config.
• Quickstart — ship a working agent in two HTTP calls.