Add connector registry for installed plugins

Author: dannyzhang-oai

docs/connectors.md

@@ -10,6 +10,58 @@ separate runtime. A connector resolves to existing SDK primitives:
 Use connectors when you want to mount a named bundle of tools or package-provided MCP servers on
 one or more agents without manually copying every tool and server into each agent definition.
 
+## Installed plugin registries
+
+Use [`ConnectorRegistry`][agents.connectors.ConnectorRegistry] when your application already has
+installed plugin records from a Unified Plugins-style directory, marketplace, or workspace plugin
+service. The SDK does not fetch those records itself; the registry is an adapter over records that
+Codex, ChatGPT, your control plane, or tests have already provided.
+
+A registry record can point at a mounted local package, hosted app connector IDs, or both. Loading
+the record still produces a normal [`Connector`][agents.connectors.Connector].
+
+```python
+from agents import Agent, Connector, ConnectorRegistry
+
+
+registry = ConnectorRegistry.from_plugin_records(
+    [
+        {
+            "id": "plugin_orders",
+            "name": "orders",
+            "package_path": "./orders-plugin",
+        },
+        {
+            "id": "plugin_calendar",
+            "name": "calendar",
+            "apps": {
+                "calendar": {
+                    "id": "connector_googlecalendar",
+                }
+            },
+        },
+    ]
+)
+
+orders = Connector.from_installed_plugin("plugin_orders", registry)
+calendar = Connector.from_installed_plugin(
+    "plugin_calendar",
+    registry,
+    authorization={"calendar": "conn_calendar_access_token"},
+    hosted_mcp_require_approval="always",
+)
+
+agent = Agent(
+    name="Assistant",
+    instructions="Use installed connector plugins when needed.",
+    connectors=[orders, calendar],
+)
+```
+
+This keeps package discovery, marketplace installation, workspace sharing, admin policy, and cloud
+sync outside the SDK runtime while giving those systems a stable place to hand installed plugin
+records to the SDK.
+
 ## SDK tool connectors
 
 Use [`Connector.from_tools()`][agents.connectors.Connector.from_tools] when your integration is
@@ -115,8 +167,9 @@ They are sent to the Responses API like other hosted tools.
 ## End-to-end demo
 
 See `examples/connectors/package_demo.py` for a deterministic demo that needs no API key. It builds
-a direct Python tool connector, creates a temporary plugin-style MCP package, mounts both on an
-agent, invokes the discovered tools, and inspects a hosted connector config.
+a direct Python tool connector, creates a temporary plugin-style MCP package, loads that package
+through a `ConnectorRegistry` record, mounts the resolved connector on an agent, invokes the
+discovered tools, and inspects a hosted connector config loaded from a registry record.
 
 Run it with:
 

docs/examples.md

@@ -45,7 +45,7 @@ Check out a variety of sample implementations of the SDK in the examples section
 -   **[connectors](https://github.com/openai/openai-agents-python/tree/main/examples/connectors):**
     Examples for packaging reusable connector surfaces, including:
 
-    -   End-to-end connector package composition without an API key (`examples/connectors/package_demo.py`)
+    -   End-to-end connector registry and package composition without an API key (`examples/connectors/package_demo.py`)
 
 -   **[customer_service](https://github.com/openai/openai-agents-python/tree/main/examples/customer_service):**
     Example customer service system for an airline.

examples/connectors/package_demo.py

@@ -8,7 +8,15 @@
 from tempfile import TemporaryDirectory
 from typing import Any
 
-from agents import Agent, Connector, FunctionTool, HostedMCPTool, RunContextWrapper, function_tool
+from agents import (
+    Agent,
+    Connector,
+    ConnectorRegistry,
+    FunctionTool,
+    HostedMCPTool,
+    RunContextWrapper,
+    function_tool,
+)
 from agents.mcp import MCPServerManager
 from agents.tool_context import ToolContext
 
@@ -29,13 +37,25 @@ def build_sdk_tool_connector() -> Connector:
 
 
 def build_hosted_connector() -> Connector:
-    return Connector.from_hosted_connector(
-        "calendar",
-        connector_id="connector_googlecalendar",
-        authorization="demo_access_token",
-        server_label="calendar",
-        require_approval="never",
-        description="Hosted Google Calendar connector shape.",
+    registry = ConnectorRegistry.from_plugin_records(
+        [
+            {
+                "id": "plugin_calendar",
+                "name": "calendar",
+                "description": "Hosted Google Calendar connector shape.",
+                "apps": {
+                    "calendar": {
+                        "id": "connector_googlecalendar",
+                    }
+                },
+            }
+        ]
+    )
+    return Connector.from_installed_plugin(
+        "plugin_calendar",
+        registry,
+        authorization={"calendar": "demo_access_token"},
+        hosted_mcp_require_approval="never",
     )
 
 
@@ -94,7 +114,17 @@ def write_demo_plugin_package(package_root: Path) -> Path:
 
 
 def build_package_connector(package_root: Path) -> Connector:
-    return Connector.from_package(package_root)
+    registry = ConnectorRegistry.from_plugin_records(
+        [
+            {
+                "id": "plugin_orders",
+                "name": "orders",
+                "package_path": str(package_root),
+                "source": "unified_plugins_demo",
+            }
+        ]
+    )
+    return Connector.from_installed_plugin("plugin_orders", registry)
 
 
 async def verify_connector_demo() -> dict[str, Any]:
@@ -144,6 +174,7 @@ async def verify_connector_demo() -> dict[str, Any]:
         "mcp_tool_result": mcp_tool_result,
         "package_connector_name": package_connector.name,
         "package_policy_labels": sorted(package_connector.policy_labels),
+        "package_registry_source": package_connector.metadata["unified_plugin"]["source"],
         "hosted_connector_label": hosted_tool.tool_config["server_label"],
         "hosted_connector_id": hosted_tool.tool_config["connector_id"],
     }
@@ -191,7 +222,8 @@ def print_summary(summary: dict[str, Any]) -> None:
     print(
         "Package connector: "
         f"{summary['package_connector_name']} "
-        f"({', '.join(summary['package_policy_labels'])})"
+        f"({', '.join(summary['package_policy_labels'])}, "
+        f"{summary['package_registry_source']})"
     )
     print(
         "Hosted connector config: "

src/agents/__init__.py

@@ -19,7 +19,9 @@
 from .connectors import (
     Connector,
     ConnectorComponents,
+    ConnectorPlugin,
     ConnectorPolicyLabel,
+    ConnectorRegistry,
     HostedConnectorAuthorization,
 )
 from .editor import ApplyPatchEditor, ApplyPatchOperation, ApplyPatchResult
@@ -367,7 +369,9 @@ def enable_verbose_stdout_logging():
     "Button",
     "Connector",
     "ConnectorComponents",
+    "ConnectorPlugin",
     "ConnectorPolicyLabel",
+    "ConnectorRegistry",
     "HostedConnectorAuthorization",
     "AgentsException",
     "InputGuardrailTripwireTriggered",