{"id":50958362,"url":"https://github.com/capiscio/langchain-capiscio","last_synced_at":"2026-06-18T10:30:27.978Z","repository":{"id":355264486,"uuid":"1179427311","full_name":"capiscio/langchain-capiscio","owner":"capiscio","description":"Trust enforcement for LangChain and LangGraph agents — verify caller badges, enforce security policies, and emit audit events via LCEL composable guards. Powered by CapiscIO.","archived":false,"fork":false,"pushed_at":"2026-05-14T03:54:58.000Z","size":27,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-13T00:06:03.232Z","etag":null,"topics":["a2a","agent-2-agent","agent-identity","agent-security","ai","ai-agent","langchain","langgraph","python"],"latest_commit_sha":null,"homepage":"https://capisc.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/capiscio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-12T02:39:22.000Z","updated_at":"2026-05-14T03:54:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/capiscio/langchain-capiscio","commit_stats":null,"previous_names":["capiscio/langchain-capiscio"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/capiscio/langchain-capiscio","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/capiscio%2Flangchain-capiscio","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/capiscio%2Flangchain-capiscio/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/capiscio%2Flangchain-capiscio/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/capiscio%2Flangchain-capiscio/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/capiscio","download_url":"https://codeload.github.com/capiscio/langchain-capiscio/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/capiscio%2Flangchain-capiscio/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34487069,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-18T02:00:06.871Z","response_time":128,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["a2a","agent-2-agent","agent-identity","agent-security","ai","ai-agent","langchain","langgraph","python"],"created_at":"2026-06-18T10:30:27.058Z","updated_at":"2026-06-18T10:30:27.973Z","avatar_url":"https://github.com/capiscio.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CapiscIO LangChain Guard\n\nTrust enforcement for LangChain and LangGraph agents.\n\n[![PyPI version](https://badge.fury.io/py/langchain-capiscio.svg)](https://badge.fury.io/py/langchain-capiscio)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n\n**LangChain Guard** is the CapiscIO trust enforcement adapter for [LangChain](https://python.langchain.com/) and [LangGraph](https://langchain-ai.github.io/langgraph/). It verifies caller trust badges, enforces security policies, and emits audit events — all composable via LangChain's LCEL pipe (`|`) operator with **zero configuration**.\n\n## Installation\n\n```bash\npip install langchain-capiscio\n```\n\n## Quick Start\n\nTurn any LangChain agent into a trust-verified agent in 2 lines:\n\n```python\nfrom langchain_capiscio import CapiscioGuard\n\n# Reads CAPISCIO_API_KEY from env, connects to registry\nsecured = CapiscioGuard.connect() | my_chain\nresult = secured.invoke({\"input\": \"Summarize this ticket\"})\n```\n\n`CapiscioGuard.connect()` reads your environment, connects to the CapiscIO registry, and returns a guard that verifies caller trust badges before every invocation — consistent with `CapiscIO.connect()` and `CapiscioMCPServer.connect()` across the ecosystem.\n\n## Why LangChain Guard?\n\nLangChain agents orchestrate powerful tools — search, databases, code execution. But LangChain itself doesn't define how to:\n\n- **Authenticate** which agent is calling your chain\n- **Authorize** whether that agent meets your trust requirements\n- **Audit** what happened for post-incident review\n\nLangChain Guard solves this with:\n\n| Feature | Description |\n|---------|-------------|\n| **`CapiscioGuard`** | `Runnable[dict, dict]` — verifies trust badges before downstream execution. Composable with `\\|`. |\n| **`CapiscioTool`** | Wraps a LangChain `Tool` with trust enforcement at the tool-call boundary. |\n| **`CapiscioCallbackHandler`** | Audit trail — emits chain/tool lifecycle events to the CapiscIO EventEmitter. |\n| **`@capiscio_guard`** | Decorator for LangGraph function-based nodes. |\n| **`verify_badge` / `resolve_agent_card`** | Convenience `@tool`-decorated functions for agent-driven trust checks. |\n\n## Enforcement Modes\n\nControl enforcement behavior per guard instance:\n\n```python\nguard = CapiscioGuard.connect(mode=\"block\")    # Fail closed (production default)\nguard = CapiscioGuard.connect(mode=\"monitor\")  # Warn but continue\nguard = CapiscioGuard.connect(mode=\"log\")      # Log only\n```\n\n## LCEL Pipe Composition\n\n`CapiscioGuard` is a LangChain `Runnable` — compose it with any chain or agent via the `|` operator:\n\n\u003e **Note**: The example below uses [LangGraph](https://langchain-ai.github.io/langgraph/).\n\u003e Install it separately: `pip install langgraph`\n\n```python\nfrom langchain_capiscio import CapiscioGuard\nfrom langgraph.prebuilt import create_react_agent\n\nagent = create_react_agent(llm, tools)\nsecured = CapiscioGuard.connect(mode=\"log\") | agent\nresult = secured.invoke({\"input\": \"What's 42 * 17?\"})\n```\n\n## Callback Handler\n\nEmit structured audit events (task lifecycle, tool calls) to the CapiscIO dashboard:\n\n```python\nfrom langchain_capiscio import CapiscioCallbackHandler\n\nhandler = CapiscioCallbackHandler(emitter=my_event_emitter)\nresult = chain.invoke(\n    {\"input\": \"...\"},\n    config={\"callbacks\": [handler]},\n)\n```\n\nEvents emitted: `task_started`, `task_completed`, `task_failed`, `tool_call`, `tool_result`.\n\n## LangGraph Integration\n\n```python\nfrom langchain_capiscio import CapiscioGuard, capiscio_guard\n\n# Option 1: Runnable as graph node\ngraph.add_node(\"verify\", CapiscioGuard.connect())\n\n# Option 2: Decorator\n@capiscio_guard(mode=\"block\")\ndef call_agent(state: dict) -\u003e dict:\n    ...\n```\n\n## \"Let's Encrypt\" Style Setup\n\n### Zero-config (recommended)\n\nSet environment variables and connect with no arguments:\n\n```bash\nexport CAPISCIO_API_KEY=\"cap_...\"\nexport CAPISCIO_SERVER_URL=\"https://dev.registry.capisc.io\"  # optional\nexport CAPISCIO_AGENT_NAME=\"my-agent\"                        # optional\nexport CAPISCIO_DEV_MODE=\"true\"                              # optional\n```\n\n```python\nguard = CapiscioGuard.connect()  # reads env vars, connects eagerly\n```\n\n### Explicit configuration\n\n```python\nguard = CapiscioGuard.connect(\n    api_key=\"cap_...\",\n    mode=\"block\",\n    name=\"my-agent\",\n    server_url=\"https://dev.registry.capisc.io\",\n)\n```\n\n### Extra connect kwargs\n\nPass additional keyword arguments through to `CapiscIO.connect()`:\n\n```python\nguard = CapiscioGuard.connect(\n    mode=\"log\",\n    dev_mode=True,\n    keys_dir=\"capiscio_keys/\",\n    agent_card=my_card_dict,\n)\n```\n\n## Using Environment Variables\n\n`CapiscioGuard.connect()` reads environment variables automatically. `from_env()` is kept as a convenience alias:\n\n```python\nguard = CapiscioGuard.connect(mode=\"log\")\n```\n\n| Variable | Required | Description | Default |\n|----------|----------|-------------|---------|\n| `CAPISCIO_API_KEY` | Yes* | Registry API key | — |\n| `CAPISCIO_SERVER_URL` | No | Registry URL override | `https://registry.capisc.io` |\n| `CAPISCIO_AGENT_NAME` | No | Agent name for registration | — |\n| `CAPISCIO_DEV_MODE` | No | Enable dev mode (`true`/`1`/`yes`) | `false` |\n| `CAPISCIO_AGENT_PRIVATE_KEY_JWK` | No | JSON-encoded Ed25519 private JWK for ephemeral environments | — |\n\n*Required if not passed explicitly via constructor.\n\nPriority: explicit constructor args \u003e `connect_kwargs` \u003e env vars \u003e SDK defaults.\n\n## Deploying to Containers / Serverless\n\nIn ephemeral environments (Docker, Lambda, Cloud Run) the local `~/.capiscio/keys/` directory doesn't survive restarts. Without a persisted key, the SDK generates a **new keypair on every start**, which means a new DID and invalidated badges.\n\n### Key Persistence via Environment Variable\n\nOn first run the SDK generates a keypair and logs a capture hint:\n\n```\n╔══════════════════════════════════════════════════════════════════╗\n║  New agent identity generated — save key for persistence         ║\n╚══════════════════════════════════════════════════════════════════╝\n\n  Add to your secrets manager / .env:\n\n    CAPISCIO_AGENT_PRIVATE_KEY_JWK='{\"kty\":\"OKP\",\"crv\":\"Ed25519\",\"d\":\"...\",\"x\":\"...\",\"kid\":\"did:key:z6Mk...\"}'\n```\n\nCopy that value into your secrets manager and set it as an environment variable.\nOn subsequent starts the SDK recovers the same DID without generating a new identity.\n\n**Key resolution priority:** env var → local file → generate new.\n\n```yaml\n# docker-compose.yml\nservices:\n  langchain-agent:\n    image: my-langchain-agent\n    environment:\n      CAPISCIO_API_KEY: ${CAPISCIO_API_KEY}\n      CAPISCIO_AGENT_PRIVATE_KEY_JWK: ${AGENT_KEY_JWK}  # from secrets manager\n      CAPISCIO_DEV_MODE: \"false\"\n```\n\n```python\n# No code changes needed — CapiscioGuard.connect() reads env vars automatically\nsecured = CapiscioGuard.connect(mode=\"block\") | my_agent\n```\n\n\u003e **Warning:** Never bake private keys into container images. Inject them at runtime via environment variables or mounted secrets.\n\nSee the [Ephemeral Deployment Guide](https://docs.capisc.io/how-to/security/ephemeral-deployment/) for secrets manager examples and volume-mount alternatives.\n\n## Badge Token Extraction\n\n`CapiscioGuard` extracts the caller's badge token from (in priority order):\n\n1. **Context variable** — set by A2A server middleware via `set_capiscio_context()`\n2. **RunnableConfig** — `config={\"configurable\": {\"capiscio_badge\": token}}`\n3. **Input dict** — `{\"capiscio_badge\": token, ...}`\n\nFor A2A server integrations, set the context at the HTTP perimeter:\n\n```python\nfrom langchain_capiscio import CapiscioRequestContext, set_capiscio_context\n\nset_capiscio_context(CapiscioRequestContext(\n    badge_token=badge_jwt,\n    caller_did=\"did:web:caller.example.com\",\n))\n```\n\n## Trust Levels\n\n| Level | Name | Description |\n|-------|------|-------------|\n| 0 | Self-Signed (SS) | No external validation, `did:key` issuer |\n| 1 | Registered (REG) | Account registration with CapiscIO Registry |\n| 2 | Domain Validated (DV) | Domain ownership verified via DNS/HTTP challenge |\n| 3 | Organization Validated (OV) | Organization existence verified (DUNS, legal entity) |\n| 4 | Extended Validated (EV) | Manual review + legal agreement with CapiscIO |\n\n## API Reference\n\n### Guard\n\n- `CapiscioGuard.connect(api_key, *, mode, name, server_url, dev_mode, **kwargs)` — Connect to registry and return a ready-to-use guard (recommended)\n- `CapiscioGuard.from_env(mode, **kwargs)` — Alias for `connect()` (reads env vars)\n- `CapiscioGuard(*, identity, config, mode, api_key, name, server_url, connect_kwargs)` — Low-level constructor (keyword-only, lazy init on first invoke)\n- `CapiscioGuard.invoke(input, config)` — Verify badge and pass through to downstream\n- `CapiscioGuard.ainvoke(input, config)` — Async version\n\n### Callbacks\n\n- `CapiscioCallbackHandler(emitter, identity)` — Emit chain/tool lifecycle events to CapiscIO\n\n### Tool Enforcement\n\n- `CapiscioTool(tool, *, identity=None, config=None, mode=\"block\", api_key=None)` — Wrap a LangChain `Tool` with trust enforcement\n- `verify_badge` — `@tool`-decorated function for agent-driven badge verification\n- `resolve_agent_card` — `@tool`-decorated function for agent card resolution\n\n### LangGraph\n\n- `@capiscio_guard(mode, identity, config, api_key)` — Decorator for LangGraph function-based nodes\n\n### Context\n\n- `set_capiscio_context(ctx)` — Set request context (badge token, caller DID) for the current invocation\n- `get_capiscio_context()` — Retrieve current request context\n- `CapiscioRequestContext` — Dataclass holding badge token and caller DID\n\n## Documentation\n\n- [LangChain Integration Guide](https://docs.capisc.io/how-to/integrations/langchain/)\n- [Trust Badges Overview](https://docs.capisc.io/concepts/trust-badges/)\n- [A2A Protocol](https://github.com/google/A2A)\n\n## Development\n\n```bash\n# Clone repository\ngit clone https://github.com/capiscio/langchain-capiscio.git\ncd langchain-capiscio\n\n# Install development dependencies\npip install -e \".[dev]\"\n\n# Run tests\npytest -v\n\n# Run tests with coverage\npytest --cov=langchain_capiscio --cov-report=html\n```\n\n## License\n\nApache License 2.0\n\n## Contributing\n\nContributions welcome! Please open an issue or pull request on [GitHub](https://github.com/capiscio/langchain-capiscio).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcapiscio%2Flangchain-capiscio","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcapiscio%2Flangchain-capiscio","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcapiscio%2Flangchain-capiscio/lists"}