Skip to main content

AgentCurie

AgentCurie is a supervisor agentic framework designed to control and coordinate agents built with multiple frameworks.

The name is inspired by Maria Salomea Skłodowska-Curie, the only person to have received Nobel Prizes in two different scientific fields. Similarly, AgentCurie is capable of supervising and orchestrating agents originating from different ecosystems.


Installation

pip install agentcurie

Quick Start

1. Define Your Agent

Create a custom agent by extending BaseAgent. Your agent implements a process method, which the supervisor will invoke.

from agentcurie import BaseAgent
from langchain_core.tools import tool
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(model="gpt-4o-mini")

class CreativeAgent(BaseAgent):
    def __init__(self):
        super().__init__()

        # Tool to communicate back with the supervisor
        query_tool = tool()(self.query_supervisor)

        self.agent = create_react_agent(
            model=llm,
            tools=[calculator, write_poem, query_tool],
        )

    async def process(self, message: str) -> str:
        result = await self.agent.ainvoke({
            "messages": [{"role": "user", "content": message}]
        })
        return result["messages"][-1].content

2. Describe the Agent with an AgentCard

An AgentCard defines the agent's identity, skills, and lifecycle behavior.

from agentcurie import AgentCard

my_agent_card = AgentCard(
    name="creative_agent",
    description="Can write poems and perform calculations",
    skills=[
        "write poems",
        "does calculations like add, subtract, multiply, divide"
    ],
    persistent=True,           # Keep the agent alive across invocations
    background_runnable=True   # Allow the supervisor to run this agent in background
)

3. Create and Configure the Supervisor

from agentcurie import SupervisorAgent, FuncHook, AgentHook, BaseAgent

async def intermediate_logger(supervisor: SupervisorAgent):
    last_message = supervisor.message_manager.history.get_last_message()
    print(last_message)

async def child_agent_state_updater(child_agent: BaseAgent, supervisor: SupervisorAgent):
    pass  # custom post-agent logic

supervisor = SupervisorAgent(
    llm=llm,
    func_hooks=[
        FuncHook(order='before', func=intermediate_logger)
    ],
    agent_hooks=[
        AgentHook(order='after', agent_name='creative_agent', func=child_agent_state_updater)
    ]
)

4. Register Agents and Tools

supervisor.register_agent(
    agent_card=my_agent_card,
    agent_class=CreativeAgent
)

@supervisor.register_tool("Get current weather for a city")
def get_weather(city: str) -> str:
    weather_data = {
        "New York": "Sunny, 72°F",
        "London": "Cloudy, 15°C",
    }
    return weather_data.get(city, f"Weather data not available for {city}")

# Register a background-runnable tool
@supervisor.register_tool("Run a slow background job", background_runnable=True)
async def slow_job(input: str) -> str:
    await asyncio.sleep(5)
    return f"Job done for: {input}"

5. Run the Supervisor

import asyncio

async def main():
    result = await supervisor.solve(
        "Check weather in London and write a poem about it"
    )
    print(result)

asyncio.run(main())

Key Features

Multi-Agent Orchestration

The supervisor intelligently delegates subtasks to the right child agent and coordinates their results. Child agents can be built with any framework (LangChain, custom, external).

Agent Queries

If a child agent is stuck or needs additional information, it can call query_supervisor() to pause execution and ask the supervisor. The supervisor can answer directly or delegate to another agent.

class MyAgent(BaseAgent):
    def __init__(self):
        super().__init__()
        query_tool = tool()(self.query_supervisor)
        ...

Background Execution

Agents and tools can be marked as background_runnable. The supervisor can fire them off without blocking and retrieve results later via wait_for_agent / wait_for_tool.

For agents — set background_runnable=True on the AgentCard:

AgentCard(name="slow_agent", ..., background_runnable=True)

For tools — pass background_runnable=True to register_tool:

@supervisor.register_tool("A slow tool", background_runnable=True)
async def slow_tool(param: str) -> str:
    ...

The supervisor automatically receives [BACKGROUND UPDATE] notifications when background tasks complete, and can use the built-in wait_for_agent or wait_for_tool tools to block until a specific result is ready.

Dynamic Initialization and Persistence

Child agents are only instantiated when first needed. Setting persistent=True on an AgentCard keeps the agent alive across multiple calls within the same solve() session.

Hook System

Hooks let you inject custom logic before or after any step:

  • FuncHook — runs before/after each supervisor step (receives the supervisor instance)
  • AgentHook — runs before/after a specific child agent is invoked (receives the agent and supervisor)
FuncHook(order='before', func=my_func)
AgentHook(order='after', agent_name='my_agent', func=my_agent_func)

MCP Client

AgentCurie includes a built-in MCP (Model Context Protocol) client to convert MCP-compatible tool definitions into supervisor-level tools:

from agentcurie import MCPClient

mcp = MCPClient(...)
tools = await mcp.get_tools()
for t in tools:
    supervisor.register_tool(t.description)(t.func)

Architecture

AgentCurie uses a feature-based modular architecture:

agentcurie/
├── supervisor/          # Master supervisor agent
│   ├── service.py       # SupervisorAgent — main orchestration loop
│   ├── prompts.py       # System prompts
│   ├── views.py         # FuncHook, AgentHook, AgentResult
│   └── message_manager/ # Conversation history & token management
├── controller/          # Tool and agent execution layer
│   ├── service.py       # Controller — dispatches tools and agents
│   ├── tool/            # Tool registration, registry, execution
│   └── agent/           # Agent registration, registry, execution
└── mcp_client/          # MCP protocol integration

Running the Example

# Add your OpenAI API key to examples/.env
echo "OPENAI_KEY=sk-..." > examples/.env

python -m examples.langchain_agents.main

Vision

AgentCurie is designed as a framework-agnostic control layer for the future of agentic systems — where multiple agents, tools, and reasoning engines collaborate under a single, well-structured supervisor.

Metadata

Release files for agentcurie 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for agentcurie 1.0.0
File Size Uploaded Provenance Actions
agentcurie-1.0.0.tar.gz 40.1 kB Without provenance Details for agentcurie-1.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for agentcurie 1.0.0
File Interpreter ABI Platform Actions
agentcurie-1.0.0-py3-none-any.whl Python 3 none any Details for agentcurie-1.0.0-py3-none-any.whl

Total release size: 88.2 kB

Release files / agentcurie-1.0.0.tar.gz

Download URL agentcurie-1.0.0.tar.gz
Size 40.1 kB
Tags Source
SHA-256 checksum
How to use checksums
7044d84553a39b1f9d5e3e88ebcc88f1093a802a5d1de795eee2b2fdb649a9c6
BLAKE2b-256 checksum
How to use checksums
0779ee9c83405022bf2e04fa71afbde7dd3a0b0f76f5f4876ba783478e137b2c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.14.0

Release files / agentcurie-1.0.0-py3-none-any.whl

Download URL agentcurie-1.0.0-py3-none-any.whl
Size 48.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
14eed8998b5bfa6605dc65f9574680f594f80fe1fcb06b9599ff2fc5662ba422
BLAKE2b-256 checksum
How to use checksums
a1bf8d5181836ed7b13a1679f4d028b09818d392b042433029925aaa7a666213
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.14.0

Security for agentcurie 1.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page