Programmatic Tool Calling (PTC) Configuration

Overview

Programmatic Tool Calling (PTC) lets a Digital Employee orchestrate tools through Python code executed in a sandboxed environment, rather than making individual API round-trips for each tool call.

When PTC is enabled, the agent gets access to an execute_ptc_code tool. The agent can write Python code that calls its registered tools, processes intermediate results, and returns only the final output to its context window.

Note: PTC is currently only supported for local runs (run(..., local=True)).

For the canonical guide, see the AIP PTC Guide.

Key Concepts

Why use PTC?

Benefit	Description
Context Window Protection	Intermediate results stay in the sandbox — only the final output is returned to the agent's context
Parallel Execution	The agent can call multiple tools concurrently within a single code block
Reduced Inference Overhead	One model pass writes the code; execution replaces multiple model-tool-model round-trips

How PTC works

1. The agent receives a task requiring multiple tool calls.

2. The agent writes a Python script and invokes execute_ptc_code.

3. The script runs inside an E2B sandbox with all registered tools available.

4. Only the final printed output is returned to the agent's context.

The PTC configuration object

PTC is configured via the PTC class from glaip_sdk.ptc:

from glaip_sdk.ptc import PTC

ptc_config = PTC(
    enabled=True,
    sandbox_timeout=120.0,
)

The instance is passed to DigitalEmployee via the ptc parameter. Tools registered on the Digital Employee are automatically made available in the sandbox — you do not need to configure them separately.

Prerequisites

• E2B_API_KEY must be set (get one at https://e2b.dev)

• OPENAI_API_KEY (or another supported model key) must be set

• glaip-sdk installed with [local] extras

Complete Example

The file examples/ptc/ptc_example.py demonstrates the PTC workflow.

Step 1: Import required components

from dotenv import load_dotenv
from glaip_sdk import Tool
from glaip_sdk.ptc import PTC

from digital_employee_core import (
    DigitalEmployee,
    DigitalEmployeeIdentity,
    DigitalEmployeeJob,
)
from digital_employee_core.connectors.tools.utility_tools import time_tool
from examples.ptc.tools.calculator_tool import CalculatorTool

load_dotenv()

Step 2: Create the Digital Employee identity

job = DigitalEmployeeJob(
    title="PTC Assistant",
    description="A helpful assistant with Programmatic Tool Calling enabled",
    instruction=(
        "You are a helpful assistant with Programmatic Tool Calling (PTC) enabled. "
        "When you need to orchestrate multiple tool calls or process data programmatically, "
        "you can write Python code using the execute_ptc_code tool.\n\n"
        "Use PTC when you need to:\n"
        "1. Call multiple tools and process their results\n"
        "2. Perform calculations or data transformations\n"
        "3. Keep intermediate results out of context\n\n"
        "Provide clear and helpful responses."
    ),
)

identity = DigitalEmployeeIdentity(
    name="PTC Assistant",
    email="[e-mail]",
    job=job,
)

Step 3: Configure PTC and attach tools

ptc_config = PTC(
    enabled=True,
    sandbox_timeout=120.0,  # Maximum execution time in seconds, optional
)

calculator_tool = Tool.from_langchain(CalculatorTool)

digital_employee = DigitalEmployee(
    identity=identity,
    tools=[time_tool, calculator_tool],
    ptc=ptc_config,
)

All tools passed to DigitalEmployee are automatically available inside the PTC sandbox.

Step 4: Run locally

message = "Calculate what time it will be in 3.5 hours. Directly show me the time without any intermediate output."

result = digital_employee.run(message=message, local=True)
print(result)

Note: Do not call deploy() for local PTC runs. Use run(..., local=True) directly.

What this example shows

• PTC is activated with PTC(enabled=True).

• Tools are registered on the Digital Employee — no separate sandbox configuration needed.

• The agent can orchestrate time_tool and calculator_tool in a single code block.

• Intermediate results (e.g., the raw time value) stay in the sandbox; only the final answer is returned to the model context.

Configuration Reference

Parameter	Type	Default	Description
enabled	bool	False	Activates PTC. Must be True to use PTC.
sandbox_timeout	float	120.0	Maximum execution time (seconds) for a sandbox run.
default_tool_timeout	float	60.0	Per-tool call timeout (seconds) inside the sandbox.
sandbox_template	str | None	"aip-agents-ptc-v1"	E2B sandbox template identifier.
prompt	dict | None	None	Prompt configuration for the execute_ptc_code tool description. Accepts {"mode": "...", "include_example": bool}.
ptc_packages	list[str] | None	None	Additional Python packages to install in the sandbox. None uses smart package selection; an explicit list is additive to the defaults.

Not supported: custom_tools — tools are always auto-derived from the DigitalEmployee.tools list.

Common Use Cases

Parallel tool calls

The agent can call multiple tools concurrently in one code block, without extra round-trips:

# Agent-generated code running inside the sandbox
result_a = time_tool()
result_b = calculator_tool(expression="365 * 24")
print(f"Time: {result_a}, Hours in a year: {result_b}")

Installing extra sandbox packages

ptc_config = PTC(
    enabled=True,
    ptc_packages=["pandas==2.2.0", "numpy"],
)

Extending the sandbox timeout for long-running tasks

ptc_config = PTC(
    enabled=True,
    sandbox_timeout=300.0,   # 5 minutes
    default_tool_timeout=90.0,
)

Best Practices

1. Mention execute_ptc_code in the job instruction

Explicitly tell the agent when and how to use PTC in the instruction field:

instruction=(
    "When orchestrating multiple tool calls, use execute_ptc_code to run them "
    "in a single Python block and return only the final result."
)

Without this hint, the agent may fall back to individual tool calls.

2. Keep sandbox_timeout proportional to task complexity

A short timeout is fine for quick calculations; increase it for tasks that involve many sequential tool calls or heavy data processing.

3. Use ptc_packages only when needed

If ptc_packages is None (the default), aip-agents selects packages automatically based on which tools are registered. Only set it explicitly when you need a package that is not auto-detected.

4. Do not call deploy() for local PTC runs

PTC is a local-only feature. Call run(..., local=True) directly — skip deploy().

5. Use a single DigitalEmployee instance per session

Constructing a new DigitalEmployee on every request means a cold sandbox start for each run. Reuse the instance across calls to amortize sandbox startup time.

Troubleshooting

E2B_API_KEY not set

Problem: The sandbox fails to start with an authentication error.

Solution: Obtain an API key from https://e2b.dev and add it to your .env file:

E2B_API_KEY=your_key_here

glaip-sdk[local] not installed

Problem: Import errors or missing sandbox dependencies.

Solution: Install the local extras:

poetry add "glaip-sdk[local]"

Agent not using execute_ptc_code

Problem: The agent calls tools individually instead of using PTC.

Solution: Add explicit PTC guidance to the job instruction. The model needs to be told when PTC is the preferred approach (see Best Practice 1 above).

Sandbox timeout exceeded

Problem: Execution is cut off mid-run with a timeout error.

Solution: Increase sandbox_timeout and, if tools are slow, default_tool_timeout:

ptc_config = PTC(
    enabled=True,
    sandbox_timeout=300.0,
    default_tool_timeout=90.0,
)

Tool not available inside the sandbox

Problem: The agent's PTC code raises an import or NameError for a registered tool.

Solution: Verify the tool is passed to DigitalEmployee(tools=[...]). Tools are auto-derived from this list — no additional sandbox configuration is required.