[Feature/Example] Add End-to-End Example Integrating Google SecOps OneMCP with OpenAI Agents API

[dandye]

Issue Overview

This issue proposes building and documenting a reference implementation that connects OpenAI's Agents API to Google SecOps via remote HTTP Model Context Protocol (MCP) endpoints (OneMCP / mcp-security).

OpenAI's Agents API provides native support for remote HTTP-based MCP tool servers and automated multi-agent delegation. Exposing an official example demonstrates cross-platform agentic security operations (SecOps), allowing autonomous tier-1 alert investigation, IOC enrichment, and automated incident triage across vendor ecosystems.

---

Motivation and Objectives

Objective	Target Outcome	Value Proposition
Specification Validation	Validate OpenAI Agents API remote HTTP MCP client against Google Cloud OneMCP endpoints.	Ensures spec-compliant streaming and tool calling interoperability.
Enterprise SecOps Workflow	Demonstrate autonomous alert triage using UDM search and threat intelligence tools.	Reduces Mean Time to Detect (MTTD) and Triage (MTTR) for multi-model SecOps teams.
Cross-Platform Enablement	Provide a turnkey script demonstrating credential management and multi-agent delegation.	Equips field engineers and customers to connect existing SecOps tooling to external agent runtimes.

---

Component Mapping

OpenAI Agents API Parameter	Configuration / Value	SecOps OneMCP / mcp-security Equivalent
tools[].type	"mcp"	Open standard Model Context Protocol tool provider.
tools[].server_label	"google_secops"	Logical namespace for SecOps Chronicle / TI tools.
tools[].transport.type	"http"	Remote HTTP/SSE MCP transport layer.
tools[].transport.server_url	Hosted SecOps endpoint (or reverse proxy)	SecOps OneMCP endpoint URL (e.g., https://chronicle.googleapis.com/mcp).
vault_ids	["vault_gcp_credentials"]	Manages GCP OAuth2 access token or service account credentials.
multi_agent.enabled	true	Coordinates specialized subagents (Detection, TI, Remediation).

---

Reference Implementation Code Sample

import OpenAI from "openai";

const client = new OpenAI();

/**
 * Creates an autonomous SecOps investigation session using OpenAI Agents API
 * backed by Google SecOps OneMCP / mcp-security HTTP server tools.
 */
const session = await client.beta.agents.sessions.create({
  agent: {
    model: "gpt-6-astra",
    tools: [
      {
        type: "mcp",
        server_label: "google_secops",
        transport: {
          type: "http",
          server_url: process.env.SECOPS_ONEMCP_URL || "https://chronicle.googleapis.com/mcp",
        },
      },
    ],
    multi_agent: {
      enabled: true,
      max_concurrent_subagents: 3,
    },
  },
  vault_ids: [process.env.OPENAI_VAULT_GCP_ID || "vault_gcp_secops_prod"],
  environment: {
    type: "openai_hosted",
    capability_directories: ["/workspace/capabilities/skills"],
  },
  input:
    "Investigate high-severity alert 'Suspicious PowerShell Download Cradle' on host 'srv-app-04'. " +
    "Delegate tasks across subagents: " +
    "1. Subagent A: Query UDM events for process execution trees and network connections within +/- 15 minutes of alert time. " +
    "2. Subagent B: Enrich all external destination IPs and file hashes via Google Threat Intelligence. " +
    "3. Subagent C: Evaluate lateral movement indicators and assess user risk score. " +
    "Synthesize all findings, IOC attribution, and containment recommendations into /workspace/outputs/incident_summary.md.",
});

console.log(`SecOps investigation session initiated: ${session.id}`);

---

Implementation Scope & Deliverables

Deliverable	Description	Primary Location
Runnable Script	Complete Node.js / TypeScript example initializing the agent session.	examples/openai-agents-api/investigate_alert.ts
Authentication Guide	Documentation on handling GCP OAuth token injection via OpenAI Vault or API gateway headers.	examples/openai-agents-api/README.md
Mock / Sandbox Runner	Local test harness supporting recorded MCP server responses for CI validation.	examples/openai-agents-api/tests/
Architecture Diagram	Visual layout mapping orchestrator, subagents, MCP protocol boundary, and SecOps APIs.	docs/architecture/openai_agents_onemcp.png

---

Technical Considerations & Prerequisites

1. Authentication Transport:

• OneMCP endpoints on One Platform enforce IAM authorization and audit logging.
• The example must demonstrate injecting the Authorization header (Bearer <GCP_ACCESS_TOKEN>) into the remote HTTP transport or configuring OpenAI Vault to pass ambient workload identity.

2. Tool Surface Curation:

• Limit initial tool exposure to high-value investigative functions (UDM search, alert retrieval, rule evaluation, and IOC lookup) to minimize token consumption and avoid exceeding tool definition limits.

3. Subagent Specialization:

• Structure subagent prompts with strict scopes: evidence collection, threat intelligence correlation, and containment formulation.

---

Acceptance Criteria

• Script successfully initializes a session against the Agents API using type: "mcp" and type: "http".
• At least one tool call to a SecOps MCP method (e.g., list_alerts or search_udm_events) completes and returns structured output.
• Multi-agent subagents execute in parallel without session collisions.
• Output artifacts are written to /workspace/outputs/incident_summary.md.
• Comprehensive README provided with prerequisites, environment variables, and execution steps.