{"id":46912036,"url":"https://github.com/agentcontrol/agent-control","last_synced_at":"2026-04-22T04:00:45.991Z","repository":{"id":343594283,"uuid":"1146326147","full_name":"agentcontrol/agent-control","owner":"agentcontrol","description":"Centralized agent control plane for governing runtime agent behavior at scale. Configurable, extensible, and production-ready. ","archived":false,"fork":false,"pushed_at":"2026-04-21T23:03:35.000Z","size":5569,"stargazers_count":215,"open_issues_count":39,"forks_count":27,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-04-22T01:13:18.906Z","etag":null,"topics":["agentic-workflow","ai-safety","guardrails","llm","runtime-guardrails"],"latest_commit_sha":null,"homepage":"https://agentcontrol.dev","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/agentcontrol.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-30T23:23:24.000Z","updated_at":"2026-04-21T22:29:57.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/agentcontrol/agent-control","commit_stats":null,"previous_names":["agentcontrol/agent-control"],"tags_count":45,"template":false,"template_full_name":null,"purl":"pkg:github/agentcontrol/agent-control","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentcontrol%2Fagent-control","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentcontrol%2Fagent-control/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentcontrol%2Fagent-control/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentcontrol%2Fagent-control/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/agentcontrol","download_url":"https://codeload.github.com/agentcontrol/agent-control/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentcontrol%2Fagent-control/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32120402,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-22T00:31:26.853Z","status":"online","status_checked_at":"2026-04-22T02:00:05.693Z","response_time":58,"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":["agentic-workflow","ai-safety","guardrails","llm","runtime-guardrails"],"created_at":"2026-03-11T02:03:43.983Z","updated_at":"2026-04-22T04:00:45.985Z","avatar_url":"https://github.com/agentcontrol.png","language":"Python","funding_links":[],"categories":["*Ops for AI"],"sub_categories":["LLMOps"],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg\n    src=\"docs/images/AgentControl-logo-light.svg#gh-light-mode-only\"\n    alt=\"Agent Control Logo (light)\"\n    width=\"120\"\n  /\u003e\n  \u003cimg\n    src=\"docs/images/AgentControl-logo-dark.svg#gh-dark-mode-only\"\n    alt=\"Agent Control Logo (dark)\"\n    width=\"120\"\n  /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eAgent Control\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://opensource.org/licenses/Apache-2.0\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-Apache_2.0-blue.svg\" alt=\"License\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.python.org/downloads/\"\u003e\u003cimg src=\"https://img.shields.io/badge/python-3.12+-blue.svg\" alt=\"Python 3.12+\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://pypi.org/project/agent-control-sdk/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/agent-control-sdk.svg\" alt=\"PyPI version\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/agent-control\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/agent-control.svg\" alt=\"npm version\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/agentcontrol/agent-control/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/agentcontrol/agent-control/actions/workflows/ci.yml/badge.svg\" alt=\"CI\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://codecov.io/gh/agentcontrol/agent-control\"\u003e\u003cimg src=\"https://codecov.io/gh/agentcontrol/agent-control/branch/main/graph/badge.svg\" alt=\"codecov\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://agentcontrol.dev\"\u003eAgent Control Website\u003c/a\u003e |\n  \u003ca href=\"https://docs.agentcontrol.dev/\"\u003eDocs\u003c/a\u003e |\n  \u003ca href=\"https://docs.agentcontrol.dev/core/quickstart\"\u003eQuickstart\u003c/a\u003e |\n  \u003ca href=\"examples/README.md\"\u003eExamples\u003c/a\u003e |\n  \u003ca href=\"https://join.slack.com/t/agentcontrol/shared_invite/zt-3se2g6d68-iGmNdRfGcD31cZ0vELMPxw\"\u003eSlack\u003c/a\u003e\n\u003c/p\u003e\n\nEnforce runtime guardrails through a centralized control layer—configure once and apply across all agents. Agent Control evaluates inputs and outputs against configurable rules to block prompt injections, PII leakage, and other risks without changing your agent’s code.\n\n![Agent Control Overview](docs/images/AgentControlDiagram.png)\n\n- **Centralized safety** - define controls once, apply across agents, update without redeploying\n- **Runtime configuration** - manage controls via API or UI, no code changes needed\n- **Pluggable evaluators** - built-in (regex, list, JSON, SQL) or bring your own\n- **Framework support** - works with LangChain, CrewAI, Google ADK, AWS Strands, and more\n\n## Quick Start\n\nPrerequisites: Docker and Python 3.12+.\n\nQuick start flow:\n\n```\nStart server\n  ↓\nInstall SDK\n  ↓\nWrap a model or tool call with @control() and register your agent\n  ↓\nCreate controls (UI or SDK/API)\n```\n\n### 1. Start the server\n\nNo repo clone required:\n\n```bash\ncurl -L https://raw.githubusercontent.com/agentcontrol/agent-control/refs/heads/main/docker-compose.yml | docker compose -f - up -d\n```\n\nThis starts PostgreSQL and Agent Control at `http://localhost:8000`, including\nthe UI/dashboard.  \n\nNote: This starts server without API keys configured which is dangerous for any real world usage.  \n\nSet appropirate env vars to override defaults like:\n * Exposed ports\n * Agent and admin API keys\n * Postgres DB Password\n\n```bash\nexport AGENT_CONTROL_SERVER_HOST_PORT=18000\nexport AGENT_CONTROL_DB_HOST_PORT=15432\nexport AGENT_CONTROL_API_KEY_ENABLED=true\nexport AGENT_CONTROL_API_KEYS=\"agent-api-key\"\nexport AGENT_CONTROL_ADMIN_API_KEYS=\"admin-api-key\"\nexport AGENT_CONTROL_POSTGRES_PASSWORD=\"postgres-password\"\n\ncurl -L https://raw.githubusercontent.com/agentcontrol/agent-control/refs/heads/main/docker-compose.yml | docker compose -f - up -d\n```\n\nVerify it is up:\n\n```bash\ncurl http://localhost:8000/health\n```\n\nIf you changed `AGENT_CONTROL_SERVER_HOST_PORT`, use that port in the health check URL.\n\n### 2. Install the SDK\n\nRun this in your agent project directory.\n\nPython:\n\n```bash\nuv venv\nsource .venv/bin/activate\nuv pip install agent-control-sdk\n```\n\nTypeScript:\n\n- See the [TypeScript SDK example](examples/typescript_sdk/README.md).\n\n### 3. Wrap a call and register your agent\n\n```python\n# my_agent.py\n\nimport asyncio\nimport agent_control\nfrom agent_control import control, ControlViolationError\n\n# Protect any function (like LLM calls)\n\n@control()\nasync def chat(message: str) -\u003e str:\n    # In production: response = await LLM.ainvoke(message)\n    # For demo: simulate LLM that might leak sensitive data\n    if \"test\" in message.lower():\n        return \"Your SSN is 123-45-6789\"  # Will be blocked!\n    return f\"Echo: {message}\"\n\n# Initialize your agent\n\nagent_control.init(\n    agent_name=\"awesome_bot_3000\",  # Unique name\n    agent_description=\"My Chatbot\",\n)\n\nasync def main():\n    try:\n        print(await chat(\"test\"))  # ❌ Blocked\n    except ControlViolationError as e:\n        print(f\"❌ Blocked: {e.control_name}\")\n    finally:\n        await agent_control.ashutdown()\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n```\n\nUse `agent_control.shutdown()` or `await agent_control.ashutdown()` before process exit so short-lived scripts flush pending observability events cleanly.\n\nExternal integrations can register a sink for the same finalized\ncontrol-event payloads:\n\n```python\nfrom agent_control import (\n    register_control_event_sink,\n    unregister_control_event_sink,\n)\nfrom agent_control_telemetry import BaseControlEventSink, SinkResult\n\n\nclass MyControlEventSink(BaseControlEventSink):\n    def write_events(self, events):\n        for event in events:\n            forward_to_external_system(event.model_dump(mode=\"json\"))\n        return SinkResult(accepted=len(events), dropped=0)\n\n\nsink = MyControlEventSink()\nregister_control_event_sink(sink)\n\n# Later, when tearing down the integration:\nunregister_control_event_sink(sink)\n```\n\nRegistered sinks receive the same local, server, and merged control-execution\nevents the SDK emits through its normal event-construction flow. If no\nexternal sink is registered, the default OSS delivery path is unchanged. If one\nor more sinks are registered, they replace the default built-in delivery path.\n\nNext, create a control in Step 4, then run the setup and agent scripts in\norder to see blocking in action.\n\n### 4. Add controls\n\nThis example adds the control with a small SDK setup script. You can also\ncreate and attach controls through the UI or direct API calls.\n\nMinimal SDK example (assumes the server is running at `http://localhost:8000`\nand uses the same `agent_name` as Step 3):\n\n```python\n# setup.py - Run once to configure agent controls\n\nimport asyncio\nfrom datetime import datetime, UTC\nfrom agent_control import AgentControlClient, controls, agents\nfrom agent_control_models import Agent\n\nasync def setup():\n    async with AgentControlClient() as client:  # Defaults to localhost:8000\n        # 1. Register agent first\n        agent = Agent(\n            agent_name=\"awesome_bot_3000\",\n            agent_description=\"My Chatbot\",\n            agent_created_at=datetime.now(UTC).isoformat(),\n        )\n        await agents.register_agent(client, agent, steps=[])\n\n        # 2. Create control (blocks SSN patterns in output)\n        control = await controls.create_control(\n            client,\n            name=\"block-ssn\",\n            data={\n                \"enabled\": True,\n                \"execution\": \"server\",\n                \"scope\": {\"stages\": [\"post\"]},\n                \"condition\": {\n                    \"selector\": {\"path\": \"output\"},\n                    \"evaluator\": {\n                        \"name\": \"regex\",\n                        \"config\": {\"pattern\": r\"\\b\\d{3}-\\d{2}-\\d{4}\\b\"},\n                    },\n                },\n                \"action\": {\"decision\": \"deny\"},\n            },\n        )\n\n        # 3. Associate control directly with agent\n        await agents.add_agent_control(\n            client,\n            agent_name=agent.agent_name,\n            control_id=control[\"control_id\"],\n        )\n\n        print(\"✅ Setup complete!\")\n        print(f\"   Control ID: {control['control_id']}\")\n\nasyncio.run(setup())\n```\n\nControls now store leaf `selector` and `evaluator` definitions under `condition`, which also enables composite `and`, `or`, and `not` trees.\n\n**Tip**: If you prefer a visual flow, use the UI instead - see the [UI Quickstart](https://docs.agentcontrol.dev/core/ui-quickstart).\n\nRun both scripts in order:\n\n```bash\nuv run setup.py\nuv run my_agent.py\n```\n\nExpected output:\n\n```text\nBlocked: block-ssn-demo\n```\n\n## Examples:\n\nExplore working examples for popular frameworks.\n\n- [Customer Support Agent](examples/customer_support_agent/) - PII protection, prompt injection defense, and tool controls\n- [Steer Action Demo](examples/steer_action_demo/) - observe, deny, and steer decisions in one workflow\n- [LangChain](examples/langchain/) - protect a SQL agent from dangerous queries\n- [CrewAI](examples/crewai/) - combine Agent Control with CrewAI guardrails\n- [AWS Strands](examples/strands_agents/) - protect Strands workflows and tool calls\n- [Google ADK Decorator](examples/google_adk_decorator/) - add controls with `@control()`\n\n## How It Works\n\n![Agent Control Architecture](docs/images/Architecture.png)\n\nAgent Control evaluates agent inputs and outputs against controls you configure at runtime. That keeps guardrail logic out of prompt code and tool code, while still letting teams update protections centrally.\n\nRead more about [Controls](https://docs.agentcontrol.dev/concepts/controls) and Learn how controls, selectors, and evaluators work\n\n## Performance\n\n| Endpoint         | Scenario                      | RPS     | p50      | p99      |\n| ---------------- | ----------------------------- | ------- | -------- | -------- |\n| Agent init       | Agent with 3 tool steps       | 509     | 19 ms    | 54 ms    |\n| Evaluation       | 1 control, 500-char content   | 437     | 36 ms    | 61 ms    |\n| Evaluation       | 10 controls, 500-char content | 349     | 35 ms    | 66 ms    |\n| Evaluation       | 50 controls, 500-char content | 199     | 63 ms    | 91 ms    |\n| Controls refresh | 5-50 controls per agent       | 273-392 | 20-27 ms | 27-61 ms |\n\n- Agent init handles create and update as an upsert.\n- Local laptop benchmarks are directional, not production sizing guidance.\n\n_Benchmarked on Apple M5 (16 GB RAM), Docker Compose (`postgres:16` + `agent-control`)._\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines, development workflow, and quality checks.\n\n## License\n\nApache 2.0. See [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagentcontrol%2Fagent-control","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fagentcontrol%2Fagent-control","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagentcontrol%2Fagent-control/lists"}