Skip to content

Lead the common.ai sandbox docs with when to use it and where each piece runs - #74297

Merged
kaxil merged 2 commits into
apache:mainfrom
astronomer:sandbox-docs-restructure
Oct 6, 2026
Merged

kaxil merged 2 commits into
apache:mainfrom
astronomer:sandbox-docs-restructure

Conversation

@kaxil

@kaxil kaxil commented Oct 5, 2026

Copy link
Copy Markdown
Member

The sandbox guide answered "should I use this, or KubernetesExecutor, KubernetesPodOperator or code mode?" in four separate sections well down the page, and carried two overlapping lists of limitations. This reorganizes sandbox/index.rst around that decision:

  • Opens with when to use something else: named operations (SQLToolset/HookToolset), code mode, KubernetesExecutor, KubernetesPodOperator.
  • New "Where each piece runs" section with a mermaid diagram: only the four sandbox tools move into the sandbox; the agent loop, the LLM credential and every other toolset stay where the task runs. It also shows sbx on the worker host versus Modal and OpenSandbox off it, and lists the provisioning credential for each backend.
  • One limitations list. "What it cannot do" and "Limitations" are merged under the existing sandbox-limitations label, each item linking to where it is explained. Claims that read as universal but are backend-specific are now scoped: attaching works on Modal only, running as root is documented for Modal, and sbx needs KVM only on Linux.
  • Real output in the quick start: the task-log summary and the Findings XCom from running the investigation example on Modal against a seeded Postgres warehouse, the exact error sbx raises for a bare SandboxSpec(), and the UsageLimitExceeded error that one of the two captured runs hit at pydantic-ai's default 50-request limit, with how to raise it.
  • Text from before Modal and OpenSandbox shipped is updated: OpenSandbox appears where backends and credentials are listed, and code mode is no longer contrasted only with sbx.

concepts.rst now links to the new placement section, and backends.rst gains a sandbox-backend-sbx label. No existing label was removed or renamed, so inbound links still resolve. The docs build and spellcheck pass.

Found while capturing the output, not changed here: the AgentOperator docstring says usage_limits=None "means no enforcement", but pydantic-ai's default request_limit=50 still applies, which is what the failed run hit. That is a one-line docstring fix for a separate PR.


  • Read the Pull Request Guidelines for more information. Note: commit author/co-author name and email in commits become permanently public when merged.
  • For fundamental code changes, an Airflow Improvement Proposal (AIP) is needed.
  • When adding dependency, check compliance with the ASF 3rd Party License Policy.
  • For significant user-facing changes create newsfragment: {pr_number}.significant.rst, in airflow-core/newsfragments. You can add this file in a follow-up commit after the PR is created so you know the PR number.

…ece runs

The sandbox page opened on the problem and only answered "should I use this,
or the executor, the pod operator or code mode?" across four sections further
down. It now opens with that answer, draws what moves into the sandbox and
what stays on the worker, merges the two overlapping limitation lists, and
shows the task log and XCom of a real run of the quick-start agent on Modal.
# Conflicts:
#	providers/common/ai/docs/sandbox/index.rst
@kaxil
kaxil merged commit 0609550 into apache:main Oct 6, 2026
71 checks passed
@kaxil
kaxil deleted the sandbox-docs-restructure branch October 6, 2026 12:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants