OpenAI Agents MCP Server

Instructions

Implementation Reference

• src/agents_mcp_server/server.py:190-226 (handler)

  The primary handler for the 'web_search_agent' MCP tool. It runs the web_search_agent (or a location-specific variant) using the Runner to execute web searches via WebSearchTool.

  @mcp.tool(
      name="web_search_agent",
      description="Use an AI agent specialized in web searching to find accurate, up-to-date information from the internet.",
  )
  async def web_search(
      query: str = Field(
          ..., description="The search query or question you want to find information about online."
      ),
      location: Optional[str] = Field(
          None,
          description="Optional location context for location-specific searches (e.g., 'New York').",
      ),
  ) -> AgentResponse:
      """Use a specialized web search agent powered by OpenAI to find information on the internet."""
      try:
          agent = web_search_agent
          if location:
              agent = Agent(
                  name="Web Search Assistant",
                  instructions=web_search_agent.instructions,
                  tools=[WebSearchTool(user_location={"type": "approximate", "city": location})],
              )
  
          with trace("Web search agent execution"):
              result = await Runner.run(agent, query)
  
          return AgentResponse(
              response=result.final_output,
              raw_response={"items": [str(item) for item in result.new_items]},
          )
  
      except Exception as e:
          print(f"Error running web search agent: {e}")
          return AgentResponse(
              response=f"An error occurred while searching the web: {str(e)}", raw_response=None
          )

• src/agents_mcp_server/server.py:152-165 (helper)

  Defines the core web_search_agent Agent instance with specialized instructions and WebSearchTool, used by the handler.

  web_search_agent = Agent(
      name="Web Search Assistant",
      instructions="""You are a web search assistant. Your primary goal is to search the web for accurate,
      up-to-date information based on the user's query.
  
      Guidelines:
      1. Always use the web search tool to find information
      2. Cite your sources when providing information
      3. If information seems outdated or contradictory, acknowledge this
      4. Summarize information in a clear, concise manner
      5. For complex topics, break down information into digestible parts
      """,
      tools=[WebSearchTool()],
  )

• src/agents_mcp_server/server.py:143-150 (schema)

  Pydantic schema for the output of the web_search_agent tool (and other agents).

  class AgentResponse(BaseModel):
      """Response from an OpenAI agent."""
  
      response: str = Field(..., description="The response from the agent")
      raw_response: Optional[Dict[str, Any]] = Field(
          None, description="The raw response data from the agent, if available"
      )

• src/agents_mcp_server/server.py:319-323 (registration)

  Secondary registration of web_search_agent as a sub-tool ('search_web') within the multi_tool_agent for orchestration.

  tools.append(
      web_search_agent.as_tool(
          tool_name="search_web", tool_description="Search the web for information"
      )
  )

• src/agents_mcp_server/server.py:206-211 (helper)

  Helper code to create a location-specific variant of the web_search_agent when location parameter is provided.

  if location:
      agent = Agent(
          name="Web Search Assistant",
          instructions=web_search_agent.instructions,
          tools=[WebSearchTool(user_location={"type": "approximate", "city": location})],
      )