feat: gRPC adapter for language-agnostic agent support by raahulrahl · Pull Request #392 · GetBindu/Bindu

raahulrahl · 2026-03-23T13:07:43Z

Summary

Adds gRPC adapter enabling TypeScript, Kotlin, and Rust agents to bindufy themselves through the Python core
Defines proto/agent_handler.proto with BinduService (registration) and AgentHandler (task execution) contracts
GrpcAgentClient is a drop-in callable replacement for manifest.run — ManifestWorker, ResultProcessor, ResponseDetector require zero changes
Extracts _bindufy_core() from bindufy() so both Python and gRPC registration paths share the same DID/auth/x402/A2A logic (DRY)
Includes TypeScript SDK (@bindu/sdk) and Kotlin SDK (bindu-sdk) with auto core-launcher
Adds examples: typescript-langchain-agent, typescript-openai-agent, kotlin-openai-agent

Architecture

SDK (TS/Kotlin)                    Bindu Core (Python)
  bindufy(config, handler)
    │
    ├─ spawns `bindu serve --grpc`  → gRPC server on :3774
    ├─ starts AgentHandler server   → random port
    ├─ calls RegisterAgent          → core runs _bindufy_core()
    │                                  (DID, auth, x402, manifest, uvicorn :3773)
    │
    │  ... task arrives via A2A ...
    │                                  worker calls manifest.run(messages)
    ◄── HandleMessages(messages) ──    = GrpcAgentClient → gRPC to SDK
    │
    handler(messages) → response
    ──► response ──────────────────►   ResultProcessor → ResponseDetector → Storage

Test plan

33 new unit tests for gRPC client, registry, and service
743 total tests pass (existing + new)
All pre-commit hooks pass (ruff, ty, pytest, bandit, pydocstyle, secrets)
Manual integration test: start core with bindu serve --grpc, connect TS agent
Verify A2A message flow end-to-end through gRPC handler

🤖 Generated with Claude Code

…gRPC settings Extract core bindufy logic into _bindufy_core() to support both Python (bindufy()) and gRPC (RegisterAgent) registration paths. Add caller_dir, skills_override, skip_handler_validation, and run_server_in_background parameters to enable gRPC service to pass pre-loaded skills, skip Python handler validation, and run uvicorn in background thread. Add GrpcSettings to settings.py with enabled flag, host/port config, worker

…t, Kotlin) - Add proto/agent_handler.proto defining BinduService and AgentHandler contracts - Add GrpcAgentClient as a drop-in replacement for manifest.run (zero changes to ManifestWorker) - Add BinduServiceImpl handling RegisterAgent from language SDKs - Add AgentRegistry for tracking remote agents - Add GrpcSettings with port 3774, configurable via GRPC__ env prefix - Extract _bindufy_core() from bindufy() for DRY reuse between Python and gRPC paths - Add `bindu serve --grpc` CLI command for SDK-spawned core process - Add TypeScript SDK (@bindu/sdk) with bindufy(), core-launcher, and gRPC server/client - Add Kotlin SDK (bindu-sdk) with bindufy(), CoreLauncher, and AgentHandler service - Add examples: typescript-langchain-agent, typescript-openai-agent, kotlin-openai-agent - Add 33 unit tests for gRPC client, registry, and service - Exclude generated proto files from linting in pre-commit config Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…proto path resolution in TypeScript SDK - Skip signal handler registration when uvicorn runs in background thread (gRPC flow) - Add threading.current_thread() check in setup_signal_handlers() - Update run_server() docstring to document main/background thread support - Fix TypeScript SDK proto path resolution to work from both src/ and dist/ - Add yaml dependency to TypeScript SDK package.json

…mple Delete committed node_modules directory including symlinks, package-lock.json, and all dependencies. These should be generated locally via npm install and excluded from version control.

…ignore for SDK artifacts - Add comprehensive gRPC testing guide with grpcurl examples in GRPC_LANGUAGE_AGNOSTIC.md - Document streaming limitation (HandleMessagesStream proto-defined but not implemented) - Add streaming support to GrpcAgentClient with use_streaming parameter and _handle_streaming() method - Remove unused --port flag from `bindu serve` CLI (only --grpc-port needed) - Update README.md with gRPC feature entry, separate unit/E2E test commands, and CI documentation

…ntation to README - Add TypeScript agent quickstart example with OpenAI SDK in Option 2 section - Document gRPC-based language support with Python/TypeScript/Kotlin code examples - Add TypeScript (OpenAI SDK, LangChain.js) and Kotlin (OpenAI Kotlin SDK) to supported frameworks - Update roadmap: mark gRPC/language-agnostic SDKs complete, add Rust SDK - Expand typescript-langchain-agent .env.example with storage/scheduler config

…onfigurations Add `# pragma: allowlist secret` comments to DATABASE_URL example values in TypeScript agent .env.example files to prevent false positives in secret scanning tools.

…actical focus Restructure gRPC docs to emphasize developer experience over implementation details: - Rewrite README.md with "The Problem/The Solution" framing showing why gRPC matters - Add concrete message flow example showing client → core → SDK → OpenAI path - Replace technical architecture-first approach with "what you write vs what Bindu handles" - Simplify client.md to focus on the callable bridge pattern and response

… practical focus Restructure SDK development documentation to emphasize developer experience: - Rewrite sdk-development.md with "What an SDK Does" framing showing the four core responsibilities - Replace architecture diagrams with concrete implementation steps - Add language-specific protoc command reference table (Rust, Go, Swift, C#) - Document HandleMessages contract with input/output format and error handling rules - Simpl

…practical examples Restructure api-reference.md to emphasize the gRPC contract between SDKs and core: - Reframe "Two gRPC Services" as "Services" with port-based organization - Add detailed RegisterAgent config_json format example showing Python bindufy() compatibility - Document "What the core does" for RegisterAgent (validation, ID generation, DID keys, x402, manifest, HTTP server) - Add response rules table for HandleMessages showing

raahulrahl and others added 2 commits March 23, 2026 13:59

raahulrahl force-pushed the main branch from 2d49238 to 3835fe2 Compare March 23, 2026 14:24

raahulrahl added 8 commits March 23, 2026 16:12

chore: remove node_modules directory from typescript-openai-agent exa…

080eda0

…mple Delete committed node_modules directory including symlinks, package-lock.json, and all dependencies. These should be generated locally via npm install and excluded from version control.

chore: add pragma allowlist secret comments to example DATABASE_URL c…

916bd7f

…onfigurations Add `# pragma: allowlist secret` comments to DATABASE_URL example values in TypeScript agent .env.example files to prevent false positives in secret scanning tools.

raahulrahl merged commit a8c3dec into main Mar 23, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: gRPC adapter for language-agnostic agent support#392

feat: gRPC adapter for language-agnostic agent support#392
raahulrahl merged 10 commits intomainfrom
feat/grpc-adapter-language-agnostic

raahulrahl commented Mar 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

raahulrahl commented Mar 23, 2026

Summary

Architecture

Test plan

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant