copass-google-agents 0.1.0__tar.gz

copass_google_agents-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Dependencies
+node_modules/
+
+# Build output
+dist/
+*.tsbuildinfo
+
+# Environment
+.env
+.env.*
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Test
+coverage/
+
+# Lerna
+lerna-debug.log
+.nx/cache
+.nx/workspace-data
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+.venv/
+venv/
+.olane

copass_google_agents-0.1.0/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: copass-google-agents
+Version: 0.1.0
+Summary: Copass agent primitives for Google Vertex AI Agent Engine (ADK)
+Project-URL: Homepage, https://github.com/olane-labs/copass-harness
+Project-URL: Repository, https://github.com/olane-labs/copass-harness.git
+Author: Olane Inc.
+License: MIT
+Keywords: adk,agent-engine,agents,copass,google,knowledge-graph,vertex-ai
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: copass-core-agents>=0.1.0
+Requires-Dist: google-cloud-aiplatform[adk,agent-engines]>=1.148.1
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# copass-google-agents
+
+Google Vertex AI **Agent Engine** (ADK) backend for Copass. Depends on [`copass-core-agents`](../copass-core-agents), which owns the vendor-neutral primitives (`BaseAgent`, `AgentTool`, `AgentBackend` ABC, events, `AgentScope`, registries, etc.) shared across every provider-specific Copass SDK.
+
+This package owns the Google-specific piece — `GoogleAgentBackend` and the `CopassGoogleAgent` convenience subclass — and re-exports the core primitives for one-line dev imports. Either of these works for consumers:
+
+```python
+from copass_google_agents import BaseAgent, CopassGoogleAgent  # convenient
+# or
+from copass_core_agents import BaseAgent                       # explicit boundary
+from copass_google_agents import CopassGoogleAgent
+```
+
+Pairs with Copass's server-side router — both sides import the same code so the agent runtime is a single codepath, whether the agent runs in the dev's process or server-side via Copass's Router endpoint.
+
+> **Status: scaffold (v0.1.0).** Constructors, type surface, and public imports are in place. `GoogleAgentBackend.run` / `GoogleAgentBackend.stream` / `deploy_adk_agent` / `adk_event_to_agent_events` currently raise `NotImplementedError`. Implementation lands in a follow-up pass.
+
+## Install
+
+```bash
+pip install copass-google-agents
+```
+
+Requires `google-cloud-aiplatform[agent_engines,adk]>=1.148.1` (which pulls in `google-adk>=1.31`). Uses Application Default Credentials (ADC) — run `gcloud auth application-default login` locally, or set `GOOGLE_APPLICATION_CREDENTIALS` / attach a service account.
+
+## Architecture
+
+Agent Engine diverges from Claude Managed Agents in one important way: **ADK agents are pre-deployed resources** (`projects/{p}/locations/{l}/reasoningEngines/{id}`) and their **tools are baked in at deploy time**. You cannot pass tools per-run.
+
+To preserve Copass's `AgentToolResolver` runtime-plug model, `copass-google-agents` deploys ADK agents carrying a single `copass_dispatch(tool_name, arguments)` function tool. At run time that proxy calls back into your Copass service, which hosts the real resolver and invokes the right tool for the current user.
+
+So:
+- **`GoogleAgentBackend`** is *session-only* — streams queries against a pre-deployed engine.
+- **`deploy_adk_agent`** (ops helper) is the one-time setup that wires the proxy tool into a new ADK agent resource.
+- **Zero client-side tools** is the expected case. `CopassGoogleAgent` defaults to an empty `AgentToolRegistry`.
+
+## Quickstart (planned — not functional in the scaffold)
+
+```python
+import os
+from copass_google_agents import (
+    AgentInvocationContext,
+    AgentScope,
+    CopassGoogleAgent,
+)
+
+agent = CopassGoogleAgent(
+    identity="support",
+    system_prompt="You are a support agent.",
+    project=os.environ["GOOGLE_CLOUD_PROJECT"],
+    reasoning_engine_id=os.environ["COPASS_REASONING_ENGINE_ID"],
+)
+
+ctx = AgentInvocationContext(scope=AgentScope(user_id="u-123"))
+result = await agent.run(
+    messages=[{"role": "user", "content": "Hello"}],
+    context=ctx,
+)
+print(result.final_text)
+```
+
+## Streaming (planned)
+
+```python
+from copass_google_agents import (
+    AgentFinish,
+    AgentTextDelta,
+    AgentToolCall,
+    AgentToolResult,
+)
+
+async for evt in agent.stream(messages, context=ctx):
+    match evt:
+        case AgentTextDelta(text=chunk):
+            print(chunk, end="", flush=True)
+        case AgentToolCall(name=name):
+            print(f"\n[tool-call] {name}")
+        case AgentToolResult(name=name):
+            print(f"\n[tool-result] {name}")
+        case AgentFinish(stop_reason=reason, session_id=sid):
+            print(f"\n[finish] {reason} session={sid}")
+```
+
+## Multi-turn continuation (planned)
+
+Agent Engine sessions hold conversation state. Capture `AgentFinish.session_id` and thread it back on the next turn:
+
+```python
+from copass_google_agents import SESSION_ID_HANDLE
+
+ctx2 = AgentInvocationContext(
+    scope=AgentScope(user_id="u-123"),
+    handles={SESSION_ID_HANDLE: prior_session_id},
+)
+```
+
+## Deploying an ADK agent (planned)
+
+```python
+from copass_google_agents.deploy import deploy_adk_agent
+
+engine = deploy_adk_agent(
+    display_name="support-agent",
+    project="my-gcp-project",
+    system_prompt="You are a support agent...",
+    copass_api_url="https://api.copass.id",
+    copass_api_key=os.environ["COPASS_API_KEY"],
+)
+print(engine.resource_name)  # feed into CopassGoogleAgent(reasoning_engine_id=...)
+```
+
+## License
+
+MIT.

