Protocol Agent Integration Paths
This guide helps partner teams choose the right entrypoint into @opensocial/protocol-agent.
The package supports three shapes:
- client
- toolset
- toolkit
They all use the same protocol actions. The difference is how much orchestration glue you want the SDK to carry for you.
1. Client
Use the raw agent client when you want direct method calls and already control the execution flow yourself.
Best for:
- application code
- deterministic workflows
- service code that already knows which method to call
Use:
- Agent quickstart
scripts/examples/protocol-partner-agent.mjs
2. Toolset
Use the toolset when your orchestrator wants a list of tools with descriptions, input schemas, and callables.
Best for:
- tool-driven runtimes
- future OpenAI Agents SDK wiring
- orchestrators that want to register tools one by one
Use:
- Agent toolset
scripts/examples/protocol-partner-agent-toolset.mjs
3. Toolkit
Use the toolkit when you want the bound agent client plus indexed tools and helper utilities together.
Best for:
- orchestrators that want both direct methods and tool invocation
- adapters that want a single object to pass around
- integration layers that need inspect/get/invoke helpers
Use:
- Agent toolset
scripts/examples/protocol-partner-agent-toolkit.mjs
Shared Recommendation
Whichever path you choose:
- assert readiness before acting when failures should block execution
- keep the app token, actor user, and delegated grants explicit
- stay inside the shipped coordination primitives
For readiness and operational preflight:
Guardrails
- These are different integration shapes, not different protocol contracts.
- None of them add posts, follows, feeds, or other unsupported social primitives.
- None of them replace the protocol contract as the source of truth.