Introspection

Ask any agent, team, or workflow where its thinking and tools actually run

Every Agent, AgentTeam, and AgentFlow can tell you — in plain English — where its thinking and tools actually run.

Quick Start

1. Ask a plain agent

   Print the agent and it tells you where it runs.

   from praisonaiagents import Agent
   
   agent = Agent(name="builder", instructions="Write short answers")
   
   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. Ask a workflow with a shared sandbox

   A workflow with run_on= shows the shared container every step uses.

   from praisonaiagents import Agent, AgentFlow
   
   writer = Agent(name="writer", instructions="Write a file")
   reader = Agent(name="reader", instructions="Read the file back")
   
   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 team

   A team reports the same shared-sandbox detail across its agents.

   from praisonaiagents import Agent, AgentTeam, Task
   
   worker = Agent(name="worker", instructions="Do the task")
   
   team = AgentTeam(
       agents=[worker],
       tasks=[Task(description="Analyse the data", agent=worker)],
       run_on="e2b",
   )
   
   print(repr(team))
   # AgentTeam(name='...', agents=1, thinks_on='this machine',
   #           tools_run_on='an E2B cloud sandbox (shared)')

How It Works

Both repr() and where_does_it_run() read the same source of truth: run_on=, backend=, and sandbox=.

How the answer is picked

Each input maps to a plain-English place. These phrases come straight from the SDK — they are the exact words the object prints.

A run_on= on a team or workflow sets tools_run_on to a shared sandbox:

A sandbox= on an agent adds a code_runs_on place — where code you run yourself with execute_code() runs:

Public sandbox aliases resolve to the backend that actually runs: native becomes a locked-down process, and local becomes a separate process. An unknown provider name is printed back as-is.

Common Patterns

Print the location at the top of your script before running untrusted code.

from praisonaiagents import Agent

agent = Agent(name="runner", instructions="Run the task", sandbox=True)
print(agent.where_does_it_run())
# Thinking (the AI model calls) happens on this machine.
# Tools run on this machine.
# Code you run yourself with execute_code() runs on a separate process on this machine.
# 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.
# Nothing is isolated: tools you pass run in this program, with your permissions.

Confirm a shared sandbox actually shares state. For a workflow with run_on=, the explanation ends with a line about visibility between steps.

from praisonaiagents import Agent, AgentFlow

flow = AgentFlow(run_on="docker", steps=[Agent(name="a", instructions="x")])
print(flow.where_does_it_run())
# ...
# Every step shares that same sandbox, so a file written by one step is visible to the next.

Read the machine-readable places directly when you need data instead of prose.

from praisonaiagents import Agent
from praisonaiagents.agent.execution_location import describe

agent = Agent(name="builder", instructions="x")
print(describe(agent))
# {'thinks_on': 'this machine', 'tools_run_on': 'this machine'}

Best Practices

Related