copass_google_agents-0.1.0/README.md

@@ -0,0 +1,114 @@
+# copass-google-agents
+
+Google Vertex AI **Agent Engine** (ADK) backend for Copass. Depends on [`copass-core-agents`](../copass-core-agents), which owns the vendor-neutral primitives (`BaseAgent`, `AgentTool`, `AgentBackend` ABC, events, `AgentScope`, registries, etc.) shared across every provider-specific Copass SDK.
+
+This package owns the Google-specific piece — `GoogleAgentBackend` and the `CopassGoogleAgent` convenience subclass — and re-exports the core primitives for one-line dev imports. Either of these works for consumers:
+
+```python
+from copass_google_agents import BaseAgent, CopassGoogleAgent  # convenient
+# or
+from copass_core_agents import BaseAgent                       # explicit boundary
+from copass_google_agents import CopassGoogleAgent
+```
+
+Pairs with Copass's server-side router — both sides import the same code so the agent runtime is a single codepath, whether the agent runs in the dev's process or server-side via Copass's Router endpoint.
+
+> **Status: scaffold (v0.1.0).** Constructors, type surface, and public imports are in place. `GoogleAgentBackend.run` / `GoogleAgentBackend.stream` / `deploy_adk_agent` / `adk_event_to_agent_events` currently raise `NotImplementedError`. Implementation lands in a follow-up pass.
+
+## Install
+
+```bash
+pip install copass-google-agents
+```
+
+Requires `google-cloud-aiplatform[agent_engines,adk]>=1.148.1` (which pulls in `google-adk>=1.31`). Uses Application Default Credentials (ADC) — run `gcloud auth application-default login` locally, or set `GOOGLE_APPLICATION_CREDENTIALS` / attach a service account.
+
+## Architecture
+
+Agent Engine diverges from Claude Managed Agents in one important way: **ADK agents are pre-deployed resources** (`projects/{p}/locations/{l}/reasoningEngines/{id}`) and their **tools are baked in at deploy time**. You cannot pass tools per-run.
+
+To preserve Copass's `AgentToolResolver` runtime-plug model, `copass-google-agents` deploys ADK agents carrying a single `copass_dispatch(tool_name, arguments)` function tool. At run time that proxy calls back into your Copass service, which hosts the real resolver and invokes the right tool for the current user.
+
+So:
+- **`GoogleAgentBackend`** is *session-only* — streams queries against a pre-deployed engine.
+- **`deploy_adk_agent`** (ops helper) is the one-time setup that wires the proxy tool into a new ADK agent resource.
+- **Zero client-side tools** is the expected case. `CopassGoogleAgent` defaults to an empty `AgentToolRegistry`.
+
+## Quickstart (planned — not functional in the scaffold)
+
+```python
+import os
+from copass_google_agents import (
+    AgentInvocationContext,
+    AgentScope,
+    CopassGoogleAgent,
+)
+
+agent = CopassGoogleAgent(
+    identity="support",
+    system_prompt="You are a support agent.",
+    project=os.environ["GOOGLE_CLOUD_PROJECT"],
+    reasoning_engine_id=os.environ["COPASS_REASONING_ENGINE_ID"],
+)
+
+ctx = AgentInvocationContext(scope=AgentScope(user_id="u-123"))
+result = await agent.run(
+    messages=[{"role": "user", "content": "Hello"}],
+    context=ctx,
+)
+print(result.final_text)
+```
+
+## Streaming (planned)
+
+```python
+from copass_google_agents import (
+    AgentFinish,
+    AgentTextDelta,
+    AgentToolCall,
+    AgentToolResult,
+)
+
+async for evt in agent.stream(messages, context=ctx):
+    match evt:
+        case AgentTextDelta(text=chunk):
+            print(chunk, end="", flush=True)
+        case AgentToolCall(name=name):
+            print(f"\n[tool-call] {name}")
+        case AgentToolResult(name=name):
+            print(f"\n[tool-result] {name}")
+        case AgentFinish(stop_reason=reason, session_id=sid):
+            print(f"\n[finish] {reason} session={sid}")
+```
+
+## Multi-turn continuation (planned)
+
+Agent Engine sessions hold conversation state. Capture `AgentFinish.session_id` and thread it back on the next turn:
+
+```python
+from copass_google_agents import SESSION_ID_HANDLE
+
+ctx2 = AgentInvocationContext(
+    scope=AgentScope(user_id="u-123"),
+    handles={SESSION_ID_HANDLE: prior_session_id},
+)
+```
+
+## Deploying an ADK agent (planned)
+
+```python
+from copass_google_agents.deploy import deploy_adk_agent
+
+engine = deploy_adk_agent(
+    display_name="support-agent",
+    project="my-gcp-project",
+    system_prompt="You are a support agent...",
+    copass_api_url="https://api.copass.id",
+    copass_api_key=os.environ["COPASS_API_KEY"],
+)
+print(engine.resource_name)  # feed into CopassGoogleAgent(reasoning_engine_id=...)
+```
+
+## License
+
+MIT.

