Add openai-agents-submilli, the OpenAI Agents SDK integration

.github/workflows/ci.yml

@@ -32,6 +32,7 @@ jobs:
         package:
           - { dir: submilli, module: submilli }
           - { dir: langchain-submilli, module: langchain_submilli }
+          - { dir: openai-agents-submilli, module: openai_agents_submilli }
     defaults:
       run:
         working-directory: packages/${{ matrix.package.dir }}
@@ -48,7 +49,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        package: [submilli, langchain-submilli]
+        package: [submilli, langchain-submilli, openai-agents-submilli]
         python: ["3.11", "3.12", "3.13", "3.14"]
         exclude:
           # langchain-submilli is tested on the Pythons its dependencies support.
@@ -72,6 +73,7 @@ jobs:
           - { package: submilli, tests: tests/integration }
           # Tests that need the research Blueprint's Packages are skipped here.
           - { package: langchain-submilli, tests: tests/integration_tests }
+          - { package: openai-agents-submilli, tests: tests/integration_tests }
     steps:
       - uses: actions/checkout@v7
       - uses: astral-sh/setup-uv@v10.3.0
@@ -132,6 +134,9 @@ jobs:
           uv run --isolated --no-project --with dist/submilli-*.whl python -c "import submilli"
           uv run --isolated --no-project --with dist/submilli-*.whl --with dist/langchain_submilli-*.whl \
             python -c "import langchain_submilli"
-      - name: langchain-submilli depends on submilli from PyPI, not the workspace
+          uv run --isolated --no-project --with dist/submilli-*.whl --with dist/openai_agents_submilli-*.whl \
+            python -c "import openai_agents_submilli"
+      - name: The integrations depend on submilli from PyPI, not the workspace
         run: |
           unzip -p dist/langchain_submilli-*.whl '*/METADATA' | grep -x 'Requires-Dist: submilli<0.2,>=0.1.2'
+          unzip -p dist/openai_agents_submilli-*.whl '*/METADATA' | grep -x 'Requires-Dist: submilli<0.2,>=0.1.2'

.github/workflows/release.yml

@@ -1,13 +1,13 @@
 name: Release
 
 # Each package is released on its own tag: `submilli-v0.1.0` publishes the SDK,
-# `langchain-submilli-v0.1.0` the integration. Publishing goes through PyPI
+# `langchain-submilli-v0.1.0` and `openai-agents-submilli-v0.1.0` the integrations. Publishing goes through PyPI
 # trusted publishing: register this workflow and the `pypi` environment for
-# both projects on PyPI first. Release `submilli` before the first
-# `langchain-submilli` that needs it.
+# each project on PyPI first. Release `submilli` before the first integration
+# release that needs it.
 on:
   push:
-    tags: ["submilli-v*", "langchain-submilli-v*"]
+    tags: ["submilli-v*", "langchain-submilli-v*", "openai-agents-submilli-v*"]
 
 permissions:
   contents: read

README.md

