Add OpenAI Responses API vm_run integration example

docs/integrations.md

@@ -0,0 +1,93 @@
+# Integration Targets
+
+These are the main ways to integrate `pyro-mcp` into an LLM application.
+
+## Recommended Default
+
+Use `vm_run` first.
+
+That keeps the model-facing contract small:
+
+- one tool
+- one command
+- one ephemeral VM
+- automatic cleanup
+
+Only move to lifecycle tools when the agent truly needs VM state across multiple calls.
+
+## OpenAI Responses API
+
+Best when:
+
+- your agent already uses OpenAI models directly
+- you want a normal tool-calling loop instead of MCP transport
+- you want the smallest amount of integration code
+
+Recommended surface:
+
+- `vm_run`
+
+Canonical example:
+
+- [examples/openai_responses_vm_run.py](/home/thales/projects/personal/pyro/examples/openai_responses_vm_run.py)
+
+## MCP Clients
+
+Best when:
+
+- your host application already supports MCP
+- you want `pyro` to run as an external stdio server
+- you want tool schemas to be discovered directly from the server
+
+Recommended entrypoint:
+
+- `pyro mcp serve`
+
+Starter config:
+
+- [examples/mcp_client_config.md](/home/thales/projects/personal/pyro/examples/mcp_client_config.md)
+
+## Direct Python SDK
+
+Best when:
+
+- your application owns orchestration itself
+- you do not need MCP transport
+- you want direct access to `Pyro`
+
+Recommended default:
+
+- `Pyro.run_in_vm(...)`
+
+Examples:
+
+- [examples/python_run.py](/home/thales/projects/personal/pyro/examples/python_run.py)
+- [examples/python_lifecycle.py](/home/thales/projects/personal/pyro/examples/python_lifecycle.py)
+
+## Agent Framework Wrappers
+
+Examples:
+
+- LangChain tools
+- PydanticAI tools
+- custom in-house orchestration layers
+
+Best when:
+
+- you already have an application framework that expects a Python callable tool
+- you want to wrap `vm_run` behind framework-specific abstractions
+
+Recommended pattern:
+
+- keep the framework wrapper thin
+- map framework tool input directly onto `vm_run`
+- avoid exposing lifecycle tools unless the framework truly needs them
+
+## Selection Rule
+
+Choose the narrowest integration that matches the host environment:
+
+1. OpenAI Responses API if you want a direct provider tool loop.
+2. MCP if your host already speaks MCP.
+3. Python SDK if you own orchestration and do not need transport.
+4. Framework wrappers only as thin adapters over the same `vm_run` contract.