copass_google_agents-0.1.0/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "copass-google-agents"
+version = "0.1.0"
+description = "Copass agent primitives for Google Vertex AI Agent Engine (ADK)"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Olane Inc." }]
+requires-python = ">=3.10"
+keywords = [
+    "copass",
+    "knowledge-graph",
+    "google",
+    "vertex-ai",
+    "agent-engine",
+    "adk",
+    "agents",
+]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "google-cloud-aiplatform[agent_engines,adk]>=1.148.1",
+    "copass-core-agents>=0.1.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "mypy>=1.10",
+    "ruff>=0.5",
+]
+
+[project.urls]
+Homepage = "https://github.com/olane-labs/copass-harness"
+Repository = "https://github.com/olane-labs/copass-harness.git"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/copass_google_agents"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+packages = ["copass_google_agents"]

copass_google_agents-0.1.0/src/copass_google_agents/__init__.py

@@ -0,0 +1,104 @@
+"""Copass agent SDK for Google Vertex AI Agent Engine (ADK).
+
+This package owns the Google-specific backend. All provider-neutral
+ABCs (``BaseAgent``, ``AgentTool``, ``AgentBackend``, events, scope,
+registries) live in :mod:`copass_core_agents` and are re-exported here
+for convenience — dev code can import everything it needs from one
+place.
+
+Public surface:
+
+    Google-specific (owned here):
+        GoogleAgentBackend
+        CopassGoogleAgent           — convenience subclass of BaseAgent
+        DEFAULT_LOCATION
+        DEFAULT_MODEL
+        DISPATCH_TOOL_NAME
+        SESSION_ID_HANDLE
+
+    Provider-neutral (re-exported from copass_core_agents):
+        BaseAgent, AgentScope, AgentInvocationContext
+        AgentTool, AgentToolRegistry, AgentToolResolver
+        ToolSpec, ToolCall, ToolConflictPolicy, ToolConflictError
+        AgentEvent, AgentTextDelta, AgentToolCall, AgentToolResult,
+        AgentFinish
+        AgentBackend, AgentRunResult
+        register_agent, get_agent_class, list_agents
+        register_agent_tool, get_agent_tool, try_get_agent_tool,
+        list_agent_tools
+"""
+
+# Re-export core (vendor-neutral) primitives for one-line imports.
+from copass_core_agents import (
+    AgentBackend,
+    AgentEvent,
+    AgentFinish,
+    AgentInvocationContext,
+    AgentRunResult,
+    AgentScope,
+    AgentTextDelta,
+    AgentTool,
+    AgentToolCall,
+    AgentToolRegistry,
+    AgentToolResolver,
+    AgentToolResult,
+    BaseAgent,
+    ToolCall,
+    ToolConflictError,
+    ToolConflictPolicy,
+    ToolSpec,
+    get_agent_class,
+    get_agent_tool,
+    list_agent_tools,
+    list_agents,
+    register_agent,
+    register_agent_tool,
+    try_get_agent_tool,
+)
+
+# Google-specific (owned here).
+from copass_google_agents.backends.google_agent_backend import (
+    DEFAULT_LOCATION,
+    DISPATCH_TOOL_NAME,
+    SESSION_ID_HANDLE,
+    GoogleAgentBackend,
+)
+from copass_google_agents.google_agent import DEFAULT_MODEL, CopassGoogleAgent
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    # Google-specific
+    "CopassGoogleAgent",
+    "DEFAULT_MODEL",
+    "GoogleAgentBackend",
+    "DEFAULT_LOCATION",
+    "DISPATCH_TOOL_NAME",
+    "SESSION_ID_HANDLE",
+    # Re-exported from copass_core_agents
+    "BaseAgent",
+    "AgentScope",
+    "AgentInvocationContext",
+    "AgentTool",
+    "AgentToolRegistry",
+    "AgentToolResolver",
+    "ToolSpec",
+    "ToolCall",
+    "ToolConflictError",
+    "ToolConflictPolicy",
+    "AgentEvent",
+    "AgentTextDelta",
+    "AgentToolCall",
+    "AgentToolResult",
+    "AgentFinish",
+    "AgentBackend",
+    "AgentRunResult",
+    "register_agent",
+    "get_agent_class",
+    "list_agents",
+    "register_agent_tool",
+    "get_agent_tool",
+    "try_get_agent_tool",
+    "list_agent_tools",
+]