@@ -11,11 +11,13 @@ execute TypeScript code in Submilli's runtime.
 [Docs](https://submilli.ai/docs/) ·
 [Connect Deep Agents](https://submilli.ai/docs/tutorials/connect-deepagents/) ·
 [Package reference](packages/langchain-submilli#readme) ·
+[OpenAI Agents](packages/openai-agents-submilli#readme) ·
 [Submilli runtime](https://github.com/submilli/submilli-runtime) ·
 [Discord](https://discord.gg/VphpukeGGj) ·
 [Website](https://submilli.ai)
 
 [![PyPI: langchain-submilli](https://img.shields.io/pypi/v/langchain-submilli?label=langchain-submilli)](https://pypi.org/project/langchain-submilli/)
+[![PyPI: openai-agents-submilli](https://img.shields.io/pypi/v/openai-agents-submilli?label=openai-agents-submilli)](https://pypi.org/project/openai-agents-submilli/)
 [![PyPI: submilli](https://img.shields.io/pypi/v/submilli?label=submilli)](https://pypi.org/project/submilli/)
 [![CI](https://github.com/submilli/submilli-python/actions/workflows/ci.yml/badge.svg)](https://github.com/submilli/submilli-python/actions/workflows/ci.yml)
 [![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
@@ -67,8 +69,11 @@ pip install "langchain-submilli[deepagents]"
 ```
 
 For a different LangChain v1 agent, install `langchain-submilli` without the `deepagents`
-extra. To use submilli-server directly from Python, install the
-[`submilli` SDK](packages/submilli/README.md) instead.
+extra. For the OpenAI Agents SDK, install
+[`openai-agents-submilli`](packages/openai-agents-submilli#readme) and follow
+[Connect OpenAI Agents](https://submilli.ai/docs/tutorials/connect-openai-agents/). To use
+submilli-server directly from Python, install the [`submilli` SDK](packages/submilli/README.md)
+instead.
 
 Follow [Connect Deep Agents](https://submilli.ai/docs/tutorials/connect-deepagents/) for the
 complete setup, including the server, Blueprint, model provider, agent, and session cleanup.
@@ -118,16 +123,17 @@ For production, deploy with
 ## Status
 
 Submilli is young and moving quickly. Breaking changes are recorded in the
-[`langchain-submilli` changelog](packages/langchain-submilli/CHANGELOG.md) and
-[`submilli` changelog](packages/submilli/CHANGELOG.md). To talk with us, email
+[`langchain-submilli`](packages/langchain-submilli/CHANGELOG.md),
+[`openai-agents-submilli`](packages/openai-agents-submilli/CHANGELOG.md), and
+[`submilli`](packages/submilli/CHANGELOG.md) changelogs. To talk with us, email
 [hello@submilli.ai](mailto:hello@submilli.ai) or join
 [Discord](https://discord.gg/VphpukeGGj).
 
 ## Development
 
 This repository is a [uv workspace](https://docs.astral.sh/uv/concepts/projects/workspaces/).
-In the workspace, `langchain-submilli` uses `packages/submilli` directly. When published, it
-depends on `submilli` from PyPI.
+In the workspace, `langchain-submilli` and `openai-agents-submilli` use `packages/submilli`
+directly. When published, they depend on `submilli` from PyPI.
 
 ```sh
 uv sync --all-packages --all-groups
@@ -138,11 +144,12 @@ uv run ruff format .
 Run type checks and tests inside each package:
 
 ```sh
-cd packages/submilli            # or packages/langchain-submilli
+cd packages/submilli            # or packages/langchain-submilli, packages/openai-agents-submilli
 uv run mypy
 uv run pyright
 uv run pyright --verifytypes submilli --ignoreexternal             # packages/submilli
 uv run pyright --verifytypes langchain_submilli --ignoreexternal   # packages/langchain-submilli
+uv run pyright --verifytypes openai_agents_submilli --ignoreexternal   # packages/openai-agents-submilli
 uv run pytest
 ```
 
@@ -152,6 +159,7 @@ live in the ignored `.submilli-bin/` directory:
 ```sh
 SUBMILLI_BIN=$PWD/../../.submilli-bin uv run pytest tests/integration -m 'not durable'         # submilli
 SUBMILLI_BIN=$PWD/../../.submilli-bin uv run pytest tests/integration_tests -m 'not durable'   # langchain-submilli
+SUBMILLI_BIN=$PWD/../../.submilli-bin uv run pytest tests/integration_tests                    # openai-agents-submilli
 ```
 
 Durable integration tests require an upstream runtime build containing durable callbacks
@@ -176,9 +184,10 @@ CI runs formatting, linting, type checks, unit tests, integration tests, and sta
 installation checks.
 
 Release a package by pushing a tag that matches its `pyproject.toml` version:
-`submilli-v0.1.0` or `langchain-submilli-v0.1.0`. The release workflow publishes that package
-to PyPI through trusted publishing. Release `submilli` before a `langchain-submilli` version
-that depends on it.
+`submilli-v0.1.0`, `langchain-submilli-v0.1.0`, or `openai-agents-submilli-v0.1.0`. The release
+workflow publishes that package to PyPI through trusted publishing. Release `submilli` before an
+integration version that depends on it. A new package's first release needs its PyPI project
+registered for trusted publishing first.
 
 ## License
 

packages/openai-agents-submilli/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to this project are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
+[Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - Unreleased
+
+First release, for submilli-server 0.4.1, the `submilli` SDK 0.1.2, and openai-agents 0.24.
+
+### Added
+
+- `SubmilliTools` for OpenAI Agents SDK agents: the server's six tools as `FunctionTool`s,
+  with the Blueprint's descriptions, and one session per conversation, bound to the variables
+  and secrets from the run's context.
+- Sessions kept in a `SessionStore`: `InMemorySessionStore` (default) or `SQLiteSessionStore`.
+  `aclose_conversation` ends a conversation's session.
+- Retries with an `Idempotency-Key` per tool call. A session that ended is replaced, and the
+  model is told. A conversation whose variables changed is refused before the model runs.
+- Execution and session ids, and the program's application-tool calls, in the output item's
+  `custom_data`.
+- `ptc` (programmatic tool calling): programs call the application's function tools as
+  `@tools`. Each call runs as an SDK tool call, and a tool's `needs_approval` pauses the run
+  with a `ToolApprovalItem` for that call, resumed with `RunState.approve` or `reject`.