🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org
Python agentai-societiesartificial-intelligencecommunicative-aicooperative-aideep-learninglarge-language-modelsmulti-agent-systemsnatural-language-processing
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.pynew file mode 100644index 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.appdiff --git a/examples/services/agent_openapi_server.py b/examples/services/agent_openapi_server.pynew file mode 100644index 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.pynew file mode 100644index 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++[email protected]_backend+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"++[email protected]_backend+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)++[email protected]_backend+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()++[email protected]_backend+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+ )