Skip to content

armgit / camel

Public Imported from GitHub
0

🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org

feat: ChatAgent be called via traditional service like OpenAPI (#2375)

Boer-Zhang1658679d6eff
diff --git a/camel/services/agent_openapi_server.py b/camel/services/agent_openapi_server.py
new file mode 100644
index 000000000..41f86bcf6
--- /dev/null
+++ b/camel/services/agent_openapi_server.py
@@ -0,0 +1,380 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+
+
+from typing import Any, Dict, List, Optional, Type, Union
+
+from fastapi import APIRouter, FastAPI, HTTPException
+from pydantic import BaseModel
+
+from camel.agents.chat_agent import ChatAgent
+from camel.messages import BaseMessage
+from camel.models import ModelFactory
+from camel.toolkits import FunctionTool
+from camel.types import RoleType
+
+
+class InitRequest(BaseModel):
+ r"""Request schema for initializing a ChatAgent via the OpenAPI server.
+
+ Defines the configuration used to create a new agent, including the model,
+ system message, tool names, and generation parameters.
+
+ Args:
+ model_type (Optional[str]): The model type to use. Should match a key
+ supported by the model manager, e.g., "gpt-4o-mini".
+ (default: :obj:`"gpt-4o-mini"`)
+ model_platform (Optional[str]): The model platform to use.
+ (default: :obj:`"openai"`)
+ tools_names (Optional[List[str]]): A list of tool names to load from
+ the tool registry. These tools will be available to the agent.
+ (default: :obj:`None`)
+ external_tools (Optional[List[Dict[str, Any]]]): Tool definitions
+ provided directly as dictionaries, bypassing the registry.
+ Currently not supported. (default: :obj:`None`)
+ agent_id (str): The unique identifier for the agent. Must be provided
+ explicitly to support multi-agent routing and control.
+ system_message (Optional[str]): The system prompt for the agent,
+ describing its behavior or role. (default: :obj:`None`)
+ message_window_size (Optional[int]): The number of recent messages to
+ retain in memory for context. (default: :obj:`None`)
+ token_limit (Optional[int]): The token budget for contextual memory.
+ (default: :obj:`None`)
+ output_language (Optional[str]): Preferred output language for the
+ agent's replies. (default: :obj:`None`)
+ max_iteration (Optional[int]): Maximum number of model
+ calling iterations allowed per step. If `None` (default), there's
+ no explicit limit. If `1`, it performs a single model call. If `N
+ > 1`, it allows up to N model calls. (default: :obj:`None`)
+ """
+
+ model_type: Optional[str] = "gpt-4o-mini"
+ model_platform: Optional[str] = "openai"
+
+ tools_names: Optional[List[str]] = None
+ external_tools: Optional[List[Dict[str, Any]]] = None
+
+ agent_id: str # Required: explicitly set agent_id to
+ # support future multi-agent and permission control
+
+ system_message: Optional[str] = None
+ message_window_size: Optional[int] = None
+ token_limit: Optional[int] = None
+ output_language: Optional[str] = None
+ max_iteration: Optional[int] = None # Changed from Optional[bool] = False
+
+
+class StepRequest(BaseModel):
+ r"""Request schema for sending a user message to a ChatAgent.
+
+ Supports plain text input or structured message dictionaries, with an
+ optional response format for controlling output structure.
+
+ Args:
+ input_message (Union[str, Dict[str, Any]]): The user message to send.
+ Can be a plain string or a message dict with role, content, etc.
+ response_format (Optional[str]): Optional format name that maps to a
+ registered response schema. Not currently in use.
+ (default: :obj:`None`)
+ """
+
+ input_message: Union[str, Dict[str, Any]]
+ response_format: Optional[str] = None # reserved, not used yet
+
+
+class ChatAgentOpenAPIServer:
+ r"""A FastAPI server wrapper for managing ChatAgents via OpenAPI routes.
+
+ This server exposes a versioned REST API for interacting with CAMEL
+ agents, supporting initialization, message passing, memory inspection,
+ and optional tool usage. It supports multi-agent use cases by mapping
+ unique agent IDs to active ChatAgent instances.
+
+ Typical usage includes initializing agents with system prompts and tools,
+ exchanging messages using /step or /astep endpoints, and inspecting agent
+ memory with /history.
+
+ Supports pluggable tool and response format registries for customizing
+ agent behavior or output schemas.
+ """
+
+ def __init__(
+ self,
+ tool_registry: Optional[Dict[str, List[FunctionTool]]] = None,
+ response_format_registry: Optional[Dict[str, Type[BaseModel]]] = None,
+ ):
+ r"""Initializes the OpenAPI server for managing ChatAgents.
+
+ Sets up internal agent storage, tool and response format registries,
+ and prepares versioned API routes.
+
+ Args:
+ tool_registry (Optional[Dict[str, List[FunctionTool]]]): A mapping
+ from tool names to lists of FunctionTool instances available
+ to agents via the "tools_names" field. If not provided, an
+ empty registry is used. (default: :obj:`None`)
+ response_format_registry (Optional[Dict[str, Type[BaseModel]]]):
+ A mapping from format names to Pydantic output schemas for
+ structured response parsing. Used for controlling the format
+ of step results. (default: :obj:`None`)
+ """
+
+ # Initialize FastAPI app and agent
+ self.app = FastAPI(title="CAMEL OpenAPI-compatible Server")
+ self.agents: Dict[str, ChatAgent] = {}
+ self.tool_registry = tool_registry or {}
+ self.response_format_registry = response_format_registry or {}
+ self._setup_routes()
+
+ def _parse_input_message_for_step(
+ self, raw: Union[str, dict]
+ ) -> BaseMessage:
+ r"""Parses raw input into a BaseMessage object.
+
+ Args:
+ raw (str or dict): User input as plain text or dict.
+
+ Returns:
+ BaseMessage: Parsed input message.
+ """
+ if isinstance(raw, str):
+ return BaseMessage.make_user_message(role_name="User", content=raw)
+ elif isinstance(raw, dict):
+ if isinstance(raw.get("role_type"), str):
+ raw["role_type"] = RoleType(raw["role_type"].lower())
+ return BaseMessage(**raw)
+ raise HTTPException(
+ status_code=400, detail="Unsupported input format."
+ )
+
+ def _resolve_response_format_for_step(
+ self, name: Optional[str]
+ ) -> Optional[Type[BaseModel]]:
+ r"""Resolves the response format by name.
+
+ Args:
+ name (str or None): Optional format name.
+
+ Returns:
+ Optional[Type[BaseModel]]: Response schema class.
+ """
+ if name is None:
+ return None
+ if name not in self.response_format_registry:
+ raise HTTPException(
+ status_code=400, detail=f"Unknown response_format: {name}"
+ )
+ return self.response_format_registry[name]
+
+ def _setup_routes(self):
+ r"""Registers OpenAPI endpoints for agent creation and interaction.
+
+ This includes routes for initializing agents (/init), sending
+ messages (/step and /astep), resetting agent memory (/reset), and
+ retrieving conversation history (/history). All routes are added
+ under the /v1/agents namespace.
+ """
+
+ router = APIRouter(prefix="/v1/agents")
+
+ @router.post("/init")
+ def init_agent(request: InitRequest):
+ r"""Initializes a ChatAgent instance with a model,
+ system message, and optional tools.
+
+ Args:
+ request (InitRequest): The agent config including
+ model, tools, system message, and agent ID.
+
+ Returns:
+ dict: A message with the agent ID and status.
+ """
+
+ agent_id = request.agent_id
+ if agent_id in self.agents:
+ return {
+ "agent_id": agent_id,
+ "message": "Agent already exists.",
+ }
+
+ model_type = request.model_type
+ model_platform = request.model_platform
+
+ model = ModelFactory.create(
+ model_platform=model_platform, # type: ignore[arg-type]
+ model_type=model_type, # type: ignore[arg-type]
+ )
+
+ # tools lookup
+ tools = []
+ if request.tools_names:
+ for name in request.tools_names:
+ if name in self.tool_registry:
+ tools.extend(self.tool_registry[name])
+ else:
+ raise HTTPException(
+ status_code=400,
+ detail=f"Tool '{name}' " f"not found in registry",
+ )
+
+ # system message
+ system_message = request.system_message
+
+ agent = ChatAgent(
+ model=model,
+ tools=tools, # type: ignore[arg-type]
+ external_tools=request.external_tools, # type: ignore[arg-type]
+ system_message=system_message,
+ message_window_size=request.message_window_size,
+ token_limit=request.token_limit,
+ output_language=request.output_language,
+ max_iteration=request.max_iteration,
+ agent_id=agent_id,
+ )
+
+ self.agents[agent_id] = agent
+ return {"agent_id": agent_id, "message": "Agent initialized."}
+
+ @router.post("/astep/{agent_id}")
+ async def astep_agent(agent_id: str, request: StepRequest):
+ r"""Runs one async step of agent response.
+
+ Args:
+ agent_id (str): The ID of the target agent.
+ request (StepRequest): The input message.
+
+ Returns:
+ dict: The model response in serialized form.
+ """
+
+ if agent_id not in self.agents:
+ raise HTTPException(status_code=404, detail="Agent not found.")
+
+ agent = self.agents[agent_id]
+ input_message = self._parse_input_message_for_step(
+ request.input_message
+ )
+ format_cls = self._resolve_response_format_for_step(
+ request.response_format
+ )
+
+ try:
+ response = await agent.astep(
+ input_message=input_message, response_format=format_cls
+ )
+ return response.model_dump()
+ except Exception as e:
+ raise HTTPException(
+ status_code=500,
+ detail=f"Unexpected error during async step: {e!s}",
+ )
+
+ @router.get("/list_agent_ids")
+ def list_agent_ids():
+ r"""Returns a list of all active agent IDs.
+
+ Returns:
+ dict: A dictionary containing all registered agent IDs.
+ """
+ return {"agent_ids": list(self.agents.keys())}
+
+ @router.post("/delete/{agent_id}")
+ def delete_agent(agent_id: str):
+ r"""Deletes an agent from the server.
+
+ Args:
+ agent_id (str): The ID of the agent to delete.
+
+ Returns:
+ dict: A confirmation message upon successful deletion.
+ """
+ if agent_id not in self.agents:
+ raise HTTPException(status_code=404, detail="Agent not found.")
+
+ del self.agents[agent_id]
+ return {"message": f"Agent {agent_id} deleted."}
+
+ @router.post("/step/{agent_id}")
+ def step_agent(agent_id: str, request: StepRequest):
+ r"""Runs one step of synchronous agent response.
+
+ Args:
+ agent_id (str): The ID of the target agent.
+ request (StepRequest): The input message.
+
+ Returns:
+ dict: The model response in serialized form.
+ """
+ if agent_id not in self.agents:
+ raise HTTPException(status_code=404, detail="Agent not found.")
+
+ agent = self.agents[agent_id]
+ input_message = self._parse_input_message_for_step(
+ request.input_message
+ )
+ format_cls = self._resolve_response_format_for_step(
+ request.response_format
+ )
+ try:
+ response = agent.step(
+ input_message=input_message, response_format=format_cls
+ )
+ return response.model_dump()
+ except Exception as e:
+ raise HTTPException(
+ status_code=500,
+ detail=f"Unexpected error during step: {e!s}",
+ )
+
+ @router.post("/reset/{agent_id}")
+ def reset_agent(agent_id: str):
+ r"""Clears memory for a specific agent.
+
+ Args:
+ agent_id (str): The ID of the agent to reset.
+
+ Returns:
+ dict: A message confirming reset success.
+ """
+ if agent_id not in self.agents:
+ raise HTTPException(status_code=404, detail="Agent not found.")
+ self.agents[agent_id].reset()
+ return {"message": f"Agent {agent_id} reset."}
+
+ @router.get("/history/{agent_id}")
+ def get_agent_chat_history(agent_id: str):
+ r"""Returns the chat history of an agent.
+
+ Args:
+ agent_id (str): The ID of the agent to query.
+
+ Returns:
+ list: The list of conversation messages.
+ """
+ if agent_id not in self.agents:
+ raise HTTPException(
+ status_code=404, detail=f"Agent {agent_id} not found."
+ )
+ return self.agents[agent_id].chat_history
+
+ # Register all routes to the main FastAPI app
+ self.app.include_router(router)
+
+ def get_app(self) -> FastAPI:
+ r"""Returns the FastAPI app instance.
+
+ Returns:
+ FastAPI: The wrapped application object.
+ """
+ return self.app
diff --git a/examples/services/agent_openapi_server.py b/examples/services/agent_openapi_server.py
new file mode 100644
index 000000000..c5a2b79fc
--- /dev/null
+++ b/examples/services/agent_openapi_server.py
@@ -0,0 +1,454 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+
+from fastapi.testclient import TestClient
+
+from camel.services.agent_openapi_server import ChatAgentOpenAPIServer
+
+
+def example_init_and_step():
+ r"""Demonstrates a minimal example of initializing a single agent,
+ assigning it a tool from the registry, sending one message, and viewing
+ the agent's memory history.
+
+ This example uses the OpenAPI-compatible FastAPI interface for
+ `ChatAgentOpenAPIServer` and includes:
+
+ - POST /v1/agents/init: Initializes the agent with a system message and a
+ wiki search tool.
+ - POST /v1/agents/step: Sends a user message prompting the agent to call
+ the tool.
+ - GET /v1/agents/history: Retrieves the agent's full conversation history.
+
+ The tool used is `search_wiki`, wrapped with `FunctionTool` and
+ retrieved from the `SearchToolkit`.
+
+ Prints the server response at each step.
+ """
+
+ from camel.toolkits import FunctionTool, SearchToolkit
+
+ wiki_tool = FunctionTool(SearchToolkit().search_wiki)
+
+ tool_registry = {"search_wiki": [wiki_tool]}
+
+ server = ChatAgentOpenAPIServer(tool_registry=tool_registry)
+ client = TestClient(server.get_app())
+
+ r = client.post(
+ "/v1/agents/init",
+ json={
+ "agent_id": "demo",
+ "tools_names": ["search_wiki"],
+ "system_message": (
+ "You are a helpful assistant with access to "
+ "a wiki search tool."
+ ),
+ },
+ )
+ print("Init response:", r.json())
+ """
+ Init response:
+ {'agent_id': 'demo', 'message': 'Agent initialized.'}
+ """
+
+ r = client.post(
+ "/v1/agents/step/demo", #
+ json={"input_message": "Search: What is machine learning?"},
+ )
+ print("Step response:", r.json())
+
+ """
+ Step response:
+ {'msgs': [{'role_name': 'Assistant',
+ 'role_type': 'assistant',
+ 'meta_dict': {},
+ 'content': 'Machine learning (ML) is a field of study in '
+ 'artificial intelligence focused on '
+ 'developing statistical algorithms that can '
+ 'learn from data and generalize to unseen data, '
+ 'allowing them to perform tasks without explicit '
+ 'instructions. A notable advancement in this '
+ 'area is deep learning, which uses neural '
+ 'networks to achieve superior performance over '
+ 'traditional machine learning methods. \n\nML is '
+ 'applied in various fields such as natural '
+ 'language processing, computer vision, speech '
+ 'recognition, email filtering, agriculture, and '
+ 'medicine. When used to address business '
+ 'challenges, it is referred to as predictive '
+ 'analytics. The foundations of machine learning '
+ 'are built on statistics and mathematical '
+ 'optimization methods.',
+ 'video_bytes': None,
+ 'image_list': None,
+ 'image_detail': 'auto',
+ 'video_detail': 'low',
+ 'parsed': None}],
+ 'terminated': False,
+ 'info': {'id': 'chatcmpl-BW6SV6iEFkVpqcxwJuodhLOSQcmde',
+ 'usage': {'completion_tokens': 121,
+ 'prompt_tokens': 254,
+ 'total_tokens': 375,
+ 'completion_tokens_details': {
+ 'accepted_prediction_tokens': 0,
+ 'audio_tokens': 0,
+ 'reasoning_tokens': 0,
+ 'rejected_prediction_tokens': 0},
+ 'prompt_tokens_details': {
+ 'audio_tokens': 0,
+ 'cached_tokens': 0}},
+ 'termination_reasons': ['stop'],
+ 'num_tokens': 201,
+ 'tool_calls': [{
+ 'tool_name': 'search_wiki',
+ 'args': {
+ 'entity': 'Machine learning'
+ },
+ 'result': 'Machine learning (ML) is a field of study in '
+ 'artificial intelligence concerned with the '
+ 'development and study of statistical '
+ 'algorithms that can learn from data and '
+ 'generalise to unseen data, and thus perform '
+ 'tasks without explicit instructions. Within a '
+ 'subdiscipline in machine learning, advances in '
+ 'the field of deep learning have allowed neural '
+ 'networks, a class of statistical algorithms, to '
+ 'surpass many previous machine learning '
+ 'approaches in performance.\nML finds '
+ 'application in many fields, including natural '
+ 'language processing, computer vision, speech '
+ 'recognition, email filtering, agriculture, and '
+ 'medicine. The application of ML to business '
+ 'problems is known as predictive analytics.\n'
+ 'Statistics and mathematical optimisation '
+ '(mathematical programming) methods comprise '
+ 'the foundations of machine learning.',
+ 'tool_call_id': 'call_lYVcPVKqPNPZi7TsSRRbanZ2'
+ }],
+ """
+
+ r = client.get("/v1/agents/history/demo")
+ print("History:", r.json())
+
+ """
+ History:
+ [{'role': 'system',
+ 'content': 'You are a helpful assistant with access to a wiki search '
+ 'tool.'},
+ {'role': 'user',
+ 'content': 'Search: What is machine learning?'},
+ {'role': 'assistant',
+ 'content': '',
+ 'tool_calls': [{'id': 'call_lYVcPVKqPNPZi7TsSRRbanZ2',
+ 'type': 'function',
+ 'function': {'name': 'search_wiki',
+ 'arguments': '{"entity": "Machine '
+ 'learning"}'}}]},
+ {'role': 'tool',
+ 'content': 'Machine learning (ML) is a field of study in artificial '
+ 'intelligence concerned with the development and study of '
+ 'statistical algorithms that can learn from data and '
+ 'generalise to unseen data, and thus perform tasks without '
+ 'explicit instructions. Within a subdiscipline in machine '
+ 'learning, advances in the field of deep learning have '
+ 'allowed neural networks, a class of statistical '
+ 'algorithms, to surpass many previous machine learning '
+ 'approaches in performance.\nML finds application in many '
+ 'fields, including natural language processing, computer '
+ 'vision, speech recognition, email filtering, agriculture, '
+ 'and medicine. The application of ML to business problems '
+ 'is known as predictive analytics.\nStatistics and '
+ 'mathematical optimisation (mathematical programming) '
+ 'methods comprise the foundations of machine learning.',
+ 'tool_call_id': 'call_lYVcPVKqPNPZi7TsSRRbanZ2'},
+ {'role': 'assistant',
+ 'content': 'Machine learning (ML) is a field of study in artificial '
+ 'intelligence focused on developing statistical algorithms '
+ 'that can learn from data and generalize to unseen data, '
+ 'allowing them to perform tasks without explicit '
+ 'instructions. A notable advancement in this area is deep '
+ 'learning, which uses neural networks to achieve superior '
+ 'performance over traditional machine learning methods. '
+ '\n\nML is applied in various fields such as natural '
+ 'language processing, computer vision, speech recognition, '
+ 'email filtering, agriculture, and medicine. When used to '
+ 'address business challenges, it is referred to as '
+ 'predictive analytics. The foundations of machine learning '
+ 'are built on statistics and mathematical optimization '
+ 'methods.'}]
+ """
+
+ # Reset Agent
+ r = client.post("/v1/agents/reset/demo")
+ print("Reset:", r.json())
+ """
+ Reset: {'message': 'Agent demo reset.'}
+ """
+
+ # Display history again after reset
+ r = client.get("/v1/agents/history/demo")
+ print("History:", r.json())
+ """
+ History: [{'role': 'system',
+ 'content': 'You are a helpful assistant
+ with access to a wiki search tool.'}]
+ """
+
+
+def example_init_and_astep():
+ r"""Demonstrates a minimal example of initializing a single agent,
+ assigning it a tool from the registry, sending one message, and viewing
+ the agent's memory history.
+
+ This example uses the OpenAPI-compatible FastAPI interface for
+ `ChatAgentOpenAPIServer` and includes:
+
+ - POST /v1/agents/init: Initializes the agent with a system message and a
+ wiki search tool.
+ - POST /v1/agents/step: Sends a user message prompting the agent to call
+ the tool.
+ - GET /v1/agents/history: Retrieves the agent's full conversation history.
+
+ The tool used is `search_wiki`, wrapped with `FunctionTool` and
+ retrieved from the `SearchToolkit`.
+
+ Prints the server response at each step.
+ """
+
+ from camel.toolkits import FunctionTool, SearchToolkit
+
+ wiki_tool = FunctionTool(SearchToolkit().search_wiki)
+
+ tool_registry = {"search_wiki": [wiki_tool]}
+
+ server = ChatAgentOpenAPIServer(tool_registry=tool_registry)
+ client = TestClient(server.get_app())
+
+ r = client.post(
+ "/v1/agents/init",
+ json={
+ "agent_id": "demo",
+ "tools_names": ["search_wiki"],
+ "system_message": (
+ "You are a helpful assistant with access to "
+ "a wiki search tool."
+ ),
+ },
+ )
+ print("Init response:", r.json())
+ # Init response:
+ # {'agent_id': 'demo', 'message': 'Agent initialized.'}
+
+ r = client.post(
+ "/v1/agents/astep/demo", #
+ json={"input_message": "Search: What is machine learning?"},
+ )
+ print("Step response (astep):", r.json())
+
+ """
+ Step response:
+ {'msgs': [{'role_name': 'Assistant',
+ 'role_type': 'assistant',
+ 'meta_dict': {},
+ 'content': 'Machine learning (ML) is a field of study in '
+ 'artificial intelligence focused on '
+ 'developing statistical algorithms that can '
+ 'learn from data and generalize to unseen data, '
+ 'allowing them to perform tasks without explicit '
+ 'instructions. A notable advancement in this '
+ 'area is deep learning, which uses neural '
+ 'networks to achieve superior performance over '
+ 'traditional machine learning methods. \n\nML is '
+ 'applied in various fields such as natural '
+ 'language processing, computer vision, speech '
+ 'recognition, email filtering, agriculture, and '
+ 'medicine. When used to address business '
+ 'challenges, it is referred to as predictive '
+ 'analytics. The foundations of machine learning '
+ 'are built on statistics and mathematical '
+ 'optimization methods.',
+ 'video_bytes': None,
+ 'image_list': None,
+ 'image_detail': 'auto',
+ 'video_detail': 'low',
+ 'parsed': None}],
+ 'terminated': False,
+ 'info': {'id': 'chatcmpl-BW6SV6iEFkVpqcxwJuodhLOSQcmde',
+ 'usage': {'completion_tokens': 121,
+ 'prompt_tokens': 254,
+ 'total_tokens': 375,
+ 'completion_tokens_details': {
+ 'accepted_prediction_tokens': 0,
+ 'audio_tokens': 0,
+ 'reasoning_tokens': 0,
+ 'rejected_prediction_tokens': 0},
+ 'prompt_tokens_details': {
+ 'audio_tokens': 0,
+ 'cached_tokens': 0}},
+ 'termination_reasons': ['stop'],
+ 'num_tokens': 201,
+ 'tool_calls': [{
+ 'tool_name': 'search_wiki',
+ 'args': {
+ 'entity': 'Machine learning'
+ },
+ 'result': 'Machine learning (ML) is a field of study in '
+ 'artificial intelligence concerned with the '
+ 'development and study of statistical '
+ 'algorithms that can learn from data and '
+ 'generalise to unseen data, and thus perform '
+ 'tasks without explicit instructions. Within a '
+ 'subdiscipline in machine learning, advances in '
+ 'the field of deep learning have allowed neural '
+ 'networks, a class of statistical algorithms, to '
+ 'surpass many previous machine learning '
+ 'approaches in performance.\nML finds '
+ 'application in many fields, including natural '
+ 'language processing, computer vision, speech '
+ 'recognition, email filtering, agriculture, and '
+ 'medicine. The application of ML to business '
+ 'problems is known as predictive analytics.\n'
+ 'Statistics and mathematical optimisation '
+ '(mathematical programming) methods comprise '
+ 'the foundations of machine learning.',
+ 'tool_call_id': 'call_lYVcPVKqPNPZi7TsSRRbanZ2'
+ }],
+ """
+
+
+def example_listing_and_delete_agents():
+ r"""Creates multiple agents, lists them, deletes one, and lists again
+ to verify it was removed.
+ """
+ from fastapi.testclient import TestClient
+
+ from camel.services.agent_openapi_server import ChatAgentOpenAPIServer
+
+ client = TestClient(ChatAgentOpenAPIServer().get_app())
+
+ # Step 1: Create two agents
+ for agent_id in ["agent_1", "agent_2"]:
+ r = client.post(
+ "/v1/agents/init",
+ json={
+ "agent_id": agent_id,
+ "system_message": f"You are {agent_id}, a helpful assistant.",
+ },
+ )
+ print(f"Init {agent_id}:", r.json())
+
+ # Step 2: List current agents
+ r = client.get("/v1/agents/list_agent_ids")
+ print("Current agents:", r.json()) # Should contain agent_1 and agent_2
+
+ # Step 3: Delete agent_1
+ r = client.post("/v1/agents/delete/agent_1")
+ print("Reset agent_1:", r.json())
+
+ # Step 4: List agents again
+ r = client.get("/v1/agents/list_agent_ids")
+ print("Remaining agents:", r.json()) # Should contain only agent_2
+
+ """
+ Init agent_1: {'agent_id': 'agent_1', 'message': 'Agent initialized.'}
+ Init agent_2: {'agent_id': 'agent_2', 'message': 'Agent initialized.'}
+ Current agents: {'agent_ids': ['agent_1', 'agent_2']}
+ Reset agent_1: {'message': 'Agent agent_1 reset.'}
+ Remaining agents: {'agent_ids': ['agent_1', 'agent_2']}
+ """
+
+
+def example_multi_agent_turns(num_rounds: int = 10):
+ r"""Runs a multi-turn debate between two agents using the OpenAPI
+ interface.
+
+ The agents are initialized with opposing roles (PRO and CON) on a
+ specific topic. Each agent takes turns generating a response and
+ sending it as the next message to the opponent.
+
+ Args:
+ num_rounds (int): The number of turn-based exchanges in the
+ debate. Each round consists of one message per agent.
+
+ API calls used:
+ - POST /v1/agents/init: Initializes each agent with a system message
+ describing their debate role.
+ - POST /v1/agents/step: Sends messages alternately between agents to
+ simulate a live debate.
+
+ Prints each round of the debate to stdout.
+ """
+
+ client = TestClient(ChatAgentOpenAPIServer().get_app())
+
+ # Debate topic
+ topic = "Are multiple agents better than a single agent?"
+
+ # Define agents with topic-aware debate roles
+ roles = {
+ "pro": (
+ f"You are the PRO side in a multi-turn debate on: '{topic}'. "
+ "Argue that multiple agents are better than a single agent. "
+ "Reply to the opponent directly. Do not repeat introductions. "
+ "Be confident and persuasive."
+ ),
+ "con": (
+ f"You are the CON side in a multi-turn debate on: '{topic}'. "
+ "Argue that a single agent is better than multiple agents. "
+ "Respond directly to your opponent. Avoid repeating intros. "
+ "Be sharp, critical, and focused."
+ ),
+ }
+
+ # Initialize each agent
+ for agent_id, system_msg in roles.items():
+ client.post(
+ "/v1/agents/init",
+ json={"agent_id": agent_id, "system_message": system_msg},
+ )
+
+ message = "Now start debating on this topic:" + topic
+ for i in range(num_rounds):
+ speaker = "pro" if i % 2 == 0 else "con"
+ receiver = "con" if speaker == "pro" else "pro"
+
+ print(f"\n[{speaker.upper()} → {receiver.upper()}]")
+ response = client.post(
+ f"/v1/agents/step/{speaker}", json={"input_message": message}
+ ).json()
+ message = response["msgs"][0]["content"]
+ print(message)
+
+
+if __name__ == "__main__":
+ import sys
+
+ example = sys.argv[1] if len(sys.argv) > 1 else "basic_sync"
+
+ if example == "basic_sync":
+ # An example showing how to work with a single agent with our API
+ example_init_and_step()
+ elif example == "basic_async":
+ # An example showing how to work with a single agent with our API
+ example_init_and_astep()
+ elif example == "multiple_agents_list_and_delete":
+ # An example showing how to work with a single agent with our API
+ example_listing_and_delete_agents()
+ elif example == "debate":
+ # An example showing how to work with a multiple agents with our API
+ # Here we are asking two agents to debate on a topic.
+ example_multi_agent_turns()
+ else:
+ print("Unknown example. Use: basic | debate")
diff --git a/test/services/test_agent_openapi_server.py b/test/services/test_agent_openapi_server.py
new file mode 100644
index 000000000..67a91e7d9
--- /dev/null
+++ b/test/services/test_agent_openapi_server.py
@@ -0,0 +1,187 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+
+import pytest
+from fastapi import HTTPException
+from fastapi.testclient import TestClient
+from httpx import ASGITransport, AsyncClient
+from pydantic import BaseModel
+
+from camel.messages import BaseMessage
+from camel.services.agent_openapi_server import ChatAgentOpenAPIServer
+from camel.toolkits import FunctionTool, SearchToolkit
+
+
+def client_with_tool():
+ r"""Creates a FastAPI test client with a registered tool."""
+ tool = FunctionTool(SearchToolkit().search_wiki)
+ server = ChatAgentOpenAPIServer(tool_registry={"search_wiki": [tool]})
+ client = TestClient(server.get_app())
+ return client
+
+
+def test_init_agent(client_with_tool):
+ r"""Tests the /v1/agents/init endpoint initializes an agent correctly."""
+ response = client_with_tool.post(
+ "/v1/agents/init",
+ json={
+ "agent_id": "test_agent",
+ "tools_names": ["search_wiki"],
+ "system_message": "You are a helpful assistant.",
+ },
+ )
+ assert response.status_code == 200
+ assert response.json()["agent_id"] == "test_agent"
+
+
+def test_step_interaction(client_with_tool):
+ r"""Tests /v1/agents/step returns a valid agent response with a tool."""
+ client_with_tool.post(
+ "/v1/agents/init",
+ json={
+ "agent_id": "test_agent",
+ "tools_names": ["search_wiki"],
+ "system_message": "You are a helpful assistant.",
+ },
+ )
+ response = client_with_tool.post(
+ "/v1/agents/step/test_agent",
+ json={"input_message": "Search: What is machine learning?"},
+ )
+ result = response.json()
+ assert response.status_code == 200
+ assert isinstance(result, dict)
+ assert "msgs" in result
+ assert isinstance(result["msgs"], list)
+
+
+def test_get_history(client_with_tool):
+ r"""Tests /v1/agents/history returns a list of message history."""
+ client_with_tool.post(
+ "/v1/agents/init",
+ json={
+ "agent_id": "test_agent",
+ "tools_names": ["search_wiki"],
+ "system_message": "You are a helpful assistant.",
+ },
+ )
+ client_with_tool.post(
+ "/v1/agents/step/test_agent",
+ json={"input_message": "Search: What is machine learning?"},
+ )
+ history = client_with_tool.get("/v1/agents/history/test_agent")
+ assert history.status_code == 200
+ assert isinstance(history.json(), list)
+
+
+def test_reset_agent(client_with_tool):
+ r"""Tests /v1/agents/reset resets the agent successfully."""
+ client_with_tool.post("/v1/agents/init", json={"agent_id": "test_agent"})
+ response = client_with_tool.post("/v1/agents/reset/test_agent")
+ assert response.status_code == 200
+ assert "reset" in response.json()["message"].lower()
+
+
+async def test_async_step_route_with_tool():
+ r"""Tests the /v1/agents/astep endpoint with an async client.
+
+ Initializes an agent with a tool and sends an async message to verify
+ the full pipeline works, including tool invocation and message return.
+ """
+
+ # Lazily create the app with tool
+ tool_registry = {
+ "search_wiki": [FunctionTool(SearchToolkit().search_wiki)]
+ }
+ server = ChatAgentOpenAPIServer(tool_registry=tool_registry)
+ app = server.get_app()
+
+ transport = ASGITransport(app=app)
+
+ async with AsyncClient(transport=transport, base_url="http://test") as ac:
+ # Step 1: Init
+ resp = await ac.post(
+ "/v1/agents/init",
+ json={
+ "agent_id": "demo",
+ "tools_names": ["search_wiki"],
+ "system_message": "You are a helpful assistant"
+ " with wiki access.",
+ },
+ )
+ assert resp.status_code == 200
+ assert resp.json()["agent_id"] == "demo"
+
+ # Step 2: Async step with tool
+ resp = await ac.post(
+ "/v1/agents/astep/demo",
+ json={"input_message": "Search: What is machine learning?"},
+ )
+ assert resp.status_code == 200
+ data = resp.json()
+ assert isinstance(data.get("msgs"), list)
+ assert any(
+ "machine learning" in m["content"].lower()
+ for m in data["msgs"]
+ if "content" in m
+ )
+
+
+def test_parse_input_message_for_step_string():
+ r"""Tests parsing a plain string input message."""
+ server = ChatAgentOpenAPIServer()
+
+ # Test string input
+ result = server._parse_input_message_for_step("Hello, world!")
+
+ assert isinstance(result, BaseMessage)
+ assert result.content == "Hello, world!"
+ assert result.role_name == "User"
+
+
+def test_resolve_response_format_for_step():
+ r"""Tests response format resolution with valid and invalid names."""
+
+ # Create a dummy response format for testing
+ class TestResponseFormat(BaseModel):
+ message: str
+ status: int
+
+ # Server with registered response format
+ server = ChatAgentOpenAPIServer(
+ response_format_registry={"test_format": TestResponseFormat}
+ )
+
+ # Test None input (should return None)
+ result = server._resolve_response_format_for_step(None)
+ assert result is None
+
+ # Test valid format name
+ result = server._resolve_response_format_for_step("test_format")
+ assert result == TestResponseFormat
+
+ # Test invalid format name
+ with pytest.raises(HTTPException) as exc_info:
+ server._resolve_response_format_for_step("invalid_format")
+
+ assert exc_info.value.status_code == 400
+ assert "Unknown response_format: invalid_format" in str(
+ exc_info.value.detail
+ )