copass_google_agents-0.1.0/src/copass_google_agents/_proxy_tool.py

@@ -0,0 +1,101 @@
+"""Module-scope definition of the ``copass_dispatch`` proxy tool.
+
+ADK serializes function tools by reference; closures over deploy-time
+variables do not round-trip into Agent Engine's remote runtime.
+This module defines the tool at module scope and reads its
+configuration from environment variables baked into the deployed
+engine (``COPASS_API_URL``, ``COPASS_API_KEY``, ``COPASS_DISPATCH_PATH``).
+
+The function's signature and docstring are what ADK exposes to the
+model as the tool schema — keep both pedagogical.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, Optional
+
+
+DEFAULT_DISPATCH_PATH = "/api/v1/agents/dispatch"
+"""Default path on the Copass service where the proxy POSTs tool
+invocations. Overridable at deploy time via ``COPASS_DISPATCH_PATH``."""
+
+
+async def copass_dispatch(
+    tool_name: str,
+    arguments: Dict[str, Any],
+    tool_context: Optional[Any] = None,
+) -> Dict[str, Any]:
+    """Route a tool invocation through Copass's server-side resolver.
+
+    ADK Agent Engine bakes tools at deploy time. To preserve the
+    runtime ``AgentToolResolver`` plug model, every deployed Copass
+    agent carries exactly this one function tool. The model calls
+    ``copass_dispatch`` with the logical tool name and arguments;
+    the Copass service receives the call, looks the tool up against
+    the current user's resolver, executes it, and returns the result.
+
+    Args:
+        tool_name: The logical name of the tool to invoke (as
+            advertised in the agent's system prompt).
+        arguments: JSON-serializable arguments for the tool.
+        tool_context: ADK-injected context providing ``user_id`` and
+            ``session_id`` when available. ADK populates this
+            automatically at invocation time.
+
+    Returns:
+        The tool result dict, passed straight from the Copass
+        service response body.
+    """
+    import httpx  # deferred import — keeps cold-start lean
+
+    api_url = os.environ.get("COPASS_API_URL")
+    api_key = os.environ.get("COPASS_API_KEY")
+    if not api_url or not api_key:
+        return {
+            "error": (
+                "copass_dispatch misconfigured: COPASS_API_URL / "
+                "COPASS_API_KEY env vars not set on the deployed agent."
+            )
+        }
+    path = os.environ.get("COPASS_DISPATCH_PATH", DEFAULT_DISPATCH_PATH)
+
+    user_id = None
+    session_id = None
+    if tool_context is not None:
+        user_id = getattr(tool_context, "user_id", None)
+        session_id = getattr(tool_context, "session_id", None)
+
+    payload = {
+        "tool_name": tool_name,
+        "arguments": arguments or {},
+        "user_id": user_id,
+        "session_id": session_id,
+    }
+    url = f"{api_url.rstrip('/')}{path}"
+
+    async with httpx.AsyncClient(timeout=60.0) as http:
+        resp = await http.post(
+            url,
+            json=payload,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+            },
+        )
+        try:
+            resp.raise_for_status()
+        except httpx.HTTPStatusError as err:
+            return {
+                "error": (
+                    f"copass_dispatch HTTP {resp.status_code}: {err}"
+                ),
+                "response_text": resp.text[:1000],
+            }
+        try:
+            return dict(resp.json())
+        except ValueError:
+            return {"text": resp.text}
+
+
+__all__ = ["copass_dispatch", "DEFAULT_DISPATCH_PATH"]

copass_google_agents-0.1.0/src/copass_google_agents/backends/__init__.py

@@ -0,0 +1,23 @@
+"""Google agent backends.
+
+Re-exports the core ``AgentBackend`` / ``AgentRunResult`` ABCs
+(implemented in ``copass-core-agents``) alongside this package's
+Google-specific ``GoogleAgentBackend``.
+"""
+
+from copass_core_agents.backends import AgentBackend, AgentRunResult
+from copass_google_agents.backends.google_agent_backend import (
+    DEFAULT_LOCATION,
+    DISPATCH_TOOL_NAME,
+    SESSION_ID_HANDLE,
+    GoogleAgentBackend,
+)
+
+__all__ = [
+    "AgentBackend",
+    "AgentRunResult",
+    "GoogleAgentBackend",
+    "DEFAULT_LOCATION",
+    "DISPATCH_TOOL_NAME",
+    "SESSION_ID_HANDLE",
+]