Before diving into the API, it helps to understand how the pieces fit together.
The Mental Model
| Component | What it does | When you need it |
|---|
| Agent | LLM-powered reasoning engine that can take actions | Always - this is your starting point |
| Tools | Functions the agent can call to interact with the world | When your agent needs to do more than chat |
| MCP Server | Standardized protocol for exposing tools to any agent | When you want reusable, shareable tool packages |
| Deployment | Run your agent as an API endpoint | When you’re ready to integrate with your app |
Agents
An Agent is an LLM with instructions and capabilities. At minimum, it needs:
- A name for identification
- A model (e.g.,
gpt-4o, claude-sonnet)
- Instructions defining its behavior
from agentor import Agentor
agent = Agentor(
name="assistant",
model="gpt-4o",
instructions="You help users with their questions."
)
Tools are functions your agent can call. They bridge the gap between “knowing” and “doing.”
from agentor.tools import GetWeatherTool, WebSearchTool
agent = Agentor(
name="research_assistant",
model="gpt-5",
tools=[GetWeatherTool(), WebSearchTool()]
)
- Built-in - Celesto provides common tools like weather, web search, and more
- Custom - Define your own Python functions as tools
- MCP Servers - Connect to standardized tool servers
Start with built-in tools. Graduate to custom tools or MCP when you need more control.
MCP (Model Context Protocol)
MCP is a standard for packaging and sharing tools. Think of it like an API specification for agent capabilities.
Why MCP matters:
- Reusability - Build once, use with any MCP-compatible agent
- Isolation - Tools run in their own server process
- Ecosystem - Access tools built by the community
# Connect to an MCP server
agent = Agentor(
name="gmail_assistant",
model="gpt-5",
tools=["celesto/gmail", "celesto/calendar"]
)
Deployment
Once your agent works locally, deploy it to make it accessible as an API.
Local API
Celesto Cloud
Self-Hosted
Run on your machine for development. One command to deploy with auto-scaling and monitoring. docker run -p 8000:8000 your-agent
Putting It Together
Here’s the typical progression:
Start Simple
Create an agent with just a model and instructions. Test it works.
Add Capabilities
Connect tools so your agent can take actions. Start with built-in tools.
Build Custom Tools
When built-ins aren’t enough, create custom tools or MCP servers.
Deploy
Ship your agent as an API. Start with Celesto Cloud for simplicity.
Next Steps