Where Your Agent Runs

Ask any agent, team, or workflow where its thinking and its tools actually execute — from the REPL, no docs required

Every Agent, AgentTeam, and AgentFlow can tell you — from repr() alone or via where_does_it_run() — where the model runs and where the tools run.

from praisonaiagents import Agent

agent = Agent(name="builder")
print(agent.where_does_it_run())
# Thinking (the AI model calls) happens on this machine.
# Tools run on this machine.
# Nothing is isolated: tools you pass run in this program, with your permissions.

Quick Start

1. Ask an agent where it runs

   A plain agent thinks and runs its tools on this machine:

   from praisonaiagents import Agent
   
   agent = Agent(name="builder")
   print(repr(agent))
   # Agent(name='builder', thinks_on='this machine', tools_run_on='this machine')
   
   print(agent.where_does_it_run())
   # Thinking (the AI model calls) happens on this machine.
   # Tools run on this machine.
   # Nothing is isolated: tools you pass run in this program, with your permissions.

2. A workflow with a shared sandbox

   Set run_on="docker" and every step shares one sandbox:

   from praisonaiagents import Agent, AgentFlow
   
   writer = Agent(name="writer")
   reader = Agent(name="reader")
   
   flow = AgentFlow(run_on="docker", steps=[writer, reader])
   print(repr(flow))
   # AgentFlow(name='AgentFlow', steps=2,
   #           thinks_on='this machine',
   #           tools_run_on='a Docker container (shared)')
   
   print(flow.where_does_it_run())
   # Thinking (the AI model calls) happens on this machine.
   # Tools run on a Docker container (shared).
   # Every step shares that same sandbox, so a file written by one step is visible to the next.

3. Ask a hosted agent where it runs

   A hosted backend moves the whole turn to the provider’s cloud:

   from praisonaiagents import Agent
   from praisonai import HostedAgent
   
   agent = Agent(name="teacher", backend=HostedAgent(provider="anthropic"))
   print(agent.where_does_it_run())
   # Thinking (the AI model calls) happens on Anthropic's cloud.
   # Tools run on Anthropic's cloud.

4. Read the answer as a dictionary

   from praisonaiagents import Agent, AgentFlow
   from praisonaiagents.agent.execution_location import describe
   
   describe(Agent(name="builder"))
   # {'thinks_on': 'this machine', 'tools_run_on': 'this machine'}
   
   describe(AgentFlow(run_on="docker", steps=[Agent(name="w")]), shared=True)
   # {'thinks_on': 'this machine', 'tools_run_on': 'a Docker container (shared)'}

Three topologies at a glance

tools_run_on= moves the tools out but keeps the model call local. A whole-loop backend moves both off this machine — hosted on a vendor’s cloud, or self-hosted in a container you own. The repr names both places, so you can tell them apart at a glance.

How the object knows

repr() asks a single shared helper — describe() — which reads three attributes off the object and turns provider names into plain phrases. where_does_it_run() passes the same result through explain() to produce sentences.

describe() never raises — if a property throws, thinks_on falls back to this machine so that describing where something runs can never break the thing it describes.

_backend_places() now asks the backend via provider_name rather than name-matching the class. A self-hosted backend (like run_on="docker") used to be misreported as thinking on this machine because its class name did not contain Hosted or Anthropic; asking it what it is fixes that — the whole-loop container is now reported as a Docker container for both places.

_backend_places() reads a backend’s _compute / compute with via="compute", because that attribute is a compute-registry provider — otherwise a LocalCompute here would borrow the subprocess backend’s stronger words. See The two flavors of local.

What each place name means

Provider names map to phrases a non-developer can read. These are the exact strings the object returns.

Public aliases resolve to the backend that actually runs — the alias name never appears in the output:

An unknown provider falls back to its own name: say_place("some-new-cloud") returns "some-new-cloud".

The two flavors of local

local means two different backends depending on which parameter carried it, so the phrase depends on where the word came from.

• run_in="local" → SandboxManager collapses it to the subprocess backend (scrubbed environment, blocked commands and paths) → "a separate process on this machine"
• tools_run_on="local" → the wrapper’s LocalCompute: a plain shell in the current directory, full environment inherited, no security policy → "a plain shell on this machine (no policy applied)"

say_place(name, *, via="sandbox") normalises the provider object first, then reads the compute-only word table. Pass via="compute" for the tools_run_on= reading:

from praisonaiagents.agent.execution_location import say_place

say_place("local")                 # "a separate process on this machine"
say_place("local", via="compute")  # "a plain shell on this machine (no policy applied)"

The same rule applies when a managed backend holds a LocalCompute provider object (provider_name="local"). A backend’s _compute / compute is a compute-registry provider, so _backend_places() reads it with via="compute" — otherwise a LocalCompute here would borrow the subprocess backend’s stronger words.

# A managed backend that carries a LocalCompute provider object
# (provider_name="local") is a COMPUTE-registry provider, so it is
# read with the compute vocabulary — never described in the subprocess
# backend's stronger words.
#
# Before PR #4070: tools_run_on='a separate process on this machine'  (WRONG — overstated)
# After  PR #4070: tools_run_on='a plain shell on this machine (no policy applied)'  (CORRECT)

The subprocess warning

A sandbox=True agent runs tools in a separate process — but a separate process is not a security boundary.

from praisonaiagents import Agent

agent = Agent(name="A", sandbox=True)
print(agent.where_does_it_run())
# Thinking (the AI model calls) happens on this machine.
# Tools run on a separate process on this machine.
# Nothing is isolated: tools you pass run in this program, with your permissions.
# Note: a separate process is not a security boundary -- it can still reach the
# network and read your files. Use docker or a cloud provider for untrusted code.

The network stays reachable and ~/.ssh stays readable under a subprocess. A real container (run_on="docker") is a real boundary, so it does not trigger this note. See Sandbox for the same warning in depth.

Configuration Options

This page adds no new knobs — where things run comes from sandbox=, run_on=, and backend=, documented on the sandbox pages below. The only new vocabulary is the field names the object returns:

The field is thinks_on / tools_run_on, never loop — that word already means the workflow loop() primitive, asyncio’s event loop, and agent-loop jargon, so it was deliberately rejected.

Public API surface

Three ways to read the answer, from a quick glance to structured data:

The helper functions live under praisonaiagents.agent.execution_location:

from praisonaiagents.agent.execution_location import describe, explain, say_place

say_place("docker")
# 'a Docker container'

Common Patterns

Check where things run before a paid run, log it at startup, or assert it in a test.

from praisonaiagents import Agent, AgentFlow
import logging

logger = logging.getLogger(__name__)

# 1. Verify what a config will do before you run it.
flow = AgentFlow(run_on="docker", steps=[Agent(name="w")])
print(repr(flow))  # confirm 'a Docker container (shared)' before starting

# 2. Log where things run at startup — support tickets get 10x easier to triage.
agent = Agent(name="builder")
logger.info(agent.where_does_it_run())

# 3. Assert where things run in a test.
from praisonaiagents.agent.execution_location import say_place
assert say_place("docker") == "a Docker container"

Compare local, shared-sandbox, and hosted from one script:

from praisonaiagents import Agent, AgentFlow
from praisonai import HostedAgent

local = Agent(name="local")
shared = AgentFlow(run_on="docker", steps=[])
hosted = Agent(name="hosted", backend=HostedAgent(provider="anthropic"))

for obj in (local, shared, hosted):
    print(obj.where_does_it_run())
    print("---")

Best Practices

Related