Skip to content
Back to search

agentor

Open source version of Claude Managed Agents. Fastest way to build and deploy reliable AI agents, MCP tools and agent-to-agent.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/celestoai--agentor/badge.svg)](/listings/celestoai--agentor)

HTML

<a href="/listings/celestoai--agentor"><img src="/api/listings/celestoai--agentor/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Installation

The recommended method of installing `agentor` is with pip from PyPI.

pip install agentor

This installs the v0.1.0 line, built on Agentor's own agent engine — durable, forkable runs included.

Tools with heavy or vendor-specific dependencies ship as extras, so the base install stays small:

pip install "agentor[google]"   # GmailTool, CalendarTool
pip install "agentor[all]"      # every optional tool

Available extras: `google`, `exa`, `git`, `github`, `slack`, `postgres`, `scrapegraph`, `all`.

<details> <summary>More ways...</summary>

You can also install the latest bleeding edge version (could be unstable) of `agentor`, should you feel motivated enough, as follows:

pip install git+https://github.com/celestoai/agentor@main

</details>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 342 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <picture>
  3. <img src="https://raw.githubusercontent.com/CelestoAI/agentor/main/assets/CelestoAI.png" alt="project logo" width="500px"/>
  4. </picture>
  5. </p>
  6. <div align="center">
  7. [![PyPI version](https://img.shields.io/pypi/v/agentor.svg?color=brightgreen&label=PyPI&style=flat)](https://pypi.org/project/agentor/)
  8. [![Tests](https://github.com/CelestoAI/agentor/actions/workflows/test.yml/badge.svg)](https://github.com/CelestoAI/agentor/actions/workflows/test.yml)
  9. ![PyPI - Downloads](https://img.shields.io/pypi/dm/agentor)
  10. [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-yellow?style=flat)](https://opensource.org/licenses/Apache-2.0)
  11. <a href="https://discord.gg/KNb5UkrAmm">
  12. <img src="https://img.shields.io/static/v1?label=Chat%20on&message=Discord&color=blue&logo=Discord&style=flat-square" alt="Discord">
  13. </a>
  14. </div>
  15. <p align="center">
  16. Fastest way to build and deploy long-running AI agents—with durability, observability, and security.
  17. </p>
  18. <p align="center">
  19. <a href="https://docs.celesto.ai">Docs</a> |
  20. <a href="https://github.com/CelestoAI/agentor/tree/main/examples">Examples</a>
  21. </p>
  22. ## Features
  23. | Feature | Description | Docs
  24. |---------------------------|------------------------------------------|-----------------------|
  25. | 🚀 MCP & tool security | The only **full FastAPI compatible** MCP Server with decorator API | [Link](https://docs.celesto.ai/agentor/tools/LiteMCP)
  26. | 🦾 Agent-to-agent | Multi-agent communication | [Link](https://docs.celesto.ai/agentor/agent-to-agent)
  27. | 📊 Observability | Agent tracing and monitoring | [Link](https://celesto.ai)
  28. | 💾 Durable runs | Persist, resume, and fork agent runs | [Durable runs docs](https://docs.celesto.ai/agentor)
  29. | 🔍 Tool Search API | Reduced tool context bloat | [Link](https://docs.celesto.ai/agentor/tools/tool-search)
  30. ## 🚅 Quick Start
  31. ### Installation
  32. The recommended method of installing `agentor` is with pip from PyPI.
  33. ```bash
  34. pip install agentor
  35. ```
  36. This installs the v0.1.0 line, built on Agentor's own agent engine — durable,
  37. forkable runs included.
  38. Tools with heavy or vendor-specific dependencies ship as extras, so the base
  39. install stays small:
  40. ```bash
  41. pip install "agentor[google]" # GmailTool, CalendarTool
  42. pip install "agentor[all]" # every optional tool
  43. ```
  44. Available extras: `google`, `exa`, `git`, `github`, `slack`, `postgres`, `scrapegraph`, `all`.
  45. <details>
  46. <summary>More ways...</summary>
  47. You can also install the latest bleeding edge version (could be unstable) of `agentor`, should you feel motivated enough, as follows:
  48. ```bash
  49. pip install git+https://github.com/celestoai/agentor@main
  50. ```
  51. </details>
  52. ## Build and Serve an Agent
  53. Build an Agent, connect external tools or MCP Server and serve as an API in just a few lines of code:
  54. ```python
  55. from agentor.tools import GetWeatherTool
  56. from agentor import Agentor
  57. agent = Agentor(
  58. name="Weather Agent",
  59. model="gpt-5-mini", # Use any LLM provider - gemini/gemini-2.5-pro or anthropic/claude-3.5
  60. tools=[GetWeatherTool()]
  61. )
  62. result = agent.run("What is the weather in London?") # Run the Agent
  63. print(result)
  64. # Serve Agent with a single line of code
  65. agent.serve()
  66. ```
  67. ### Any OpenAI-compatible provider
  68. Point `base_url` at any provider that speaks OpenAI's `/chat/completions` — OpenRouter,
  69. Groq, Together, Fireworks, DeepSeek, vLLM, Ollama, or Anthropic's and Gemini's compatible
  70. endpoints — with no extra dependency:
  71. ```python
  72. agent = Agentor(
  73. name="Assistant",
  74. model="openrouter/auto",
  75. base_url="https://openrouter.ai/api/v1",
  76. api_key=os.environ["OPENROUTER_API_KEY"],
  77. )
  78. ```
  79. Run the following command to query the Agent server:
  80. ```bash
  81. curl -X 'POST' \
  82. 'http://localhost:8000/chat' \
  83. -H 'accept: application/json' \
  84. -H 'Content-Type: application/json' \
  85. -d '{
  86. "input": "What is the weather in London?"
  87. }'
  88. ```
  89. `agent.serve()` gives you an ordinary ASGI app, so host it wherever you already
  90. run Python services.
  91. ## Durable Runs
  92. Give the agent a store and every run becomes an append-only event log that
  93. survives process death. Resume an interrupted run, or fork any persisted run —
  94. even a completed one — into a new, independent run that keeps the full trace,
  95. the model's reasoning included when the provider returns it:
  96. ```python
  97. from agentor import Agentor
  98. from agentor.engine.store import FileStore
  99. agent = Agentor(name="Assistant", model="gpt-5-mini", store=FileStore("runs"))
  100. result = agent.run("Draft a launch plan") # persisted under result.run_id
  101. # Interrupted mid-run? agent.resume(result.run_id) picks up where it left off.
  102. fork = agent.fork(result.run_id, "Make it punchier") # fork.run_id is a new run; parent untouched
  103. ```
  104. `fork` and `resume` have async twins, `afork` and `aresume`.
  105. ## Tracing
  106. Tracing is **off unless you ask for it**. A trace carries prompts, tool arguments, tool
  107. results, and the model's reasoning when a provider returns it — so nothing leaves your
  108. process by default.
  109. Turn it on for an agent:
  110. ```python
  111. agent = Agentor(name="Assistant", enable_tracing=True) # needs CELESTO_API_KEY
  112. ```
  113. Or decide per run:
  114. ```python
  115. agent.run("public question")
  116. agent.run("contains customer data", tracing=False) # this run sends nothing
  117. agent.run("debug this", tracing=True) # trace just this one
  118. ```
  119. `tracing=` is accepted by `run`, `arun`, `chat` and `stream_chat`. View traces at
  120. [celesto.ai/observe](https://celesto.ai/observe).
  121. ## Agent Skills
  122. Skills are folders of instructions, scripts, and resources that Claude loads dynamically to improve performance on specialized tasks.
  123. Agent Skills help agents pull just the right context from simple Markdown files. The agent first sees only a skill’s name and short description. When the task matches, it loads the rest of `SKILL.md`, follows the steps, and can call a shell environment to run the commands the skill points to.
  124. - **Starts light**: discover skills by name/description only
  125. - **Loads on demand**: pull full instructions from `SKILL.md` when relevant
  126. - **Executes safely**: run skill-driven commands in an isolated shell
  127. Skill layout example:
  128. ```
  129. example-skill/
  130. ├── SKILL.md # required instructions + metadata
  131. ├── scripts/ # optional helpers the agent can call
  132. ├── assets/ # optional templates/resources
  133. └── references/ # optional docs or checklists
  134. ```
  135. Using a skill to create a GIF:
  136. ```python
  137. from agentor.tools import ShellTool
  138. from agentor import Agentor
  139. agent = Agentor(
  140. name="Assistant",
  141. model="gemini/gemini-3-flash-preview",
  142. instructions="Your job is to create GIFs. Lean on the shell tool and any available skills.",
  143. skills=[".skills/slack-gif-creator"],
  144. tools=[ShellTool()],
  145. )
  146. async for chunk in await agent.chat("produce a cat gif", stream=True):
  147. print(chunk)
  148. ```
  149. ## Create an Agent from Markdown
  150. Bootstrap an Agent directly from a markdown file with metadata for name, tools, model, and temperature:
  151. ```markdown
  152. ---
  153. name: WeatherBot
  154. tools: [get_weather]
  155. model: gpt-4o-mini
  156. temperature: 0.3
  157. ---
  158. You are a concise weather assistant.
  159. ```
  160. Load it with:
  161. ```python
  162. from agentor import Agentor
  163. agent = Agentor.from_md("agent.md")
  164. result = agent.run("Weather in Paris?")
  165. ```
  166. ## Build a custom MCP Server with LiteMCP
  167. Agentor enables you to build a custom [MCP Server](https://modelcontextprotocol.io) using LiteMCP. You can run it inside a FastAPI application or as a standalone MCP server.
  168. Agentor uses the official MCP Python SDK 2.3 or newer within the 2.x line.
  169. FastMCP is not an Agentor dependency; the LiteMCP decorator API is unchanged.
  170. ```python
  171. from agentor.mcp import LiteMCP, get_token
  172. mcp = LiteMCP(name="my-server", version="1.0.0")
  173. @mcp.tool(description="Get weather for a given location")
  174. def get_weather(location: str) -> str:
  175. # *********** Control authentication ***********
  176. token = get_token()
  177. if token != "SOME_SECRET":
  178. return "Not authorized"
  179. return f"Weather in {location}: Sunny, 72°F"
  180. mcp.serve()
  181. ```
  182. ### LiteMCP vs FastMCP
  183. **Key Difference:** LiteMCP is a native ASGI app that integrates directly with FastAPI using standard patterns. FastMCP requires mounting as a sub-application, diverging from standard FastAPI primitives.
  184. | Feature | LiteMCP | FastMCP |
  185. |---------|---------|---------|
  186. | Integration | Native ASGI | Requires mounting |
  187. | FastAPI Patterns | ✅ Standard | ⚠️ Diverges |
  188. | Built-in CORS | ✅ | ❌ |
  189. | Custom Methods | ✅ Full | ⚠️ Limited |
  190. | With Existing Backend | ✅ Easy | ⚠️ Complex |
  191. 📖 [Learn more](https://docs.celesto.ai/agentor/tools/LiteMCP)
  192. ## Connect an Agent to an MCP Server
  193. Use `MCPServer` for a remote server that supports Streamable HTTP. Agentor
  194. discovers its tools, including paginated results, and closes the connection
  195. after the run:
  196. ```python
  197. from agentor import Agentor
  198. from agentor.mcp import MCPServer
  199. agent = Agentor(
  200. name="Assistant",
  201. model="gpt-5-mini",
  202. tools=[MCPServer(url="https://your-server.example/mcp")],
  203. )
  204. ```
  205. Hosts that supply their own HTTP transport can pass `http_client_factory` to
  206. `MCPServer`. The factory receives `headers` and `timeout` keyword arguments and
  207. must return a new `httpx2.AsyncClient`. Agentor owns that client's lifecycle,
  208. closing it when connection setup fails or the MCP connection closes.
  209. ### Search the web through MCP
  210. The [Parallel Search example](examples/parallel_search.md) connects an agent to
  211. web search and page extraction without a Parallel API key. It also includes a
  212. tools-only mode that runs without model credentials:
  213. ```bash
  214. uv run python examples/parallel_search.py --tools-only "Agentor durable agent runs"
  215. ```
  216. ## Agent-to-Agent (A2A) Protocol
  217. The A2A Protocol defines standard specifications for agent communication and message formatting, enabling seamless interoperability between different AI agents.
  218. **Key Features:**
  219. - **Standard Communication**: JSON-RPC based messaging with support for both streaming and non-streaming responses
  220. - **Agent Discovery**: Automatic agent card generation at `/.well-known/agent-card.json` describing agent capabilities, skills, and endpoints
  221. - **Rich Interactions**: Built-in support for tasks, status updates, and artifact sharing between agents
  222. Agentor makes it easy to serve any agent as an A2A protocol.
  223. ```python
  224. from agentor import Agentor
  225. agent = Agentor(
  226. name="Weather Agent",
  227. model="gpt-5-mini",
  228. tools=["get_weather"],
  229. )
  230. # Serve agent with A2A protocol enabled automatically
  231. agent.serve(port=8000)
  232. # Agent card available at: http://localhost:8000/.well-known/agent-card.json
  233. ```
  234. Any agent served with `agent.serve()` automatically becomes A2A-compatible with standardized endpoints for message sending, streaming, and task management.
  235. 📖 [Learn more](https://docs.celesto.ai/agentor/agent-to-agent)
  236. ## 🤝 Contributing
  237. We'd love your help making Agentor even better! Please read our [Contributing Guidelines](.github/CONTRIBUTING.md) and [Code of Conduct](.github/CODE_OF_CONDUCT.md).
  238. ## 📄 License
  239. Apache 2.0 License - see [LICENSE](LICENSE) for details.
  240. ---
  241. <div align="center">
  242. Built with 🧡 in London by <a href="https://celesto.ai">Celesto AI</a>
  243. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.