{"id":43358120,"url":"https://github.com/polos-dev/polos","last_synced_at":"2026-02-20T01:00:33.113Z","repository":{"id":334364291,"uuid":"1140867287","full_name":"polos-dev/polos","owner":"polos-dev","description":"AI agents write code, run commands, and delete files - autonomously. Polos gives them isolated sandboxes with built-in tools (shell, file system, web search), approval flows that reach you on various channels, and durable execution with automatic retries, prompt caching, and concurrency control. Agents get full power. Your systems stay safe.","archived":false,"fork":false,"pushed_at":"2026-02-16T07:09:22.000Z","size":2154,"stargazers_count":19,"open_issues_count":13,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-16T09:50:28.693Z","etag":null,"topics":["agent-orchestration","agentic-ai","ai-agents","ai-observability","developer-tools","durable-execution","human-in-the-loop","python","sandbox","typescript"],"latest_commit_sha":null,"homepage":"https://polos.dev","language":"TypeScript","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/polos-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":null,"dco":null,"cla":null}},"created_at":"2026-01-23T21:22:02.000Z","updated_at":"2026-02-16T07:09:25.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/polos-dev/polos","commit_stats":null,"previous_names":["polos-dev/polos"],"tags_count":36,"template":false,"template_full_name":null,"purl":"pkg:github/polos-dev/polos","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polos-dev%2Fpolos","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polos-dev%2Fpolos/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polos-dev%2Fpolos/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polos-dev%2Fpolos/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/polos-dev","download_url":"https://codeload.github.com/polos-dev/polos/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polos-dev%2Fpolos/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29637914,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-19T22:32:43.237Z","status":"ssl_error","status_checked_at":"2026-02-19T22:32:38.330Z","response_time":117,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["agent-orchestration","agentic-ai","ai-agents","ai-observability","developer-tools","durable-execution","human-in-the-loop","python","sandbox","typescript"],"created_at":"2026-02-02T03:18:08.767Z","updated_at":"2026-02-20T01:00:32.971Z","avatar_url":"https://github.com/polos-dev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\".github/assets/logo.png\" alt=\"Polos Logo\" width=\"200\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eDurable execution platform for AI agents\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/polos-dev/polos\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/stars/polos-dev/polos?style=social\" alt=\"GitHub Stars\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://docs.polos.dev\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/docs-polos.dev-0891B2?style=flat-square\u0026logo=read-the-docs\u0026logoColor=white\" alt=\"Documentation\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://discord.gg/ZAxHKMPwFG\"\u003e\n    \u003cimg src=\"https://img.shields.io/discord/1468012115859345611?color=2D6A4F\u0026label=community\u0026logo=discord\u0026logoColor=white\u0026style=flat-square\" alt=\"Discord\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  AI agents that survive crashes, resume mid-execution, and pause for human approval - with zero manual checkpointing, retry logic, or queue management.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cb\u003e⭐ Star us to support the project!\u003c/b\u003e\n\u003c/p\u003e\n\n---\n\nPolos is a durable execution platform for AI agents. It provides the stateful infrastructure required to run long-running, autonomous agents reliably at scale, including a **built-in event system** for agent coordination, so you don't need to bolt on Kafka or RabbitMQ.\n\nWrite it all in plain Python or TypeScript. No DAGs to define, no graph syntax to learn. Use loops, conditionals, and function calls naturally while Polos handles durability, reliability and scaling automatically.\n\n**Python**\n```python\nfrom polos import Agent, workflow, WorkflowContext\n\norder_agent = Agent(\n    provider=\"openai\",\n    model=\"gpt-4o\",\n    tools=[check_inventory, calculate_shipping]\n)\n\n@workflow(trigger_on_event=\"order/new\")\nasync def process_order(ctx: WorkflowContext, order: ProcessOrderInput):\n    # Agent validates order and checks inventory\n    validation = await ctx.step.agent_invoke_and_wait(\n        \"validate_order\",\n        order_agent.with_input(f\"Validate this order: {order}\")\n    )\n\n    if not validation.result.valid:\n        return ProcessOrderOutput(status=\"invalid\", reason=validation.result.reason)\n\n    # High-value orders need approval - suspend until human decides\n    if order.amount \u003e 1000:\n        decision = await ctx.step.suspend(\n            \"approval\",\n            data={\"id\": order.id, \"amount\": order.amount, \"items\": order.items}\n        )\n        if not decision.data[\"approved\"]:\n            return ProcessOrderOutput(status=\"rejected\")\n\n    # Charge customer (exactly-once guarantee)\n    payment = await ctx.step.run(\"charge\", charge_stripe, order)\n\n    # Wait for warehouse pickup (could be hours or days)\n    await ctx.step.wait_for_event(\"wait_pickup\", topic=f\"warehouse.pickup/{order.id}\")\n\n    # Send shipping notification\n    await ctx.step.run(\"notify\", send_shipping_email, order)\n\n    return ProcessOrderOutput(status=\"completed\", payment_id=payment.id)\n```\n\n**TypeScript**\n```typescript\nimport { defineAgent, defineWorkflow } from \"@polos/sdk\";\nimport { openai } from \"@ai-sdk/openai\";\nimport { z } from \"zod\";\n\nconst orderAgent = defineAgent({\n  id: \"order-agent\",\n  model: openai(\"gpt-4o\"),\n  tools: [checkInventory, calculateShipping],\n});\n\nconst processOrder = defineWorkflow(\n  {\n    id: \"process-order\",\n    triggerOnEvent: \"order/new\",\n    payloadSchema: z.object({\n      id: z.string(),\n      amount: z.number(),\n      items: z.array(z.string()),\n    }),\n  },\n  async (ctx, order) =\u003e {\n    // Agent validates order and checks inventory\n    const validation = await ctx.step.agentInvokeAndWait(\n      \"validate_order\",\n      orderAgent.withInput(`Validate this order: ${JSON.stringify(order)}`)\n    );\n\n    if (!validation.result.valid) {\n      return { status: \"invalid\", reason: validation.result.reason };\n    }\n\n    // High-value orders need approval - suspend until human decides\n    if (order.amount \u003e 1000) {\n      const decision = await ctx.step.suspend(\"approval\", {\n        data: { id: order.id, amount: order.amount, items: order.items },\n      });\n      if (!decision.data.approved) {\n        return { status: \"rejected\" };\n      }\n    }\n\n    // Charge customer (exactly-once guarantee)\n    const payment = await ctx.step.run(\"charge\", () =\u003e chargeStripe(order));\n\n    // Wait for warehouse pickup (could be hours or days)\n    await ctx.step.waitForEvent(\"wait_pickup\", {\n      topic: `warehouse.pickup/${order.id}`,\n    });\n\n    // Send shipping notification\n    await ctx.step.run(\"notify\", () =\u003e sendShippingEmail(order));\n\n    return { status: \"completed\", paymentId: payment.id };\n  }\n);\n```\n\nThis workflow survives crashes, resumes mid-execution, and pauses for approval - automatically.\n\n---\n\n## Architecture\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\".github/assets/architecture.png\" alt=\"Polos Architecture\" width=\"800\"\u003e\n\u003c/p\u003e\n\nPolos consists of three components:\n\n- **Orchestrator**: Manages execution state, handles retries, and coordinates workers\n- **Worker**: Runs your agents and workflows, connects to the orchestrator\n- **SDK**: Python and TypeScript libraries for defining agents, workflows, and tools\n\n---\n\n## See It In Action\n\nImagine a workflow that charges a customer, then pauses for a human fraud review. In most frameworks, a server restart during that 24-hour wait would lose the state - or worse, re-run the charge on reboot. Polos guarantees exactly-once durable execution.\n\n\u003cbr /\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cvideo src=\"https://github.com/user-attachments/assets/4607d70e-b078-4b8e-ad2e-a28bd1820a3f\" width=\"800\" controls\u003e\u003c/video\u003e\n\u003c/p\u003e\n\n**Timeline of what's happening:**\n\n1. `charge_stripe` runs → Polos checkpoints the execution result\n\n2. Workflow suspends for fraud review → Worker resources freed\n\n3. Worker 1 crashes during the wait\n\n4. Fraud team approves → Signal sent to orchestrator\n\n5. Worker 2 resumes on a different machine → Stripe is **not** called again, result replayed from the log guaranteeing exactly-once execution\n\n6. Confirmation email sent → workflow completes\n\nPolos handles failures, rescheduling, and checkpointing. You just focus on business logic.\n\n---\n\n## Why Polos?\n\n| Feature | Description |\n|---------|-------------|\n| **🧠 Durable State** | Your agent survives crashes with call stack and local variables intact. Step 18 of 20 fails? Resume from step 18. No wasted LLM calls. |\n| **🚦 Global Concurrency** | System-wide rate limiting with queues and concurrency keys. Prevent one rogue agent from exhausting your entire OpenAI quota. |\n| **🤝 Human-in-the-Loop** | Native support for pausing execution. Wait hours or days for user approval and resume with full context. Paused agents consume zero compute. |\n| **📡 Agent Handoffs** | Transactional memory for multi-agent systems. Pass reasoning history between specialized agents without context drift. |\n| **🔍 Decision-Level Observability** | Trace the reasoning behind every tool call, not just raw logs. See why your agent chose Tool B over Tool A. |\n| **⚡ Production Ready** | Automatic retries, exactly-once execution guarantees, OpenTelemetry tracing built-in. |\n\n\u003cbr /\u003e\n\n### Logic Belongs in Code, Not Configs\n\n**With Polos:**\n\n**Python**\n```python\n@workflow\nasync def process_order(ctx: WorkflowContext, order: ProcessOrderInput):\n    if order.amount \u003e 1000:\n        approved = await ctx.step.suspend(\"approval\", data=order.model_dump())\n        if not approved.data[\"ok\"]:\n            return {\"status\": \"rejected\"}\n\n    await ctx.step.run(\"charge\", charge_stripe, order)\n    await ctx.step.run(\"notify\", send_email, order)\n```\n\n**TypeScript**\n```typescript\nconst processOrder = defineWorkflow({ id: \"process-order\" }, async (ctx, order) =\u003e {\n  if (order.amount \u003e 1000) {\n    const approved = await ctx.step.suspend(\"approval\", { data: order });\n    if (!approved.data.ok) {\n      return { status: \"rejected\" };\n    }\n  }\n\n  await ctx.step.run(\"charge\", () =\u003e chargeStripe(order));\n  await ctx.step.run(\"notify\", () =\u003e sendEmail(order));\n});\n```\n\n**Other platforms:**\n```python\ndag = DAG(\n    nodes=[\n        Node(\"check_amount\", CheckAmount),\n        Node(\"approval\", HumanApproval),\n        Node(\"charge\", ChargeStripe),\n        Node(\"notify\", SendEmail),\n    ],\n    edges=[\n        (\"check_amount\", \"approval\", condition=\"amount \u003e 1000\"),\n        (\"check_amount\", \"charge\", condition=\"amount \u003c= 1000\"),\n        (\"approval\", \"charge\", condition=\"approved\"),\n        (\"charge\", \"notify\"),\n    ]\n)\n```\n\nNo DAGs. No graph syntax. Just Python or TypeScript.\n\n---\n\n## Quick Start\n\n### 1. Install Polos Server\n\n```bash\ncurl -fsSL https://install.polos.dev/install.sh | bash\npolos-server start\n```\n\nCopy the project ID displayed when you start the server. You'll need it in the next steps.\n\n### 2. Install the SDK\n\n**Python**\n```bash\npip install polos-sdk\n```\n\n**TypeScript**\n```bash\nnpm install @polos/sdk\n```\n\n### 3. Create your first agent\n\n**Python**\n```python\n# worker.py\nfrom polos import Agent, Worker, PolosClient\n\nweather_agent = Agent(\n    id=\"weather_agent\",\n    provider=\"openai\",\n    model=\"gpt-4o-mini\",\n    system_prompt=\"You are a helpful weather assistant.\",\n    tools=[get_weather],\n)\n\nclient = PolosClient(project_id=\"your-project-id\")\nworker = Worker(client=client, agents=[weather_agent])\n\nif __name__ == \"__main__\":\n    import asyncio\n    asyncio.run(worker.run())\n```\n\n**TypeScript**\n```typescript\n// worker.ts\nimport { defineAgent, PolosClient, Worker } from \"@polos/sdk\";\nimport { openai } from \"@ai-sdk/openai\";\n\nconst weatherAgent = defineAgent({\n  id: \"weather-agent\",\n  model: openai(\"gpt-4o-mini\"),\n  systemPrompt: \"You are a helpful weather assistant.\",\n  tools: [getWeather],\n});\n\nconst client = new PolosClient({ projectId: \"your-project-id\" });\nconst worker = new Worker({ client, agents: [weatherAgent] });\n\nawait worker.run();\n```\n\n### 4. Run your agent\n\n**Python**\n```bash\n# Terminal 1: Start the worker\npython worker.py\n\n# Terminal 2: Invoke the agent\npython main.py\n```\n\n**TypeScript**\n```bash\n# Terminal 1: Start the worker\nnpx tsx worker.ts\n\n# Terminal 2: Invoke the agent\nnpx tsx main.ts\n```\n\n### 5. See it in action\n\nOpen the Polos UI to see your agent's execution trace, tool calls, and reasoning:\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\".github/assets/observability.png\" alt=\"Polos Observability UI\" width=\"800\"\u003e\n\u003c/p\u003e\n\n📖 **[Full Quick Start Guide →](https://docs.polos.dev/quickstart)**\n\n---\n\n## Examples\n\n### Agents\n\n| Example | Python | TypeScript | Description |\n|---------|--------|------------|-------------|\n| Agent with tools | [Python](./python-examples/01-agent-with-tools) | [TypeScript](./typescript-examples/01-agent-with-tools) | Simple agent with tool calling |\n| Structured Output | [Python](./python-examples/02-structured-output) | [TypeScript](./typescript-examples/02-structured-output) | Agent with structured model responses |\n| Streaming | [Python](./python-examples/03-agent-streaming) | [TypeScript](./typescript-examples/03-agent-streaming) | Real-time streaming responses |\n| Conversational Chat | [Python](./python-examples/04-conversational-chat) | [TypeScript](./typescript-examples/04-conversational-chat) | Multi-turn conversations with memory |\n| Thinking Agent | [Python](./python-examples/05-thinking-agent) | [TypeScript](./typescript-examples/05-thinking-agent) | Chain-of-thought reasoning |\n| Guardrails | [Python](./python-examples/06-guardrails) | [TypeScript](./typescript-examples/06-guardrails) | Input/output validation |\n| Multi-Agent Coordination | [Python](./python-examples/14-router-coordinator) | [TypeScript](./typescript-examples/14-router-coordinator) | Workflow orchestrating multiple agents |\n| Order Processing | [Python](./python-examples/17-order-processing) | [TypeScript](./typescript-examples/17-order-processing) | Human-in-the-loop fraud review |\n| Sandbox Tools | [Python](./python-examples/18-sandbox-tools) | [TypeScript](./typescript-examples/18-sandbox-tools) | Code execution in an isolated Docker container |\n| Exec Security | [Python](./python-examples/19-exec-security) | [TypeScript](./typescript-examples/19-exec-security) | Allowlist-based command approval |\n| Web Search Agent | [Python](./python-examples/20-web-search-agent) | [TypeScript](./typescript-examples/20-web-search-agent) | Research agent with Tavily web search |\n| Local Sandbox | [Python](./python-examples/21-local-sandbox) | [TypeScript](./typescript-examples/21-local-sandbox) | Sandbox tools running on the host machine |\n\n### Workflows\n\n| Example | Python | TypeScript | Description |\n|---------|--------|------------|-------------|\n| Workflow Basics | [Python](./python-examples/08-workflow-basics) | [TypeScript](./typescript-examples/08-workflow-basics) | Core workflow patterns |\n| Suspend/Resume | [Python](./python-examples/09-suspend-resume) | [TypeScript](./typescript-examples/09-suspend-resume) | Human-in-the-loop approvals |\n| State Persistence | [Python](./python-examples/10-state-persistence) | [TypeScript](./typescript-examples/10-state-persistence) | Durable state across executions |\n| Error Handling | [Python](./python-examples/11-error-handling) | [TypeScript](./typescript-examples/11-error-handling) | Retry, fallback, compensation patterns |\n| Queues \u0026 Concurrency | [Python](./python-examples/12-shared-queues) | [TypeScript](./typescript-examples/12-shared-queues) | Rate limiting and concurrency control |\n| Parallel Execution | [Python](./python-examples/13-parallel-review) | [TypeScript](./typescript-examples/13-parallel-review) | Fan-out/fan-in patterns |\n\n### Events \u0026 Scheduling\n\n| Example | Python | TypeScript | Description |\n|---------|--------|------------|-------------|\n| Event-Triggered | [Python](./python-examples/15-event-triggered) | [TypeScript](./typescript-examples/15-event-triggered) | Pub/sub event-driven workflows |\n| Scheduled Workflows | [Python](./python-examples/16-scheduled-workflow) | [TypeScript](./typescript-examples/16-scheduled-workflow) | Cron-based scheduling |\n\n### Human-in-the-Loop\n\n| Example | Python | TypeScript | Description |\n|---------|--------|------------|-------------|\n| Approval Page | [Python](./python-examples/22-approval-page) | [TypeScript](./typescript-examples/22-approval-page) | Web UI for workflow approval with suspend/resume |\n\n---\n\n## Under the Hood\n\nPolos captures the result of every side effect - tool calls, API responses, time delays as a durable log.\nIf your process dies, Polos replays the workflow from the log, returning previously-recorded results instead of re-executing them.\nYour agent’s exact local variables and call stack are restored in milliseconds.\n\n**Completed steps are never re-executed - so you never pay for an LLM call twice.**\n\n---\n\n## Documentation\n\nFor detailed documentation, visit **[docs.polos.dev](https://docs.polos.dev)**\n\n- 📖 [Quick Start Guide](https://docs.polos.dev/quickstart)\n- 🤖 [Building Agents](https://docs.polos.dev/agents/overview)\n- ⚙️ [Workflow Patterns](https://docs.polos.dev/workflows/overview)\n- 📡 [Events](https://docs.polos.dev/workflows/event-triggered-workflows)\n- ⏰ [Scheduling](https://docs.polos.dev/workflows/scheduled-workflows)\n- 🔍 [Observability](https://docs.polos.dev/observability/tracing)\n\n---\n\n## Community\n\nJoin our community to get help, share ideas, and stay updated:\n\n- ⭐ [Star us on GitHub](https://github.com/polos-dev/polos)\n- 💬 [Join our Discord](https://discord.gg/ZAxHKMPwFG)\n- 📖 [Read the Docs](https://docs.polos.dev)\n\n---\n\n## Contributing\n\nWe welcome contributions! Whether it's bug reports, feature requests, documentation improvements, or code contributions.\n\n- 🐛 [Report Issues](https://github.com/polos-dev/polos/issues)\n- 💡 [Feature Requests](https://github.com/polos-dev/polos/issues)\n- 📖 [Contributing Guide](CONTRIBUTING.md)\n\n---\n\n## License\n\nPolos is [Apache 2.0 licensed](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpolos-dev%2Fpolos","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpolos-dev%2Fpolos","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpolos-dev%2Fpolos/lists"}